Git Workflows,
branching without the chaos.

1 · Orientation: a workflow is a contract, not a tool

Every team that shares a repository already has a git workflow — written down or not. The question is never "do we have one?" but "is ours deliberate, and does it fit how we ship?"

Git itself ships with almost no opinion about how you organize work. It gives you commits, branches, merges, tags, and a remote protocol. A workflow is the set of rules a team layers on top: which branch is sacred, where new work starts, how it gets reviewed, how it reaches production, and what the resulting history should look like. The four workflows in this guide are simply four common, named answers to those questions.

The four decision axes

Almost every "which workflow?" debate collapses onto four axes. Memorize these; the decision matrix in §11 is built directly on them.

How to use this guide

Read §2–§6 once; they are the engine every workflow is built from. Then study each workflow in §7–§10 — each is self-contained with a topology diagram, the real commands, pros and cons, and a throwaway-repo lab. Use §11 when you must pick, §12 when you must operationalize the choice, and §14 to practice all four end to end. Treat the capstone and per-workflow labs as the real test — reading about merging is not the same skill as merging.

2 · Prerequisite floor: what you already need

This guide assumes you can already move around a repository on your own. If any item below is shaky, fix it first — workflows will not make sense until the primitives do.

Hard prerequisites

• Commits and history: stage with git add, commit with git commit, read git log and git diff.
• Branches: create (git switch -c), switch (git switch), list (git branch), delete (git branch -d).
• Merging: merge one branch into another and read the result; know that a merge can create a merge commit.
• Remotes: what origin is, the difference between git fetch, git pull, and git push, and how to set an upstream.

Soft prerequisites (helpful)

• Having opened a pull request or merge request at least once.
• Having seen a merge conflict and at least attempted to resolve it.
• A vague sense of what a "tag" or "release" is.

Just-in-time prerequisites

Interactive rebase, conflict markers, and the ours/theirs vocabulary are introduced in §6, exactly when you need them — not before.

Self-assessment

Answer each before opening it. If you miss more than two, revisit the prerequisites before continuing.

3 · The DAG model: commits, pointers, and why branches are cheap

Every workflow is easier to reason about once you stop picturing branches as "lines" and start picturing them as movable labels on a graph of immutable commits.

Commits are immutable; branches are labels

A commit is a snapshot plus metadata (author, message, timestamp) plus a pointer to its parent (or parents). A commit's hash is the SHA-1 of all of that content. Change anything — even the message — and you get a different commit with a different hash. The old commit still exists in your object store until garbage collection; that is what makes recovery possible.

A branch is none of that. A branch is a tiny movable pointer — a file containing one hash. main is just "the name of the commit we currently call main." Moving a branch is free, which is why creating and deleting branches is trivial and why short-lived branches are viable.

The graph is a DAG

Commits form a directed acyclic graph (DAG). Each commit points back to its parent; merge commits point to two parents. HEAD is a special pointer that says "where you are now" — usually it points to a branch, which points to a commit. (Detached HEAD means HEAD points directly at a commit instead of a branch.)

# Two commits on main, then a feature branch diverges:
#
#   C0 ── C1 ────────── C4   (main)
#             \
#              C2 ── C3       (feature)
#
# HEAD -> feature -> C3 ;  main -> C4
git log --graph --oneline --all --decorate

What merging and rebasing really do

The whole rest of this guide is choosing which of those operations happen, when, and on which branches. That is literally what a workflow is.

4 · Merge models: the engine underneath every workflow

Before the named workflows, you must internalize the four ways a branch can land. Most heated "merge vs rebase" arguments are people talking past each other because they never separated these.

The four models

Same situation, four outcomes

Start with main at C1 and a feature branch with two commits C2, C3. Here is the resulting main history under each model:

# Starting point
#   C0 ── C1            main
#           \
#            C2 ── C3   feature

# 1) Fast-forward  --ff-only
#   C0 ── C1 ── C2 ── C3        main
#   (no merge commit; feature label absorbed)

# 2) Merge commit  --no-ff
#   C0 ── C1 ─────── M          main
#           \       /
#            C2 ── C3
#   (M is the merge commit with two parents)

