Prepare the branch before starting
Check out the feature branch and confirm it is clean. Run git status to verify no uncommitted changes exist. If changes remain, commit or stash them first. A clean working directory ensures the rebase begins from a known state without mixing unrelated edits into the replay process.
Fetch the latest main from the remote so the rebase target reflects current work. This step prevents rebasing against an outdated base that would require another rebase later. Updating the local view of main gives each replayed commit the most recent context available.
Review the branch history briefly with git log to understand the sequence of commits that will be replayed. This mental map helps anticipate where conflicts are likely to appear during the operation.
- git checkout feature-branch
- git fetch origin
- git status
Run the rebase command
Start the rebase with git rebase main. Git rewinds the branch to the common ancestor, applies each commit in order, and stops if a conflict appears. The replay mechanism takes the changes from each original commit and attempts to apply them sequentially onto the new base.
The output shows which commit is being applied. When a conflict occurs, Git prints the file names with conflict markers and pauses the process. At this point the working directory contains the partially applied state, allowing direct inspection of the exact lines that could not be merged automatically.
Observe any messages about which commit introduced the conflict. This information guides the decision on whether to edit the file, skip the commit entirely, or stop the rebase.
- git rebase main
Resolve a conflict at the current commit
Open the conflicted files and edit the sections between the markers. Keep the version that matches the intended change, then remove the markers. The goal is to produce a single coherent version of the file that incorporates the purpose of the commit being replayed.
After editing, stage the resolved files with git add. Do not commit yet; the rebase process manages the commit itself. Staging tells Git that the conflict for the current commit has been addressed and the replay can proceed to the next commit.
Optionally run git diff --check to confirm no conflict markers remain. This extra verification step reduces the chance of accidentally leaving markers that would cause build or review problems later.
- Edit files to remove conflict markers
- git add resolved-file.txt
- git diff --check (optional verification)
Continue, skip, or abort the rebase
Once all conflicts in the current commit are resolved, run git rebase --continue to apply the remaining commits. Repeat the resolution step if another conflict appears. Each iteration follows the same pattern of editing, staging, and continuing until the entire sequence finishes.
If the conflicting commit is no longer needed, use git rebase --skip. This drops the commit from the replayed history while allowing the rest of the branch to be updated. To abandon the entire operation and return the branch to its original state, run git rebase --abort. The abort option restores the branch exactly as it was before the rebase began, providing a safe exit when the conflicts prove too complex or the outcome is no longer desired.
- git rebase --continue
- git rebase --skip
- git rebase --abort
Finish and verify the result
After the rebase completes, the branch history shows a linear sequence of commits on top of the latest main. Run git log --oneline to confirm the order. The linear history makes it easier to follow the evolution of the feature without interleaved merge commits.
Test the branch locally before pushing. A rebase changes commit hashes, so any previously shared commits will appear as new work to collaborators. Running the test suite verifies that the resolved conflicts did not introduce functional regressions.
Compare the final state against the original branch using git diff to ensure the net changes remain as intended after all resolutions.
- git log --oneline -10
- Run tests on the rebased branch
When to choose merge instead
If the branch has already been pushed and others may have based work on it, create a merge commit instead. Merging preserves the original commit hashes and avoids rewriting shared history. The resulting graph shows both lines of development meeting at the merge point.
The choice between rebase and merge depends on team conventions and whether the branch is private or public. When history must remain unchanged for other contributors, merging provides a non-destructive way to incorporate updates from main.
Consider the long-term readability of the project history. A rebase produces a cleaner line of commits, while a merge records the exact moment integration occurred.