Git Branching Strategies: GitHub Flow, Trunk, Merge vs Rebase

What: branch off main and commit your feature work there. Why: isolating work keeps main releasable at every commit, and keeping the branch short-lived (hours to a couple of days, not weeks) is the single biggest factor in painless integration. The longer a branch lives, the more main moves under it and the worse the eventual merge becomes. Name the branch after the change, feature/api here, so its purpose is obvious in listings and pull requests.

In the sandbox, make a real change so the commit has content: add a users() function to api.py, then commit. Two or three small commits on the branch will make the graphs in step 04 much more instructive than one giant commit.

MAKE TWO SMALL COMMITS ON THE BRANCH

git switch -c feature/api
printf '\ndef users():\n    return ["taki", "sam"]\n' >> api.py
git commit -am "feat: add users endpoint"
printf '\ndef version():\n    return "0.1.0"\n' >> api.py
git commit -am "feat: add version endpoint"

Common mistake: doing the work on main and branching afterwards. If that happens, the fix is easy because branches are just pointers: git branch feature/api to mark the current commit, then git switch main and git reset --hard origin/main (or the earlier hash) to move main back. Verify with git log --oneline --graph --all that the commits sit on the feature branch, not main.

Naming note: pick a convention and stick to it, feature/<topic>, fix/<issue-id>, and chore/<task> cover nearly everything. Consistent prefixes let you filter branches with git branch --list "feature/*" and let CI or automation apply rules per branch type.

What: switch back to main and merge the feature branch with --no-ff (no fast-forward). Why: without that flag, when main has not moved since you branched, Git simply slides the main pointer forward, a "fast-forward", and the fact that a branch ever existed is erased from the graph. Forcing a merge commit keeps a visible record that this work arrived as one reviewed unit, which is exactly what teams using GitHub Flow want when they look back at history or need to revert a whole feature with a single git revert -m 1.

Git opens an editor for the merge commit message; the default Merge branch 'feature/api' is fine, or write something more descriptive like Merge branch 'feature/api': users and version endpoints. Save and close to complete the merge.

How to verify: git log --oneline --graph shows a branch-and-join shape: the merge commit on main with two parents, and the two feature commits on the side line. git show --no-patch --pretty=%P HEAD prints two parent hashes, confirming it is a true merge commit.

Common mistake: merging the wrong direction. It is always feature into main, done while standing on main. If you accidentally merged main into your feature branch instead, nothing is lost, the feature branch just contains main's commits, but do not confuse that with integration; main still does not have your work until you merge the other way.

What: instead of merging, replay the feature commits on top of the latest main. Why: a rebase rewrites the branch so it looks as if you started from today's main all along, no merge commits, just a straight line. Teams that value a readable, bisect-friendly history (and trunk-based teams especially) prefer this. The trade-off is that the original commits are replaced by new copies with new hashes, which is why rebase is reserved for local, un-pushed work.

To see the contrast in the sandbox, first undo the merge commit from step 02, then give main an independent commit of its own. That second part matters: without a new commit on main, the feature branch would already sit on main's tip and git rebase main would just report "up to date" without replaying anything, and the new-hashes check below would fail.

UNDO THE MERGE, ADVANCE MAIN, THEN REBASE

git switch main
git reset --hard HEAD~1          # undo the step-02 merge; safe, nothing pushed
printf '# API notes\n' > docs.md
git add docs.md && git commit -m "docs: add API notes"
git switch feature/api
git rebase main

FINISH THE INTEGRATION AFTER A REBASE

git switch main
git merge --ff-only feature/api

The --ff-only flag is the key detail: after a rebase, main can simply fast-forward to the replayed commits, and the flag makes Git refuse to do anything else, so if the rebase was incomplete, you get an error instead of an accidental merge commit.

How to verify: git log --oneline is a straight line with no merge commit, and the two feature commits have different hashes than before the rebase, proof they were replayed. If you want your old hashes back, git reflog lists every previous position of HEAD, and git reset --hard HEAD@{1} can undo the whole rebase.

What: inspect the graph each strategy produced. Why: the difference between merge and rebase is easiest to internalize visually. Run the comparison twice, once after a --no-ff merge, once after a rebase, and the shapes make the trade-off obvious: preserved context versus a clean line.

AFTER A MERGE: BRANCH-AND-JOIN GRAPH

$ git log --oneline --graph --all
*   d2e3f4a (HEAD -> main) Merge branch 'feature/api'
|\
| * c7d8e9f (feature/api) feat: add version endpoint
| * b4c5d6e feat: add users endpoint
|/
* a1b2c3d chore: initial commit

AFTER A REBASE: STRAIGHT LINE

$ git log --oneline --graph --all
* e8f9a0b (HEAD -> main, feature/api) feat: add version endpoint
* f0a1b2c feat: add users endpoint
* d4e5f6a docs: add API notes
* a1b2c3d chore: initial commit

How to interpret: in the merge graph you can still see that two commits arrived together as a unit; in the rebase graph you cannot, but every commit sits directly on main, which makes git bisect and blame archaeology simpler. Neither is "correct", the team picks one and applies it consistently.