# 3) Squash
#   C0 ── C1 ── S               main
#   (S holds the combined diff of C2+C3; C2,C3 dropped from main)

# 4) Rebase + ff
#   C0 ── C1 ── C2' ── C3'      main
#   (C2',C3' are replayed copies with new hashes; linear)

Decoupling deploy from release: feature flags

One idea appears in modern workflow debates constantly: you do not have to release a feature when you merge it. With a feature flag, half-finished code can merge to the main line behind a default-off switch and be turned on later, independently of any deploy. This single technique is what makes trunk-based development viable for large teams — and it loosens the grip of long-lived feature branches everywhere.

5 · Pull requests: the integration gate every modern workflow shares

Whatever the workflow, on a hosted platform the moment of integration is almost always a pull request (GitHub/Bitbucket) or merge request (GitLab). Understanding what it is and is not prevents a lot of confusion.

A pull request (PR) is not a git concept — git has no PR command. It is a feature of the hosting platform: a proposed merge of one branch into another, bundled with a discussion thread, a diff view, continuous-integration status, and review approvals. Under the hood, finishing a PR just performs one of the four merges from §4 on the server.

What a PR configures

Review etiquette that transcends the workflow

• Small PRs. A 50-line PR gets a careful review; a 500-line PR gets a rubber stamp. Workflow choice does not change this — but trunk-based's short branches make it the default.
• Every commit on a feature branch should ideally build if you use rebase or merge-commit (not squash) integration — otherwise git bisect lands on broken commits.
• Keep the base fresh. Rebase or merge main into your branch before opening to shrink the final integration diff and catch conflicts early.

6 · Rebase and conflict survival (just-in-time refresher)

Every workflow produces conflicts eventually. This section gives you the minimum mechanics to survive them and the one rule that prevents most rebase disasters.

What rebase does, precisely

git rebase <base> takes the commits that are on your current branch but not on <base>, sets your branch aside, moves its tip to <base>, then replays each saved commit one at a time. Each replayed commit becomes a new commit with a new hash. The history reads as if you had started from the new base all along.

# Before
#   C0 ── C1 ── C2        main
#           \
#            A ── B       feature
#
# git switch feature
# git rebase main
#
# After: A' and B' are replays (new hashes), tip now on C2
#   C0 ── C1 ── C2        main
#                \
#                 A' ── B'  feature

Conflicts and how to read them

A conflict happens when two branches change the same lines and git cannot combine them automatically. Git pauses and writes conflict markers into the file:

def greeting():
<<<<<<< HEAD
    return "hello"        # your current branch (HEAD)
=======
    return "howdy"        # the commit being merged/replayed
>>>>>>> feature

Edit the file to the correct final content (removing all markers), then continue. The flow differs only slightly between merge and rebase:

Recovery net

If a merge or rebase goes sideways, git reflog records where every ref has been. You can almost always recover by checking out or resetting to a reflog entry. ORIG_HEAD conveniently records your position before the last merge/reset.

7 · GitHub Flow — the simplest model that works

One immortal branch (main), short-lived feature branches, a pull request, and a merge. That is the entire model. It is the default at most modern web companies for a reason.

The rules

• main is always deployable. Anything in main is, or can immediately be, in production.
• Branch off main for anything: feature/x, fix/y, chore/z.
• Open a pull request early; get review; keep the branch short-lived (hours to a few days).
• When approved and CI is green, merge into main. Deploy from main.
• Delete the branch. No develop, no release branches.

Topology

main    C0 ── C1 ── M1 ── M2 ── M3   (always deployable)
                 \   /   \   /
feature           F1      F2              (short-lived, deleted after merge)

The real loop

git switch main
git pull --ff-only            # start from a fresh main
git switch -c feature/dark-mode

# ... make changes, commit ...
git commit -am "Add dark mode"

git push -u origin feature/dark-mode
# open the PR in your host; get review; CI green

# after merge (server side), clean up:
git switch main
git pull --ff-only
git branch -d feature/dark-mode

Pros

• Simple. One integration branch. New people understand it in minutes.
• Few moving parts. No release/hotfix branch ceremony to learn.
• Deploys continuously. Nothing between "merged" and "shipped" but a deploy button.
• Short branches → fewer conflicts. Integration happens constantly.

