Three ways to join branches
The starting point: a feature branch left main, and while work went on in it, main got a commit too.
C ── D feature
/
A ── B ── E main
Merge. A new commit M with two parents. The history is honest: you can see the work went on in parallel. No old commit changes.
C ── D
/ \
A ── B ── E ── M main
Rebase. Commits C and D move on top of E and become new commits C′ and D′, with new hashes. The history is linear, as if the work started after E.
A ── B ── E ── C′ ── D′ feature (then main, by fast-forward)
Squash. All the branch’s commits fold into one new commit S. GitHub’s “Squash and merge” button does exactly this.
A ── B ── E ── S main
If nothing appeared in main during the work, merge doesn’t merge anything; it moves main forward — a fast-forward,
with no new commit.
Which to choose
| If… | Use | Why |
|---|---|---|
your own branch, not pushed yet, needs the fresh main |
git rebase main |
linear history; conflicts are resolved one commit at a time |
| the branch is already on GitHub, and others work in it | git merge main |
a rebase rewrites commits other people have |
a finished task goes back into main via a pull request |
squash or merge on GitHub | squash — one commit per task; merge — every step is visible |
git pull when both you and the server have new commits |
pull.rebase = true (~/.gitconfig block by block) |
your local commits go on top, no “Merge branch ‘main’ of …” commit |
A branch per task
Create a branch from a fresh main
git switch main git pull git switch -c traefik-timeouts # Switched to a new branch 'traefik-timeouts'Name it for the work:
traefik-timeouts,fix-crowdsec-hooks. A week latergit branchtells you what’s in it.Work and commit
The usual loop from Git from scratch: edit,
git diff,git add,git commit. Make as many commits as you like — a squash will fold them into one later.Bring in the fresh main
While you worked,
mainchanged. Move your commits on top:git fetch git rebase origin/main # Successfully rebased and updated refs/heads/traefik-timeouts.If the branch is already on GitHub and someone else works in it, use
git merge origin/maininstead of a rebase.Bring it back into main
Without a pull request, locally:
git switch main git merge --ff-only traefik-timeouts git push--ff-onlymeans fast-forward only: ifmainhas moved ahead, git refuses and you go back to step 3 instead of getting an accidental merge commit.Through GitHub:
git push, a pull request, the merge button. Then locally,git switch main && git pull.Delete the branch
git branch -d traefik-timeouts git push origin --delete traefik-timeouts # if it was on GitHubAfter a squash on GitHub,
-drefuses: the branch’s commits landed inmainunder a different hash (see “If it doesn’t work”).
Conflict
Both branches changed one line: in main the port became 9090, in feature 8080.
Read what git said
Auto-merging app.yml CONFLICT (content): Merge conflict in app.yml Automatic merge failed; fix conflicts and then commit the result.A rebase says the same, plus which commit didn’t apply and what to do next:
error: could not apply 7931637... feature port hint: Resolve all conflicts manually, mark them as resolved with hint: "git add/rm <conflicted_files>", then run "git rebase --continue". hint: You can instead skip this commit: run "git rebase --skip". hint: To abort and get back to the state before "git rebase", run "git rebase --abort".See which files are in conflict
git status # You have unmerged paths. # (fix conflicts and run "git commit") # (use "git merge --abort" to abort the merge) # # Unmerged paths: # (use "git add <file>..." to mark resolution) # both modified: app.ymlFix the file
With
merge.conflictStyle = zdiff3(~/.gitconfig block by block) the file holds three versions:name: site <<<<<<< HEAD port: 9090 ||||||| 217e8ca port: 80 ======= port: 8080 >>>>>>> feature workers: 2On top is the current branch (
HEAD), in the middle what the common ancestor had, at the bottom the incoming branch. The ancestor shows it: it was 80, and both sides changed it, each their own way. Decide which value is right, or combine the two. Leave oneport: …line and delete every<<<<<<<,|||||||,=======,>>>>>>>marker.To take one side whole without editing by hand:
What you take During a merge During a rebase the version of the branch you’re on git checkout --ours app.ymlgit checkout --theirs app.ymlthe version of the incoming branch git checkout --theirs app.ymlgit checkout --ours app.ymlIn a rebase the sides are flipped: git stands on
mainand applies your commits one by one, so “ours” ismainand “theirs” is your commit.Mark it and continue
grep -n '^<<<<<<<\|^>>>>>>>' app.yml || echo "no markers" git add app.yml git commit # during a merge git rebase --continue # during a rebase — to the next commit or the endIf you got the resolution wrong or changed your mind —
git merge --abortorgit rebase --abort: everything goes back to how it was before you started.
If it doesn’t work
error: cannot rebase: You have unstaged changes. error: Please commit or stash them.
- Cause
- There are uncommitted edits in the working directory, and a rebase switches files.
- Fix
git stash, rebase,git stash pop— or once,rebase.autoStash = true(~/.gitconfig block by block).
CONFLICT (content): Merge conflict in app.yml
- Cause
- Both branches changed the same lines, and git doesn’t know whose edit is right.
- Fix
- Work through the steps under “Conflict”. Changed your mind —
git merge --abortorgit rebase --abort, and everything goes back as it was.
During a rebase --ours took the wrong version
- Cause
- In a rebase the sides swap: “ours” is the branch you’re moving onto (
main), “theirs” is your commit being moved. - Fix
- During a rebase, yours is
git checkout --theirs app.yml; during a merge, yours is--ours.
error: the branch 'feature' is not fully merged
- Cause
git branch -drefuses to delete a branch with commits the current branch lacks. After a squash merge on GitHub every branch looks like that: its commits are inmainunder different hashes.- Fix
- Check that the edits are in
main(git log main --oneline -5) and delete withgit branch -D feature.
After a rebase git push is rejected: ! [rejected] … (non-fast-forward)
- Cause
- The rebase rewrote commits that were already on GitHub: they have new hashes.
- Fix
- If the branch is only yours —
git push --force-with-lease(push --force-with-lease instead of --force). If others work in it — don’t rebase, only merge.
How to check
The history after merging, as a graph:
git log --oneline --graph -8
# * 3e2d1c (HEAD -> main, origin/main) traefik: readTimeout 300s
# * 9f8e7d traefik: read timeout moved to its own block
# * a1b2c3 crowdsec: forward hook
A straight line without |\ and |/ means a rebase or a fast-forward; a fork with a merge star means a merge. No
conflict markers left in the files:
git grep -n '^<<<<<<< ' || echo "clean"
# clean