Skip to content
AI Engineer Guide.

concept · basics · intermediate · concept 19 of 24

Git workflow

0 of 24 complete

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

Mechanism, step by stepInteractive
  1. 1Choose trunk-based development with short-lived branches, or document why a release branch is required.
  2. 2Set a review size expectation and split work by behaviour change rather than by file.
  3. 3Protect the main branch with required checks, required review and one merge policy applied consistently.
  4. 4Rebase or merge from the trunk frequently so conflicts surface while the change is small.
  5. 5Write commit messages that explain why, and squash or preserve history according to the chosen policy.
  6. 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.

Step 1/6 · step 1

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 …

  1. Choose trunk-based development with short-lived branches, or document why a release branch is required.
  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 applied consistently.
  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 chosen policy.
  6. Scan for secrets before pushing, and rotate anything that was committed even after it is removed.

Trade-offs

ChoiceGood forCostFails when
Trunk-basedFast integration and small diffsNeeds feature flags and a green pipelineThe team ships rarely and in large batches
Release branchesSupports versioned releases and hotfixesMerge overhead and long-lived divergenceDeployment is continuous
Squash mergeClean linear historyLoses intermediate commitsBisecting needs the individual changes
Merge commitsPreserves branch contextNoisy historyThe team reads history as a changelog
Trade-off mapInteractive

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

  1. The team ships rarely and in large batches
  2. Deployment is continuous
  3. Bisecting needs the individual changes
  4. 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