Git Operational Checklists

Git mastery is not only knowing commands. Git mastery is being able to enter any repository state, classify it, choose the lowest-risk operation, preserve evidence, and leave the system more understandable than before.

This part converts the entire series into operational checklists.

The goal is not to memorize everything. The goal is to build repeatable behavior for high-risk Git moments:

• before starting work;
• before committing;
• before pushing;
• before rewriting history;
• before merging;
• before releasing;
• before deleting anything;
• before cleaning a workspace;
• before responding to incidents;
• before changing repository policy.

A checklist is useful only if it encodes real invariants. A weak checklist says:

Run tests before merging.

A strong checklist says:

Confirm the checked-out commit is the commit being tested, the merge base is current, required tags were fetched, generated files are either reproducible or intentionally committed, and the artifact records the source commit SHA and dirty-tree state.

That is the difference between ritual and operational control.

1. How to Use These Checklists

Do not run every checklist every day. Use them based on risk class.

The common pattern is:

2. Universal Safety Invariants

These invariants apply across all Git workflows.

2.1 Identity Invariants

2.2 State Invariants

2.3 Collaboration Invariants

2.4 Release Invariants

3. Daily Start Checklist

Use this at the beginning of a work session.

# Where am I?
git status --short --branch

# What commit am I on?
git rev-parse --short HEAD

# Am I on a branch?
git symbolic-ref --short -q HEAD || echo "DETACHED HEAD"

# What is my upstream relationship?
git branch -vv

# What remotes exist?
git remote -v

Checklist:

• I know the current branch or detached HEAD state.
• I know whether the working tree is clean, dirty, conflicted, sparse, shallow, or partial.
• I know the upstream branch.
• I know whether local branch is ahead/behind/diverged.
• I have fetched before making integration decisions.
• I am not starting work from a stale base unless intentionally doing so.
• I am not carrying unrelated local changes from yesterday.

Safer daily refresh:

git fetch --prune --tags

git status --short --branch

For teams using trunk-based development:

git switch main
git pull --ff-only
git switch -c feature/<ticket>-<short-name>

For existing branch:

git fetch --prune

git merge-base --is-ancestor origin/main HEAD \
  && echo "Branch contains origin/main" \
  || echo "Branch may need refresh"

Important: pull is not automatically safe. It is fetch + integrate. Prefer explicit configuration:

git config --global pull.ff only

4. New Branch Checklist

Before creating a branch:

• The base branch is correct.
• The base branch is current.
• The branch name encodes purpose, not implementation noise.
• The work has a bounded scope.
• The target branch is known.
• The branch will not live longer than the team's branch lifetime budget.

Commands:

git switch main
git pull --ff-only
git switch -c feature/REG-1842-case-escalation-timeout

Good names:

feature/REG-1842-escalation-timeout
fix/REG-2210-permission-cache-invalidation
chore/SEC-1042-upgrade-oauth-library
hotfix/INC-7782-null-case-owner
backport/v2.8/SEC-1042-oauth-library

Weak names:

update-code
final-fix
new-branch
john-work
misc-changes

Naming rule:

A branch name should help a reviewer or incident responder understand why the branch exists without opening the diff.

5. Pre-Commit Checklist

Before committing:

git status --short
git diff
git diff --staged

Checklist:

• The staged diff is the commit I intend to create.
• The unstaged diff is intentionally excluded.
• No debug logs, test credentials, local config, or generated garbage are staged.
• New files are intentionally tracked.
• Deleted files are intentional.
• Renames are reviewable.
• Binary changes are expected.
• Lockfile changes match dependency changes.
• Migration changes include rollback/forward strategy where needed.
• Tests or verification commands were run at the right scope.

Partial staging:

git add -p

git diff --staged

git commit

For suspicious files:

git diff --staged --stat

git diff --staged --name-status

git diff --staged --check

git diff --check helps catch whitespace errors, but it is not semantic validation.

6. Commit Message Checklist

A commit message should answer:

1. What changed?
2. Why did it change?
3. What constraint or incident caused it?
4. What should future maintainers know?
5. What evidence links it to review, ticket, release, or policy?

Template:

<area>: <imperative summary>

<why this change exists>

<important design/operational notes>

Refs: REG-1842
Risk: medium
Test: ./gradlew test --tests EscalationTimeoutTest

Checklist:

