Selectively Accepting Upstream Changes During Git Rebase Conflicts

Branch Identifier Semantics in Git Rebase Operations

In Git rebase operations, the semantics of branch identifiers differ significantly from regular merge operations. When executing the git rebase main command to rebase the feature_x branch onto the current main branch, Git replays each commit from the feature_x branch on top of the main branch. During this process, if merge conflicts occur, Git redefines the meanings of ours and theirs.

According to the official Git documentation, in the rebase context:

• ours refers to the so-far rebased series, starting with the upstream branch (i.e., main branch)
• theirs refers to the working branch being replayed (i.e., feature_x branch)

This semantic reversal is crucial for understanding rebase conflict resolution. Many developers mistakenly assume that ours always represents the currently checked-out branch, but this assumption leads to incorrect conflict resolution decisions in rebase scenarios.

Correct Method for Selectively Accepting Upstream Branch Files

When encountering conflicts during rebase and deciding to accept specific files from the upstream branch (main), the correct operation sequence is as follows:

git checkout --ours foo/bar.java
git add foo/bar.java

Explanation of this command sequence:

• git checkout --ours foo/bar.java: In the rebase context, this command checks out the upstream branch (main) version of the foo/bar.java file, overwriting the conflicted version in the current working directory
• git add foo/bar.java: Marks the resolved file as resolved, informing Git that the conflict has been handled

Complete Rebase Conflict Resolution Workflow

To ensure comprehensive understanding, here is the standard workflow for handling rebase conflicts:

1. Initiate rebase operation: git rebase main
2. When conflicts occur, Git pauses the rebase process and displays the list of conflicted files
3. For files you want to completely accept from the upstream branch, execute: git checkout --ours <filename>
4. For files you want to keep from the working branch, execute: git checkout --theirs <filename>
5. For files requiring manual merging, edit the file content to resolve conflict markers
6. Add all resolved files to the staging area: git add <resolved_files>
7. Continue the rebase process: git rebase --continue

Common Errors and Solutions

Many developers encounter errors when attempting to directly reference branch files, as shown in the original question:

git checkout main:foo/bar.java
fatal: reference is not a tree: TS-modules-tmp:foo/bar.java

This error occurs because during rebase, branch references may be in a special state and cannot be accessed through conventional reference syntax. The correct approach is to use the --ours and --theirs identifiers, which are specifically maintained by Git in the rebase context and can reliably access the corresponding version of file content.

Best Practice Recommendations

Based on practical development experience, the following best practices are recommended:

• Before starting rebase, ensure the working directory is clean by using git status to confirm there are no uncommitted changes
• For complex rebase operations, consider using git rebase -i for interactive rebase to better control the replay order of commits
• When handling conflicts, prioritize using git checkout --ours and git checkout --theirs for clear file selections rather than manually editing each conflict
• After completing rebase, run test suites to verify code functionality integrity
• Consider using graphical tools like git mergetool to assist with complex conflict resolution

By mastering these techniques, developers can handle conflicts during Git rebase operations with greater confidence and efficiency, ensuring codebase cleanliness and project progress.