Complete Guide to Resolving "master rejected non-fast-forward" Error in EGit

Problem Analysis and Background

When using Eclipse's EGit plugin for Git operations, developers may encounter the "master rejected non-fast-forward" error. This typically occurs when attempting to push local commits to a remote repository, where Git detects that the remote branch contains new commits not present in the local branch. Git's default behavior is to reject non-fast-forward pushes to prevent overwriting history in the remote repository.

Root Cause

The fundamental cause of this error is a divergence between local and remote branch histories. After your initial successful push, if other collaborators have pushed new commits to the remote repository, or if you've made modifications to the same branch elsewhere, the remote branch becomes ahead of your local branch. Git requires you to merge remote changes locally before pushing to ensure code consistency.

Solution Steps

Here are detailed steps to resolve this issue in the EGit environment:

1. Open the "Git Repositories" view in Eclipse and ensure visibility of local repository and remote connections.
2. Locate the green left arrow icon representing fetch operation, right-click and select "Configure Fetch".
3. In the configuration dialog, verify the URI points to the correct remote repository address.
4. In the ref mappings section, click "Add" to specify the remote branch to fetch (typically "master").
5. Click "Save and Fetch" to execute the fetch operation, downloading the latest state of the remote branch.
6. Find the fetched remote branch (e.g., "origin/master") under "Remote Tracking" in the "Branches" folder.
7. Right-click the local branch (e.g., "master"), select "Merge", then choose the remote branch for merging.
8. Handle any merge conflicts using EGit's merge tools or manual file editing.
9. Commit the merge result to the local repository with an appropriate commit message.
10. Execute the push operation to send the merged local branch to the remote repository.

Code Examples and Explanation

The following equivalent Git command-line operations illustrate the underlying mechanisms:

# Fetch latest changes from remote repository
$ git fetch origin

# Check status of local and remote branches
$ git status

# Merge remote branch into current branch
$ git merge origin/master

# If conflicts occur, resolve and commit
$ git add .
$ git commit -m "Merge remote changes"

# Push the merged branch
$ git push origin master

In EGit, these operations are performed through the graphical interface, but understanding the corresponding Git commands helps master version control principles.

Preventive Measures and Best Practices

To minimize non-fast-forward push errors, consider these practices:

• Always fetch and pull before starting new work to ensure local and remote branch synchronization.
• Use git pull --rebase instead of simple git pull to maintain linear commit history.
• Establish clear branching strategies like Git Flow or GitHub Flow in team collaborations.
• Regularly run git log --oneline --graph --all to visualize branch history and detect divergences early.

Advanced Scenario Handling

In complex situations, forced push or branch reset might be necessary. However, these operations rewrite history and should only be used on personal branches or with team consensus:

# Force push (use with caution)
$ git push --force origin master

# Or use safer force push variant
$ git push --force-with-lease origin master

Force pushing overwrites remote branches and may cause collaboration issues, so it should be a last resort.

Conclusion

The "master rejected non-fast-forward" error is Git's crucial mechanism for protecting code integrity. Through EGit's graphical tools, developers can conveniently fetch remote changes, merge branches, and resolve conflicts. Understanding the version control principles behind this error not only solves immediate problems but also enhances team collaboration efficiency and code quality. Combining command-line tools for deeper Git learning is recommended to fully leverage distributed version control system advantages.