For a mechanical check that goes beyond reading the graph, inspect the parent count of the tip commit. A merge commit has two parents; a rebased tip has exactly one:

COUNT PARENTS OF THE TIP COMMIT

git show --no-patch --pretty=%P HEAD | wc -w   # 2 = merge commit, 1 = linear

This one-liner is handy in scripts and CI, for example, a check that rejects direct commits to main can assert that every commit landing on main is a two-parent merge from a reviewed pull request.

What: practice the routine you will use daily: while your branch is open, main gains commits, and you need to incorporate them before integrating. Why: integrating a stale branch is where conflicts and broken builds come from. Syncing early and often keeps the final integration trivial, this is the entire philosophy behind short-lived branches and trunk-based development.

Simulate it: cut a fresh feature branch with one commit, feature/api was fully merged in step 03, so rebasing it again would be a no-op. Then, while the new branch is open, main gains a commit, a CI config file. Rebase the branch onto the updated main to incorporate it.

MOVE MAIN FORWARD, THEN SYNC THE FEATURE

git switch -c feature/auth main
printf 'token expiry: 15m\n' > auth.md
git add auth.md && git commit -m "feat: draft auth notes"
git switch main
printf 'name: ci\non: [push]\n' > ci.yml
git add ci.yml && git commit -m "ci: add workflow stub"
git switch feature/auth
git rebase main

Against a real remote the same routine is one command: git pull --rebase origin main while on your feature branch. Set git config --global pull.rebase true if you want that to be the default everywhere.

Common mistake: syncing with git merge main into the feature branch repeatedly. It works, but each sync adds a merge commit, and after a week the branch history is half merge noise. For a branch only you work on, rebase keeps it clean; reserve merge-syncs for shared branches.

What: deliberately create overlapping edits and walk through the resolution. Why: the first time you see CONFLICT during a rebase it looks like an error; it is actually Git pausing to ask you a question. Knowing the rhythm, edit, stage, continue, removes the fear. (The Merge Conflict Resolution lab goes deeper; here you only need the workflow in context.)

Trigger it: on main, change the health() return value to {"status": "healthy"} and commit; on a fresh feature branch off the old point, change the same line to {"status": "up"}. Rebasing the feature onto main now conflicts.

Open api.py, find the conflict markers, keep the lines you want, and delete the markers. Then stage and continue:

THE CONFLICT MARKERS GIT WRITES

<<<<<<< HEAD
    return {"status": "healthy"}
=======
    return {"status": "up"}
>>>>>>> 8b9c0d1 (feat: add users endpoint)

RESOLVE, STAGE, CONTINUE

# edit api.py, then:
git add api.py
git rebase --continue

How to verify: git status during the pause says interactive rebase in progress and lists unmerged paths; afterwards it says clean, and git log --oneline shows the replayed commit on top of main. If the rebase goes sideways, git rebase --abort returns the branch to exactly where it was before you started, it is always safe to bail out and retry.

What: delete feature branches once integrated, locally and on the remote. Why: stale branches are clutter that hides the branches that actually matter, and a merged branch has no unique information, its commits are reachable from main, so deleting it loses nothing. Keeping the branch list short is part of keeping main the single source of truth.

DELETE MERGED BRANCHES LOCALLY AND REMOTELY

git switch main
git branch -d feature/api          # safe delete: refuses if unmerged
git branch -D feature/auth        # force: the step-05 sync exercise branch, never merged
git push origin --delete feature/api
git fetch --prune                  # drop stale remote-tracking refs

Note the lowercase -d: it is the safe delete that refuses when the branch contains unmerged work. The uppercase -D forces deletion, useful, but check first with git log main..feature/api, which lists commits the branch has that main does not. If that output is empty, nothing is lost.

Common mistake: deleting the wrong branch. Recovery is straightforward if you act soon: git reflog (or the hash in the "Deleted branch ... (was e8f9a0b)" message) gives you the tip commit, and git branch feature/api e8f9a0b recreates the branch exactly where it was.

What: finish the lab by turning the decision into a short, explicit policy. Why: branching strategies fail by ambiguity, not by tooling, half the team rebasing and half merging produces the worst of both. A five-line policy in CONTRIBUTING.md (or the repo wiki) settles branch naming, integration method, and branch lifetime so nobody has to guess.

CONTRIBUTING.md WORKFLOW EXCERPT

## Branching workflow
- main is always releasable; all work happens on short-lived branches.
- Branch names: feature/<topic>, fix/<issue>. Lifetime: 2 days max.
- Sync daily with `git pull --rebase origin main`; never rebase pushed commits.
- Integrate via pull request with --no-ff merge; delete the branch after merge.
- main is protected: CI must pass and one review is required.

This particular policy is GitHub Flow with merge integration, a sensible default for a small web team. A trunk-based team would shorten lifetimes to hours and drop the merge commit; a GitFlow team would add develop and release branch rules. The point of the lab is not which policy you wrote, but that every line of it is something you have now done by hand.

How to verify: the policy is enforceable, not aspirational. GitHub branch protection rules (required reviews, required status checks) make the last line mechanical, the GitHub Actions lab covers wiring CI into that gate.