Branches and merging

Mei has asked for a loyalty tracker: customers earn a point for every whole dollar they spend, move up through the Bean, Roast and Reserve tiers and get every tenth drink free. Sam takes the job. It will take two weeks, and for most of that time the code will be half-finished and broken. Meanwhile Jordan must keep ridgeline.py working for the staff, fixing bugs as they come in. If both of them commit to the same line of history, Sam's half-finished loyalty code lands in the tool the café uses every morning. Branches let each line of work develop separately and come together only when it is ready.

This lesson explains what a branch is in Git, how to create branches and move between them, the two ways Git merges one branch into another, how Git finds the common starting point of two branches, how to name branches and which branching strategies teams use.

What a branch is

In Git, a branch is nothing more than a movable label that points to a commit. The main branch created by git init is a label named main that points to the newest commit on the main line of work. When you make a new commit on a branch, Git moves that branch's label forward to the new commit. Creating a branch just creates a new label pointing at the current commit, which is why branches in Git are instant and cost almost nothing, however large the project.

Git also keeps a special label named HEAD that records where you are: usually HEAD points to a branch name, which points to a commit. When you switch branches, Git moves HEAD to the other branch and updates the files in your working tree to match that branch's newest commit. The next commit you make then extends whichever branch HEAD points to.

> git branch
* main
> git switch -c loyalty
Switched to a new branch 'loyalty'
> git branch
* loyalty
  main
> # ... write loyalty.py, commit twice ...
> git log --oneline --graph --all
* 3c81f0a (HEAD -> loyalty) Add tier calculation
* 9b44e21 Add points for each whole dollar
| * d27aa90 (main) Fix low-stock threshold
|/
* a41c9e2 Add low-stock report command

git switch -c creates a branch and switches to it in one step; git switch on its own moves to an existing branch. Older tutorials use git checkout for both, which still works but does several unrelated jobs, so the newer git switch and git restore commands are clearer. git log --oneline --graph --all draws the history of every branch as text, with the asterisks showing commits and the lines showing how branches split and join.

Switching branches changes the files on disk. If Jordan switches from main to loyalty, loyalty.py appears in the working tree; switching back makes it disappear again, because main does not have it. Git refuses to switch if you have uncommitted changes that the switch would overwrite, to protect your work. Commit the changes first, or set them aside temporarily with git stash, which saves them and cleans the working tree, and bring them back later with git stash pop.

Two ways to merge

When the loyalty feature is finished, its commits need to join main. git merge does this: while on main, git merge loyalty brings in the work from the loyalty branch. Git does it in one of two ways, depending on the shape of the history.

If main has not moved since loyalty was created, every commit on main is already part of loyalty's history. Git can simply slide the main label forward to loyalty's newest commit. This is a fast-forward merge: no new commit is made, and history stays a straight line. If main has moved on, as in the figure where Jordan's fix C3 was committed after the branch split, the two lines have each gained commits the other lacks. Git then makes a merge commit, a new commit with two parents, whose snapshot combines the changes from both branches.

> git switch main
> git merge loyalty
Merge made by the 'ort' strategy.
 src/ridgeline/loyalty.py | 64 ++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)
> git log --oneline --graph
*   e5f1b07 (HEAD -> main) Merge branch 'loyalty'
|\
| * 3c81f0a (loyalty) Add tier calculation
| * 9b44e21 Add points for each whole dollar
* | d27aa90 Fix low-stock threshold
|/
* a41c9e2 Add low-stock report command
> git branch -d loyalty
Deleted branch loyalty (was 3c81f0a).

To make the merge commit, Git performs a three-way merge. It compares three snapshots: the newest commit on each branch and their merge base, the most recent commit they have in common. A change that appears on only one side, compared with the merge base, is taken from that side. Only when both sides changed the same lines differently does Git stop and ask a person to decide, which is a merge conflict and the subject of lesson 7. After a successful merge, the branch label is no longer needed, and git branch -d deletes it; the commits remain in history.

The listings below model Git's history with a dictionary that maps each commit to the list of its parents. That is close to how Git stores it: each commit records its parents' hashes, and everything else is worked out by following those links.

parents = {
    'C1': [], 'C2': ['C1'], 'C3': ['C2'],     # main
    'L1': ['C2'], 'L2': ['L1'],               # loyalty, branched at C2
}

def ancestors(commit):
    seen, stack = set(), [commit]
    while stack:
        c = stack.pop()
        if c not in seen:
            seen.add(c)
            stack.extend(parents[c])
    return seen

print(sorted(ancestors('L2')))
print(sorted(ancestors('C3')))
print('C2 is an ancestor of L2:', 'C2' in ancestors('L2'))
print('C3 is an ancestor of L2:', 'C3' in ancestors('L2'))

['C1', 'C2', 'L1', 'L2']
['C1', 'C2', 'C3']
C2 is an ancestor of L2: True
C3 is an ancestor of L2: False

def ancestors(commit):
    return {commit}

def can_fast_forward(target_tip, branch_tip):
    return False

print(can_fast_forward('C3', 'X1'))

Finding the merge base

The merge base is the newest commit that both branches contain. For main at C3 and loyalty at L2, the commits they share are C1 and C2, and the newest of those is C2, where loyalty branched off. Git uses it as the reference point for the three-way merge, and git merge-base main loyalty prints it. Finding it is a matter of working out each branch's ancestors and picking the shared commit that comes latest.

def merge_base(a, b):
    # ancestors(commit) is already defined for you
    return None

print(merge_base('C3', 'L2'))

Naming branches

Branch names should say what the work is, so that a list of branches reads like a list of tasks in progress. Many teams use a prefix for the kind of work followed by a short description in lowercase with hyphens: feature/loyalty-points, fix/rounding-daily-totals, docs/install-guide. Some add the issue number, as in fix/14-rounding. Keep names short, because you will type them often, and delete branches once they are merged so the list stays meaningful.

Git itself forbids some names. A branch name cannot contain spaces, two consecutive dots, a tilde, a caret, a colon, a question mark, an asterisk, an opening square bracket or a backslash; it cannot begin with a hyphen, end with a slash or a dot, or end with .lock; and no part between slashes can begin with a dot. The command git check-ref-format --branch checks a name against these rules. The rules exist because those characters have special meanings in Git commands, such as the two dots that name a range of commits.

def valid_branch(name):
    return ' ' not in name

for n in ['feature/loyalty-points', 'fix rounding', 'feature/.hidden']:
    print(n, valid_branch(n))

Branching strategies

Teams agree on how they use branches, and three strategies are common. In GitHub flow, main is always ready to release; every piece of work happens on a short-lived branch, which is merged into main through a pull request after review, as lesson 6 describes. In trunk-based development, everyone integrates small changes into main, the trunk, at least daily, with branches lasting hours rather than weeks and unfinished features hidden behind settings called feature flags. In Git flow, long-lived develop and main branches are combined with feature, release and hotfix branches, a heavier process suited to software released in numbered versions on a fixed schedule.

For a small team like Ridgeline's, GitHub flow is the natural choice: main always works, each feature or fix gets its own branch, and branches are merged as soon as the work is reviewed. Whatever the strategy, the same principle holds: the longer a branch lives apart from main, the more main changes underneath it and the harder the eventual merge. Merge often, or bring main's latest changes into your branch often, and keep branches small.