Why it matters
Git records content, not intent, so the workflow has to supply what history cannot: how long a branch lives, how large a review is, and what verification is required before merge. Teams that skip those decisions get long-lived branches, enormous diffs, and merges reviewed by fatigue rather than by reading. The workflow keeps changes small enough to reason about and the shared branch releasable.
Mental model
It is a shared document with tracked changes: small edits are easy to review and easy to revert, while a rewrite of the whole file is neither. The analogy breaks because git can merge independent edits automatically, which makes large parallel changes look safer than they are.
How it works
- 1Choose trunk-based development with short-lived branches, or document why a release branch is required.
- 2Set a review size expectation and split work by behaviour change rather than by file.
- 3Protect the main branch with required checks, required review and one merge policy applied consistently.
- 4Rebase or merge from the trunk frequently so conflicts surface while the change is small.
- 5Write commit messages that explain why, and squash or preserve history according to the chosen policy.
- 6Scan for secrets before pushing, and rotate anything that was committed even after it is removed.
Step 1 of 6
Choose trunk-based development with short-lived branches, or document why a release branch is required.
Figure. The mechanism in this page's own steps. The figure adds sequence, not new claims.
What to notice. A step can be read alone, but the order is the mechanism. The control lets you stop on any one.
Text version
The page's steps: 1. Choose trunk-based development with short-lived branches, or document why a release branc… 2. Set a review size expectation and split work by behaviour change rather than by file. 3. Protect the main branch with required checks, required review and one merge policy applie… 4. Rebase or merge from the trunk frequently so conflicts surface while the change is small. 5. Write commit messages that explain why, and squash or preserve history according to the c… 6. Scan for secrets before pushing, and rotate anything that was committed even after it is …
- Choose trunk-based development with short-lived branches, or document why a release branch is required.
- Set a review size expectation and split work by behaviour change rather than by file.
- Protect the main branch with required checks, required review and one merge policy applied consistently.
- Rebase or merge from the trunk frequently so conflicts surface while the change is small.
- Write commit messages that explain why, and squash or preserve history according to the chosen policy.
- Scan for secrets before pushing, and rotate anything that was committed even after it is removed.
Trade-offs
| Choice | Good for | Cost | Fails when |
|---|---|---|---|
| Trunk-based | Fast integration and small diffs | Needs feature flags and a green pipeline | The team ships rarely and in large batches |
| Release branches | Supports versioned releases and hotfixes | Merge overhead and long-lived divergence | Deployment is continuous |
| Squash merge | Clean linear history | Loses intermediate commits | Bisecting needs the individual changes |
| Merge commits | Preserves branch context | Noisy history | The team reads history as a changelog |
Good for
Fast integration and small diffs
Cost
Needs feature flags and a green pipeline
Fails when
The team ships rarely and in large batches
- The team ships rarely and in large batches
- Deployment is continuous
- Bisecting needs the individual changes
- The team reads history as a changelog
Figure. Each choice with what it buys, what it costs, and the case where it loses.
What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.
Text version
Four trade-offs: Trunk-based is good for Fast integration and small diffs, costs Needs feature flags and a green pipeline, and fails when The team ships rarely and in large batches. Release branches is good for Supports versioned releases and hotfixes, costs Merge overhead and long-lived divergence, and fails when Deployment is continuous. Squash merge is good for Clean linear history, costs Loses intermediate commits, and fails when Bisecting needs the individual changes. Merge commits is good for Preserves branch context, costs Noisy history, and fails when The team reads history as a changelog
Failure modes
- Long-lived branch. Conflicts are resolved by choosing one side and the review no longer reflects the change. Debug: measure branch age at merge and flag anything older than a few days.
- Secret in history. Removing the file in a later commit leaves the credential in the object database. Debug: scan the full history, not the working tree, and rotate the secret.
- Review by size. A large diff is approved with a skim and the defect ships. Debug: chart review comments per hundred lines and look for a collapse as size grows.
In production
Track branch age, review latency and revert rate; a rising revert rate means reviews are not catching what breaks. Keep the protected-branch rules in version control with the code they govern.
Common misconceptions
People think: A merge strategy determines whether the code is correct.
Actually: It determines history shape; correctness comes from review, tests and small changes.
People think: Deleting a committed secret is enough.
Actually: The object remains in history and in clones, so the credential must be rotated.
Interview angle
Tie branch lifetime to review quality and name the enforcement point, the protected branch. Treat a committed secret as a rotation event. Arguing merge versus rebase without saying how large a change should be avoids the question.
Sources
- Pro Git — branching, merging and history rewriting.
- Git documentation — reference behaviour for merge, rebase and reset.
- Trunk Based Development — short-lived branches and release from trunk.