Cons

• main must be always-releasable. This is load-bearing: it demands strong CI and the discipline to keep broken code out. Without it, the model breaks.
• No built-in release management. No formal "release 2.3" concept; versioning and changelogs are an add-on.
• Awkward for multiple supported versions. If you must patch v1 and v2 simultaneously, there is no structure for it.
• Rolled-back deploys need care. A bad merge means redeploying the previous main or reverting — there is no separate production branch to promote from.

Use it when you deploy continuously (web apps, SaaS), have trustworthy CI, and support essentially one live version. Avoid it when you ship versioned, installed artifacts or must maintain several old releases.

# Lab 0 builds the playground. Run it once, then:
git switch -c feature/dark-mode
printf 'theme=dark\n' >> app.conf
git add app.conf
git commit -m "Add dark mode option"

# simulate the PR merge (server-side, no-ff) locally:
git switch main
git merge --no-ff feature/dark-mode -m "Merge dark mode"
git tag -a v0.2.0 -m "Dark mode release"   # optional version marker
git branch -d feature/dark-mode
git log --graph --oneline --all

8 · Git Flow — structure for versioned releases

Vincent Driessen's 2010 "successful Git branching model." Five branch types, explicit release and hotfix tracks, tags on production. It is the heavyweight champion — powerful for shipped software, overkill for a website.

The five branch types

Topology

main      C0 ──────────────── R ────────── H ──   (tagged v1.0, v1.0.1)
             \                / \          / \
develop      D1 ── D2 ── D3 ──   ── D4 ──     ── D5
                  \      /                \
feature            F1 ──┘                  (next features)