• Subject is specific and imperative.
• Body explains causal context for non-trivial changes.
• Security, migration, compatibility, or release impact is explicit.
• Test evidence is mentioned if useful.
• Ticket/reference trailer is included when required.
• The message does not merely repeat the diff.

Weak:

fix bug

Better:

case-workflow: expire pending escalation after SLA window

Pending escalations were staying active when their SLA timer elapsed
without an assignee. This blocked later escalation attempts because the
workflow still observed an active escalation edge.

Refs: REG-1842
Test: EscalationTimeoutPolicyTest

7. Pre-Push Checklist

Before pushing:

git status --short --branch
git log --oneline --decorate --graph --max-count=20

Checklist:

• I know what branch I am pushing.
• I know what remote ref will be updated.
• I am not accidentally pushing to upstream instead of fork/origin.
• My branch is not behind its upstream in a way that will surprise me.
• I am not pushing WIP commits to a protected or shared branch unless expected.
• I did not accidentally include local-only commits.
• If rewriting, I am using --force-with-lease, not blind --force.

Safer first push:

git push -u origin HEAD

Safer rewrite push:

git fetch origin

git push --force-with-lease origin HEAD

Even safer explicit lease:

expected=$(git rev-parse origin/my-branch)
git push --force-with-lease=refs/heads/my-branch:$expected origin HEAD:my-branch

8. Pull Request Readiness Checklist

Before opening or marking PR ready:

• PR has one clear integration purpose.
• Branch target is correct.
• Diff base is current enough for review.
• PR title explains the change at integration level.
• Description explains why, not only what.
• Testing evidence is included.
• Migration/deployment steps are explicit.
• Rollback/revert strategy is known.
• Sensitive files have correct reviewers.
• Generated files are justified.
• Binary/LFS/submodule changes are visible and intentional.
• Commit series is reviewable or PR is intentionally squash-merged.

Diagnostic commands:

git fetch origin

git diff --stat origin/main...HEAD

git diff --name-status origin/main...HEAD

git log --oneline --decorate origin/main..HEAD

git range-diff origin/main...HEAD@{1} origin/main...HEAD 2>/dev/null || true

PR description template:

## What changed

## Why

## Risk

## Verification

## Deployment / migration notes

## Rollback

## Review focus

Review focus examples:

Please focus on the escalation state transition invariant and not on generated OpenAPI changes.

The risky part is the cache invalidation condition in PermissionSnapshotStore.

9. Code Review Checklist

For reviewers:

• Is the PR boundary coherent?
• Does the diff hide generated or renamed code?
• Are tests validating the behavior that changed?
• Are security-sensitive paths covered by owners?
• Does the change alter API, schema, permission, workflow, or deployment semantics?
• Is rollback possible?
• Does the PR introduce long-lived branch dependency?
• Is the merge method appropriate?
• Does the PR require documentation, runbook, migration, or alert update?

Useful reviewer commands:

# Compare branch with merge base
git diff origin/main...feature-branch

# Show commits proposed by branch
git log --oneline origin/main..feature-branch

# Show first-parent integration history
git log --first-parent --oneline origin/main

# Detect moved code with low noise
git diff --color-moved origin/main...feature-branch

# Ignore whitespace if formatting-only change is claimed
git diff -w origin/main...feature-branch

Reviewer red flags:

10. Conflict Resolution Checklist

When Git reports conflicts:

git status

git ls-files -u

Checklist:

• I know which operation caused the conflict: merge, rebase, cherry-pick, revert, stash apply.
• I know which side is ours and which side is theirs for this operation.
• I inspected the base when semantic intent matters.
• I did not blindly choose ours or theirs for domain files.
• I resolved generated files using the generator if possible.
• I ran relevant tests after resolution.
• I reviewed the final resolved diff.

Conflict inspection:

# Show unmerged stages
git ls-files -u

# Inspect versions
git show :1:path/to/file   # base
git show :2:path/to/file   # ours
git show :3:path/to/file   # theirs

After resolving:

git add path/to/file

git diff --staged

For rebase/cherry-pick:

git rebase --continue
# or
git cherry-pick --continue

Abort only if you intend to abandon the operation:

git rebase --abort
# or
git merge --abort
# or
git cherry-pick --abort

Mental model:

11. Rebase Checklist

Before rebase:

• Branch is private or rewrite has been coordinated.
• Working tree is clean or intentionally stashed.
• Current branch tip is backed up.
• Base branch has been fetched.
• I know whether merge topology should be preserved.
• I know how to abort and recover.

