git merge: merging branches

git merge <branch> merges the branch you name into the branch you are standing on.

The order matters more than anything else here. First move to the branch you are merging into, and only then name the branch you are taking work from. The work on feature-x is done and belongs in main, so you stand on main:

$ git switch main
Switched to branch 'main'
$ git merge feature-x

From there two things can happen, and git picks between them on its own.

Fast-forward versus a merge commit

The first outcome is a fast-forward. While you worked on your branch, nobody committed anything to main. There is nothing to combine: git simply moves the main pointer forward to where feature-x stands.

$ git merge feature-x
Updating a01b646..e07e156
Fast-forward
 notes.txt | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 notes.txt

The second outcome is an ordinary merge. main gained commits of its own in the meantime, the histories diverged, and git combines the changes from both sides into a separate merge commit with two parents:

$ git merge feature-x
Merge made by the 'ort' strategy.
 z.txt | 1 +
 1 file changed, 1 insertion(+)

Before that, an editor opens with a prepared message, Merge branch 'feature-x'. Most of the time you leave it as it is: save and close. The word ort is the name of the merge algorithm, and you never need to touch it.

The --no-ff flag forbids the fast-forward and writes a merge commit even where git would have gone without one. That leaves a visible mark in the history: a branch was here, and it held this many commits. Plenty of teams require it for every branch.

$ git merge --no-ff feature-x     # always create a merge commit

When the merge stops

If both branches changed the same line in different ways, git stops and asks you to pick. That is a merge conflict, and it is routine. You can work through it by hand, or you can call the whole thing off:

$ git merge --abort               # put the repository back the way it was

The command only works while the merge is unfinished. After a successful merge it answers fatal: There is no merge to abort (MERGE_HEAD missing)., and what you undo then is the commit itself, with git revert.

Common mistakes

Merging backwards. Running git merge main while standing on feature-x pulls main into your branch, not the other way round. Nothing is broken, but main gets nothing out of it. Check the On branch ... line in git status before every merge.

The answer Already up to date. means every commit of the named branch is in the current one. That is not an error: there is nothing to merge.

Where this is in the book

Chapter 5. Branches: parallel versions of a project shows both merge outcomes and draws the fork with git log --graph --oneline.

To practise it by hand, open the Sandbox: a real terminal with git and step checks.