Features accumulate on develop. When a release is due, a release/* branch freezes, gets last polish, then merges to main (tagged) and back to develop. A production bug spawns hotfix/* off main, fixes it, merges to main (tagged) and back to develop so the fix isn't lost.

Pros

• Explicit release management. Clear "we are shipping 2.0" branch; tags mark exactly what shipped.
• Production vs next-release separation. main mirrors production; develop holds the future.
• First-class hotfix path. Patch production without waiting for the next release train.
• Suits installed/versioned software where artifacts are shipped and later patched in place.

Cons

• Complex. Five branch types, two back-merge points per release/hotfix — easy to get wrong.
• Heavy merge overhead. Lots of no-ff merges; the graph gets busy.
• Overkill for continuously-deployed web apps. Driessen himself later noted the model is overkill for teams that deploy many times a day; GitHub Flow or trunk-based fits better there.
• Long-lived develop can drift from main, making releases surprisingly large.

# from Lab 0 repo, on main
git switch -c develop

# feature → develop
git switch -c feature/login develop
printf 'login=true\n' >> app.conf
git commit -am "Implement login"
git switch develop
git merge --no-ff feature/login -m "Merge feature/login"
git branch -d feature/login

# release → main (tag) AND develop
git switch -c release/1.0 develop
printf 'version=1.0.0\n' > version.txt
git commit -am "Bump version 1.0.0"
git switch main
git merge --no-ff release/1.0 -m "Release 1.0.0"
git tag -a v1.0.0 -m "Release 1.0.0"
git switch develop
git merge --no-ff release/1.0 -m "Back-merge release/1.0 into develop"
git branch -d release/1.0

# hotfix off main → main (tag) AND develop
git switch -c hotfix/1.0.1 main
printf 'patch=security\n' >> app.conf
git commit -am "Critical security fix"
git switch main
git merge --no-ff hotfix/1.0.1 -m "Hotfix 1.0.1"
git tag -a v1.0.1 -m "Hotfix 1.0.1"
git switch develop
git merge --no-ff hotfix/1.0.1 -m "Back-merge hotfix into develop"
git branch -d hotfix/1.0.1
git tag --list

9 · Trunk-based development — integration as the heartbeat

Everyone integrates to one branch (main/trunk) frequently, with branches that live hours to a couple of days at most. Scale comes from small changes, fast review, strong CI, and feature flags — not from elaborate branch topology.

The rules

• main (or trunk) is the single integration line and is always green.
• Feature branches are short-lived — ideally less than a day, rarely more than three. Small, frequently merged changes.
• Every merge is gated by CI; broken builds are the top priority to fix or revert.
• Feature flags let incomplete-but-safe code merge and hide behind a switch, decoupling merge from release.
• History is kept linear — squash or rebase merges are conventional.

Topology

main   C0 ── C1 ── C2 ── C3 ── C4 ── C5 ── C6   (one green line)
            \    /\    /\    /
short         F0   F1    F2   (each <1 day, squash-merged, deleted)

Pros

• Minimal integration pain. Branches live so briefly that conflicts are tiny and rare.
• Fast feedback. Changes reach shared, tested code in hours.
• Scales to huge teams — used at Google, Meta, and others — provided CI and tooling are excellent.
• One clean line of history; bisects and reverts are trivial.

Cons

• Demands discipline and automation. Weak CI kills it: one bad merge breaks everyone within hours.
• Feature flags become mandatory infrastructure, with their own complexity and debt if unmanaged.
• Unnatural for multiple supported versions. Backporting fixes across old lines is not its strength — you'd add release branches on top.
• Culture shift. Teams used to week-long feature branches must learn to slice work small.

# from Lab 0 repo, on main (the trunk)
git switch -c add-flag
printf 'feature_x=on   # flag-gated, off in prod config\n' >> app.conf
git commit -am "Implement X behind flag"

# squash-merge keeps main linear; one commit per change
git switch main
git merge --squash add-flag
git commit -m "Add feature X behind flag"
git branch -D add-flag          # -D, not -d: see note

git log --oneline

10 · GitLab Flow — environment branches between you and production

GitLab's model tries to keep GitHub Flow's simplicity while restoring a sane path from "merged" to "deployed." The signature idea: environment branches that track what is actually running in each environment.

The rules (environment-branch variant)

• main (or master) is the source of truth where feature branches merge — the "latest" code.
• Downstream environment branches — e.g. pre-prod, production — represent what is deployed in each place.
• Code flows strictly downstream: main → pre-prod → production. You promote by merging upstream into downstream, never by cherry-picking forward.
• A production hotfix branches off production, merges back to production, and is cherry-picked back to main so the fix isn't lost.

Topology

main        C0 ── C1 ── C2 ── C3 ── C4 ── C5 ── (latest; feature merges land here)
              \    \    \    \
pre-prod       P1 ── P2 ── P3 ── P4 ───────────── (what's in staging)
                              \
production                     Q1 ── Q2 ───────── (what's actually live)

# hotfix off production flows back to main via cherry-pick
production  ── H ──
main           ... cherry-pick H ...

Pros

• Traceability. production literally is what is deployed — no guessing what shipped.
• Simpler than Git Flow. No develop or release/* ceremony; just environment branches.
• Suits staged deployment pipelines where you want explicit gates between environments.
• Release-branch variant exists too: for installed software, stable branches per release get cherry-picked bugfixes — Git Flow's release idea without its full weight.

Cons

• Cherry-pick drift. Backporting hotfixes to main by hand creates duplicate commits and can drift over time.
• production can become a bottleneck if promotions are manual and infrequent — it lags main arbitrarily.
• More branches than GitHub Flow, so a bit more to keep straight; merges flow one direction only, which must be enforced.
• Environment-branch count grows with each deployment target (staging, UAT, prod, regional prods).

# from Lab 0 repo, on main
git switch -c pre-prod main
git switch -c production pre-prod     # production starts behind main

# feature merges to main
git switch -c feature/billing main
printf 'billing=v2\n' >> app.conf
git commit -am "Rewrite billing"
git switch main
git merge --no-ff feature/billing -m "Merge billing"
git branch -d feature/billing

# promote downstream: main -> pre-prod -> production
git switch pre-prod
git merge --no-ff main -m "Promote to pre-prod"
git switch production
git merge --no-ff pre-prod -m "Promote to production"

# hotfix on production, then cherry-pick back to main
git switch -c hotfix/prod-fix production
printf 'fix=1\n' >> app.conf
git commit -am "Production hotfix"
git switch production
git merge --no-ff hotfix/prod-fix -m "Apply prod hotfix"
git switch main
git cherry-pick hotfix/prod-fix
git branch -D hotfix/prod-fix     # -D: original hotfix isn't on main (cherry-pick = new hash)
git log --graph --oneline --all

11 · Decision matrix: choosing the right workflow

There is no universally best workflow — only the one that fits your release cadence, team size, deployment topology, and CI maturity. This matrix collapses the four axes from §1 onto the four models.

At a glance

Recommendation by situation

A decision walk

These models also compose. It is common to run trunk-based on main and add release branches for the few supported versions you must patch — a hybrid of trunk-based and Git Flow's release idea. Pragmatism beats purity.

12 · The team-process layer: making a workflow stick

Choosing a workflow is half the job. The other half is the policy and automation that make it real: branch protection, required checks, code ownership, and versioning conventions. Without these, the workflow is a suggestion.

Branch protection / rulesets

All major hosts let you make a branch (usually main) protected: direct pushes are blocked, merges require a PR, and certain conditions must be met. GitHub calls these rulesets (formerly branch-protection rules); GitLab calls them protected branches.

CODEOWNERS — automatic review routing

A CODEOWNERS file maps paths to the people or teams responsible for them. When a PR touches those paths, the host automatically requests their review — and with "require review from code owners" enabled, their approval becomes mandatory. It scales review across a large repo without a gatekeeper.

# .github/CODEOWNERS (GitHub)  /  CODEOWNERS (GitLab, repo root)
# Each line: path pattern  owner(s)
/src/payments/    @payments-team
/src/auth/        @security-team @alice
/docs/            @docs-team
*.md              @docs-team
/                 @lead-developers   # default fallback

Conventional commits and semantic versioning

Pairing a workflow with a commit-message convention makes releases and changelogs automatable. Conventional Commits prefix messages with a type; SemVer derives the version bump from those types.

feat: add dark mode               # → MINOR bump (1.2.0)
fix: correct tax calculation      # → PATCH bump (1.2.1)
feat!: redesign API               # → MAJOR bump (2.0.0)  (! = breaking)
chore: bump dependencies          # → no release
docs: update README               # → no release

Tags and releases

• Annotated tags (git tag -a v1.2.0 -m "Release 1.2.0") carry a message, tagger, and date — recommended for releases.
• Lightweight tags (git tag v1.2.0) are just a pointer; fine for ephemeral marks.
• Tags are not pushed automatically — git push origin v1.2.0 (or --tags) ships them.

13 · Anti-patterns and failure modes

Most workflow pain is not from picking the wrong model — it is from violating the model's assumptions. These are the recurring ways teams get hurt.

14 · Capstone lab: run all four on one repo

A single cumulative lab. You build a real shared repository with a bare remote and two "teammates," run GitHub Flow end to end, cut a Git Flow release, and finish with a trunk-based cycle. No GitHub account needed — the bare repo is the remote, and "merging a PR" is a local fetch-and-merge.

cap_dir="$(mktemp -d)/wf-capstone"
mkdir -p "$cap_dir" && cd "$cap_dir"

# bare repo = the shared "server"
git init --bare origin.git

# alice bootstraps the project
git clone origin.git alice
cd alice
git switch -c main
printf '# Capstone App\n' > README.md
printf 'theme=light\nversion=0.1.0\n' > app.conf
git add README.md app.conf
git config user.name "Alice" && git config user.email "alice@example.invalid"
git commit -m "Initial commit"
git push -u origin main
cd ..

# bob clones the now-populated remote
git clone origin.git bob
cd bob
git config user.name "Bob" && git config user.email "bob@example.invalid"

# --- in bob/ ---
git switch -c feature/search
printf 'search=on\n' >> app.conf
git commit -am "Add search"
git push -u origin feature/search

# --- in alice/ ---  (Alice fetches the PR branch and merges it)
cd ../alice
git fetch origin
git switch main
git merge --no-ff origin/feature/search -m "Merge search (approved)"
git push origin main
git push origin --delete feature/search   # clean up the merged branch

# --- back in bob/ ---  (Bob syncs the integrated main)
cd ../bob
git switch main
git pull --ff-only
cat app.conf        # should now contain search=on

# --- in alice/ ---
git switch -c develop
git switch -c release/1.0 develop
printf 'version=1.0.0\n' > version.txt
git add version.txt
git commit -m "Bump version 1.0.0"

git switch main
git merge --no-ff release/1.0 -m "Release 1.0.0"
git tag -a v1.0.0 -m "Release 1.0.0"
git switch develop
git merge --no-ff release/1.0 -m "Back-merge release/1.0 into develop"
git branch -d release/1.0

git push origin main develop
git push origin v1.0.0

# --- in bob/ ---  (Bob receives the new branches + tag)
cd ../bob
git fetch origin --tags
git branch --track develop origin/develop 2>/dev/null || true
git switch main && git pull --ff-only
git tag --list          # v1.0.0 present

# --- in bob/ ---  switch to trunk-style: develop is retired, main is the trunk
git switch main
git pull --ff-only
git switch -c add-flag
printf 'feature_x=on   # flag-gated\n' >> app.conf
git commit -am "Implement X behind flag"

git switch main
git merge --squash add-flag
git commit -m "Add feature X behind flag"
git branch -D add-flag
git push origin main

# --- in alice/ ---  (Alice pulls the linear history)
cd ../alice
git switch main
git pull --ff-only
git log --oneline --graph --all
cd ../bob

15 · Troubleshooting playbook

Five-second pre-flight before any integration

1. Where am I? git status, current branch, clean tree?
2. What will move? Which branch advances, and is it shared?
3. Reversible? Is this local-only (reflog saves me) or pushed (revert instead)?
4. History rewrite? Am I rebasing commits anyone else has? If yes, stop.
5. How do I verify? What command or CI result confirms it worked?

16 · Cheat sheet

Merge strategies at a glance

Everyday commands

17 · Glossary

Branch

A movable pointer (ref) to a commit. Cheap to create and delete; never confuses with the commits it points to.

Commit

An immutable snapshot + metadata + parent pointer(s), identified by a SHA hash. Changing anything yields a new commit.

DAG

Directed acyclic graph — the shape of git history. Commits point to parents; the graph has no cycles.

Fast-forward (FF)

A merge that only advances the target pointer because the source is strictly ahead. Creates no merge commit.

Feature flag

A runtime switch that lets merged-in code stay dormant, decoupling merge from release. Enables trunk-based at scale.

Golden Rule (rebase)

Never rebase commits others already have. Rebase only your own local branches.

Integration branch

The shared line everyone merges into (main, develop, or trunk).

Merge commit

A commit with two parents, created when diverged lines join (or forced with --no-ff).

Pull request (PR)

A hosting-platform feature: a proposed branch merge with review and CI. Not a git command. Called "merge request" on GitLab.

Rebase

Replaying commits onto a new base, producing new hashes. Yields linear history; rewrites shared history at your peril.

Reflog

A local log of where every ref has been. The recovery net for "lost" commits after reset/rebase.

Remote-tracking branch

A local cache (e.g. origin/main) of a remote branch's position at last fetch. Not live.

SemVer

Semantic versioning: MAJOR.MINOR.PATCH, bumped by breaking/feature/fix respectively.

Squash

Collapsing several commits into one new commit on the target. Clean history; loses granularity.

Tag

An immutable-ish ref marking a specific commit, usually a release. Annotated tags carry metadata.

Trunk

The single integration branch in trunk-based development; often literally named main or trunk.

Workflow

The agreed rules for where work happens, how it integrates, and how it ships — a contract, not a tool.

18 · Retrieval quiz and sources

Answer aloud before revealing. Mark honestly; your score persists in this browser only.

Sources

External links require network; the guide itself works fully offline. Content reflects the widely documented public models as of 2026-07-23.

• Vincent Driessen — A successful Git branching model (Git Flow, 2010)
• gitflow — the model and the CLI extension (nvie)
• GitHub Docs — GitHub Flow
• GitHub Docs — Configuring pull request merges (merge strategies)
• trunkbaseddevelopment.com — Trunk-Based Development reference
• GitLab — What is GitLab Flow?
• GitLab Docs — GitLab Flow (environment & release branches)
• Pro Git — Basic Branching and Merging
• Pro Git — Rebasing
• Conventional Commits specification
• Semantic Versioning 2.0.0
• GitHub Docs — About CODEOWNERS