Backup:

git branch backup/$(git branch --show-current)-before-rebase

Rebase:

git fetch origin

git rebase origin/main

Interactive rebase:

git rebase -i origin/main

Preserve merges:

git rebase --rebase-merges origin/main

After rebase:

git range-diff origin/main...backup/my-branch-before-rebase origin/main...HEAD

git status --short --branch

Force push only with lease:

git push --force-with-lease origin HEAD

Recovery:

git reflog

git reset --hard HEAD@{<before-rebase>}

12. Force Push Checklist

Before force push:

• I fetched remote state recently.
• I know exactly which remote ref will be updated.
• Branch is not protected or shared without agreement.
• Reviewers know the branch was rewritten.
• A backup ref exists if this is risky.
• I am using --force-with-lease.

Commands:

git fetch origin

git branch backup/my-branch-before-force-push

git push --force-with-lease origin HEAD:my-branch

After force push:

git fetch origin

git rev-parse HEAD

git rev-parse origin/my-branch

Tell teammates:

I rewrote feature/REG-1842 to squash review feedback.
New tip: <sha>
Old tip backup: backup/feature-REG-1842-before-rewrite
Please reset/rebase local copies before continuing work.

13. Merge to Main Checklist

Before merging to main:

• PR target branch is correct.
• Required checks ran on current branch head or merge queue candidate.
• Required reviewers approved after latest relevant changes.
• Sensitive paths have owners.
• No unresolved discussions remain.
• Branch is not stale relative to target branch, or merge queue will validate latest integration.
• Merge method matches policy.
• Rollback strategy is clear.

For merge commit policy:

git log --first-parent --oneline main

For squash policy:

• Squash commit message preserves PR context.
• Important commit-level rationale is not lost.
• Release notes tooling can still classify the change.

For rebase-merge policy:

• Commit series is clean and bisectable.
• Commits were not signed in a way that rewrite invalidated policy expectations.

14. Release Checklist

Before release:

• Release source commit is identified by full SHA.
• Release branch/tag strategy is known.
• Working tree is clean.
• Build uses exact commit, not mutable branch state.
• Required tags were fetched.
• Version file matches intended version.
• Release notes boundary is explicit.
• Artifact records source commit and build metadata.
• Artifact digest is recorded.
• Release tag is annotated and signed if policy requires it.
• Tag is protected/immutable after publication.

Commands:

git fetch --tags --prune

git status --porcelain=v2

git rev-parse --verify HEAD^{commit}

git describe --tags --always --dirty

Create annotated tag:

git tag -a v2.8.0 -m "Release v2.8.0"

Create signed tag:

git tag -s v2.8.0 -m "Release v2.8.0"

Verify tag:

git tag -v v2.8.0

git rev-parse v2.8.0^{commit}

Release notes:

git log --first-parent --oneline v2.7.0..v2.8.0

git shortlog -sne v2.7.0..v2.8.0

Release evidence bundle:

release: v2.8.0
sourceCommit: <full-sha>
sourceTree: <tree-sha>
tagObject: <tag-object-sha>
artifactDigest: sha256:<digest>
ciRun: <run-id>
builderImage: <image-digest>
releaseNotesRange: v2.7.0..v2.8.0
approvedBy:
  - <reviewer>

15. Hotfix Checklist

Before hotfix:

• Incident severity and affected versions are known.
• Patch origin is known: main-first, release-branch-first, or emergency branch.
• Fix is minimal.
• Dependency commits are identified.
• Backport/forward-port direction is explicit.
• Version bump is decided.
• Rollback plan exists.
• Release evidence will record hotfix source commit.

Typical flow:

git switch release/2.8

git pull --ff-only

git switch -c hotfix/INC-7782-null-case-owner

# apply minimal fix

git commit -m "case-owner: handle missing owner during escalation"

Backport from main:

git switch release/2.8

git cherry-pick -x <fix-commit>

Forward-port to main if fix began on release branch:

git switch main

git pull --ff-only

git cherry-pick -x <hotfix-commit>

Hotfix anti-patterns:

16. Backport Checklist

Before backport:

• Target maintenance branch is supported.
• Patch commit list is explicit and ordered.
• Each commit has dependency classification.
• Patch applies semantically, not just textually.
• -x is used unless policy says otherwise.
• Tests run against target branch, not main.
• Release notes mention affected version.

Manifest:

backport: SEC-1042
sourceBranch: main
targetBranches:
  - release/2.8
  - release/2.7
