System Atlas
the atlas

Git branching workflows

The commit-to-merge loop every team runs — and the branching models that shape it.

the gist

The core Git loop is edit → stage → commit → push → open a pull request → review → merge. Teams wrap that loop in a branching model: feature-branch (simple, one branch per task), Gitflow (structured main/develop/release/hotfix branches), or trunk-based (everyone commits to main behind flags). The trade-off is structure and safety versus speed and simplicity.

ANALOGY // Writing a book with editors: you draft a chapter (branch), hand it in for notes (pull request), the editor marks it up (review), and only then is it bound into the master manuscript (merge) — and the publisher's house style dictates how chapters are named and combined.
living diagram01 / 06
git addWorking diredit codeStaging areagit addLocal commitgit commitPush branchgit pushPull requestpropose mergeReview + CIapprove · testsmain / trunkmerge & deploy
01

Edit and stage

You start in your working directory, changing files on a branch. Git doesn't record everything automatically — you use git add to move specific changes into the staging area, choosing exactly what belongs in the next snapshot. Staging is Git's way of letting you compose a clean, meaningful commit rather than dumping every edit together.

02

Commit locally

git commit takes everything staged and writes a permanent snapshot into your local repository, tagged with a message describing the change. This commit lives only on your machine for now — it costs nothing, needs no network, and can be amended or reverted freely. Good practice is many small, focused commits that each tell one story.

03

Push the branch

When the work is ready to share, git push uploads your branch and its commits to the remote (GitHub, GitLab, etc.). Pushing to your own feature branch never touches the main branch, so your in-progress work is backed up and visible to teammates without disturbing the shared line of development. Nothing is merged yet.

04

Open a pull request

You open a pull request (or merge request) proposing that your branch be merged into the target branch. This is the pivotal move: instead of silently changing the code, you create a reviewable unit where the diff, commit history and description sit together for others to examine. CI pipelines typically fire here to build and test the change automatically.

05

Review and CI

Teammates read the diff, leave inline comments, request changes, and ultimately approve. Automated checks — tests, linters, security scans — must go green alongside human sign-off. This gate is where bugs are caught and knowledge spreads; the branch is iterated until both the reviewers and the pipeline are satisfied.

06

Merge, then loop

Once approved and green, the branch is merged into main, becoming part of the shared history and usually triggering a deployment. You then pull the updated main, delete the finished branch, and start the loop again for the next task. Which branches exist and how strictly this flows is exactly what a branching model like Gitflow or trunk-based development defines.

the full picture
01

Why teams need a workflow at all

Git gives you the raw mechanics — commits, branches, merges — but it deliberately does not tell you how to use them as a team. Left unmanaged, a shared repository turns into chaos: people committing straight to the main branch, half-finished work breaking everyone else, and no record of who reviewed what. A Git workflow is the agreed set of conventions that turns Git's freedom into a repeatable, safe process.

Every workflow is built on the same foundation: a core loop that takes a change from your editor into the shared codebase, and a branching model that dictates which branches exist, what each is for, and how work flows between them. Understanding the loop first, then the models layered on top, is the way to make sense of any team's setup.

02

The inner loop: stage, commit, push

Every change starts the same way. You edit files in your working directory, then run git add to move chosen changes into the staging area — a distinctive Git feature that lets you compose exactly what the next commit will contain, rather than blindly saving everything. This is how you keep commits focused: stage the three files that belong to one fix, leave the unrelated experiment for later.

Then git commit snapshots everything staged into your local repository with a descriptive message. Crucially this commit is local — it needs no network, costs nothing, and can be amended or discarded freely, so the discipline is to make many small, self-explanatory commits. Finally, git push uploads your branch and its commits to the remote (GitHub, GitLab, Bitbucket). Pushing to your own feature branch backs up your work and makes it visible to teammates without touching the main line — nothing is merged into shared code yet.

03

The outer loop: pull request, review, merge

Pushing a branch is only half the story; the other half is getting it safely into the shared codebase. You open a pull request (called a merge request on GitLab) — a proposal to merge your branch into a target branch. This is the pivotal design choice of modern collaboration: instead of silently altering the code, you create a reviewable unit where the diff, the commit history and a written description live together for others to scrutinise.

Two gates guard the merge. Automated CI fires on the pull request to build the code and run tests, linters and security scans, giving objective feedback that the change is sound. Human review runs in parallel: teammates read the diff, leave inline comments, and either request changes or approve. The branch is iterated until both gates are green. Only then is it merged into the main branch, becoming part of shared history and typically triggering a deployment. You then pull the updated main, delete the finished branch, and begin the loop again. This review-before-merge discipline is where most bugs are caught and where knowledge spreads across a team.

04

The three branching models

Teams wrap that loop in one of three broad models, trading structure against speed:

  • Feature-branch workflow — the common default. There is one long-lived main branch that is always deployable; every task gets its own short-lived branch off main, and merges back via a pull request. Simple, easy to teach, and enough for most teams.
  • Gitflow — a highly structured model with two permanent branches (main for releases, develop for integration) plus supporting feature, release and hotfix branches. It gives strong control over versioned releases and is well suited to software with formal release cycles or multiple maintained versions, but the ceremony is heavy and it can slow fast-moving web teams down.
  • Trunk-based development — the model favoured by high-velocity teams and continuous deployment. Everyone integrates into main (the "trunk") constantly — many times a day — using only tiny, short-lived branches. Unfinished work is hidden behind feature flags rather than isolated in long branches. It minimises painful merge conflicts and maximises integration frequency, but demands excellent automated testing and CI to keep main always releasable.
05

Choosing, and the trade-offs that decide it

The models exist on a spectrum from structure to speed. Gitflow sits at the structured end: many branch types, explicit release management, strong control — at the cost of overhead and slower flow, and a real risk of long-lived branches drifting far apart and merging painfully. Trunk-based sits at the speed end: minimal branching, constant integration, fast delivery — but it only works if your test suite and CI are strong enough to catch regressions automatically, because there is no long review-in-isolation buffer. Feature-branch flow sits comfortably in the middle and is why most teams start there.

The practical guidance is to match the model to the product and the team. A library with several supported versions and scheduled releases benefits from Gitflow's structure; a SaaS product deploying dozens of times a day thrives on trunk-based development; a small or new team is well served by plain feature branches. The deeper lesson is that the branching model and your delivery cadence are two sides of one coin — the more continuously you want to ship, the shorter-lived your branches must be, which is exactly why continuous deployment and trunk-based development go hand in hand.

what to remember
01

The inner loop: edit files → git add (stage) → git commit (local snapshot) → git push → pull request → review → merge.

02

Staging lets you craft exactly what goes into each commit; commits are local until you push.

03

A pull request turns a merge into a reviewable, testable proposal rather than a silent change.

04

Feature-branch flow: branch per task off main, merge back via PR — simple and the common default.

05

Gitflow: long-lived main + develop plus feature/release/hotfix branches — structured but heavy.

06

Trunk-based: short-lived branches merged to main many times a day behind feature flags — fast, needs strong CI.

check yourself

Quick quiz

Q1

What does the staging area (git add) let you do?

Q2

What best describes trunk-based development?

follow the thread