commits:
  - sha: abc1234
    reason: core fix
  - sha: def5678
    reason: regression test
excluded:
  - sha: aaa9999
    reason: refactor-only dependency not needed

Execution:

git switch release/2.8

git pull --ff-only

git switch -c backport/2.8/SEC-1042

git cherry-pick -x abc1234 def5678

Verification:

git log --oneline release/2.8..HEAD

git range-diff main~5..main release/2.8..HEAD || true

17. Broken Main Incident Checklist

When main is broken:

Checklist:

• Freeze merges or merge queue.
• Capture current main tip.
• Announce incident channel.
• Determine whether failure is build, test, runtime, migration, config, secret, or infra.
• Prefer revert for shared history unless fix-forward is clearly safer.
• If reverting merge commit, identify mainline parent carefully.
• Validate remediation on current main candidate.
• Merge remediation with clear incident message.
• Reopen queue after green validation.
• Add guardrail that would have caught it.

Snapshot:

git fetch origin

git rev-parse origin/main

git log --first-parent --oneline -20 origin/main

Revert normal commit:

git revert <bad-commit>

Revert merge commit:

git show --summary <merge-commit>

git revert -m 1 <merge-commit>

Do not use reset --hard on published main as default incident response.

18. Bad Release Tag Checklist

When a release tag is wrong:

• Stop publishing artifacts for that tag.
• Determine whether tag was pushed publicly.
• Determine whether artifacts were built from it.
• Determine whether consumers may have fetched it.
• Capture old tag target and new intended target.
• Avoid silently moving public tag if possible.
• Prefer corrective version if exposure occurred.
• Protect tag pattern after incident.

Diagnosis:

git fetch --tags --force

git rev-parse v2.8.0

git rev-parse v2.8.0^{commit}

git cat-file -t v2.8.0

git tag -v v2.8.0 || true

Corrective release pattern:

Bad:  v2.8.0 points to wrong commit and may be consumed.
Good: publish v2.8.1 with correct commit and document v2.8.0 as invalid/superseded.

If tag was local only:

git tag -d v2.8.0

git tag -a v2.8.0 <correct-commit> -m "Release v2.8.0"

If public exposure occurred, treat as release integrity incident, not cleanup.

19. Secret Leak Checklist

When a secret enters Git:

Checklist:

• Rotate/revoke credential before history rewrite.
• Capture where it appeared.
• Identify exposure window.
• Remove from current branch.
• Search all refs if necessary.
• Decide whether rewrite is needed.
• Notify affected clone owners before rewrite.
• Purge CI caches/artifacts/logs if they contain secret.
• Verify secret no longer appears in reachable history.
• Add prevention: secret scanning, hooks, CI gates, education.

Search:

git grep -n "SECRET_PATTERN" $(git rev-list --all)

Large repositories may require specialized scanning tooling.

Rewrite using git filter-repo requires separate operational planning and downstream coordination.

20. Repository Health Checklist

Run this periodically or when repo feels slow.

git status --short --branch

git count-objects -vH

git for-each-ref --format='%(refname:short) %(committerdate:iso8601)' refs/heads refs/remotes | head

git fsck --connectivity-only

Checklist:

• Loose object count is not exploding.
• Pack count is not excessive.
• Large blobs are known and intentional.
• Stale branches are pruned or archived.
• Release tags are protected and coherent.
• Commit-graph maintenance is enabled for large repos.
• Multi-pack-index/incremental repack is considered where needed.
• Sparse/partial clone profile exists for monorepo users.
• CI is not doing wasteful full clone when unnecessary.
• CI release jobs fetch tags/history when necessary.

Large blob scan:

git rev-list --objects --all \
  | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' \
  | awk '$1 == "blob" {print $3, $4, $2}' \
  | sort -nr \
  | head -50

Maintenance:

git maintenance run

git gc --auto

Do not use aggressive history rewrite as first response to slowness. Diagnose first.

21. CI Checkout Checklist

For CI jobs:

• Job knows whether it needs full history.
• Job knows whether it needs tags.
• PR job knows whether to test head commit or merge result.
• Release job uses exact commit/tag.
• Shallow clone does not break changelog, merge-base, or affected-set logic.
• Submodules are initialized recursively if required.
• LFS files are fetched if required.
• Sparse checkout does not omit files needed by build/test.
• Build metadata records commit SHA and dirty state.

Profiles:

Validation snippet:

git rev-parse --verify HEAD^{commit}

git status --porcelain=v2

git describe --tags --always --dirty || true

22. Large File / LFS Checklist

Before adding large files:

• File is source-like and reviewable, or intentionally binary.
• File changes over time at acceptable frequency.
• Repository size impact is known.
• CI and local workflows can fetch it.
• Artifact repository was considered.
• Git LFS was considered for large binary source assets.
• Generated artifacts are not committed unless required.
• .gitattributes tracks LFS patterns if used.

Check staged large files:

git diff --cached --numstat

Find large blobs:

git rev-list --objects --all \
  | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' \
  | sort -k3nr \
  | head -20

Decision:

23. Submodule Checklist

Before adding or updating submodule:

• Dependency ownership is explicit.
• Submodule commit is reachable from its upstream.
• CI can fetch submodule recursively.
• Release process records submodule commit.
• Security review includes submodule repository.
• Developers know detached HEAD behavior.
• Update PR includes parent repo gitlink change and reason.

Commands:

git submodule status --recursive

git submodule update --init --recursive

Submodule update:

cd path/to/submodule
git fetch --tags
git checkout <commit-or-tag>
cd -
git add path/to/submodule
git commit -m "deps: update case-rules submodule to <sha>"

Failure mode:

Parent repository points to a submodule commit that was never pushed to the submodule remote.

Verification:

cd path/to/submodule
git cat-file -e HEAD^{commit}
git branch -r --contains HEAD

24. Sparse / Partial Clone Checklist

Before enabling sparse or partial clone:

• Users understand missing working tree paths vs missing objects.
• Tooling supports sparse index if enabled.
• CI jobs that need full repository do not inherit developer sparse profile blindly.
• Offline workflows are considered.
• Lazy fetch storm risk is measured.
• Release jobs use full-enough checkout.

Sparse checkout:

git sparse-checkout init --cone

git sparse-checkout set services/case-api libs/workflow-core

Partial clone:

git clone --filter=blob:none <url>

Diagnostic:

git rev-parse --is-shallow-repository

git config --get remote.origin.promisor

git config --get remote.origin.partialclonefilter

git sparse-checkout list || true

25. Audit / Regulated Systems Checklist

For regulated or high-accountability systems:

• Protected branch rules are documented.
• Required approvals map to risk class.
• CODEOWNERS routes sensitive changes.
• CI checks produce durable evidence.
• Release tag is immutable and preferably signed.
• Artifact provenance records source commit and digest.
• Emergency change path exists and is auditable.
• History rewrite policy exists.
• Secret leak response procedure exists.
• Deployment record links artifact to release approval.
• Runtime version endpoint exposes commit/artifact identity.

Evidence chain:

Minimum release evidence:

changeRequest: REG-1842
pr: 4217
sourceCommit: <sha>
releaseTag: v2.8.0
artifactDigest: sha256:<digest>
ciRun: <id>
approvals:
  - security-owner
  - workflow-owner
deployedAt: 2026-07-07T10:00:00+07:00

26. Dangerous Command Checklist

Before running any dangerous command:

git status --short --branch

git rev-parse --short HEAD

Create backup when uncertain:

git branch backup/before-dangerous-operation-$(date +%Y%m%d-%H%M%S)

Dangerous commands:

Safe pattern:

# 1. Observe
git status --short --branch

# 2. Backup
git branch backup/<name>

# 3. Dry run where possible
git clean -ndx

# 4. Execute scoped command, not broad command
git clean -fd -- path/to/generated-output

27. One-Page Decision Tree

Command selection:

28. Final Operational Principle

A high-level engineer does not ask only:

What Git command solves this?

A high-level engineer asks:

1. Which state will this command mutate?
2. Is the state local or shared?
3. Is the identity mutable or release-critical?
4. What evidence do we preserve?
5. How do downstream users recover?
6. What invariant prevents recurrence?

That is the bridge from Git usage to Git operational engineering.

References

• Git documentation index: https://git-scm.com/docs
• Git workflows: https://git-scm.com/docs/gitworkflows
• Git hooks: https://git-scm.com/docs/githooks
• Git push: https://git-scm.com/docs/git-push
• Git revert: https://git-scm.com/docs/git-revert
• Git tag: https://git-scm.com/docs/git-tag
• Git sparse checkout: https://git-scm.com/docs/git-sparse-checkout
• Partial clone design: https://git-scm.com/docs/partial-clone