Developer Reference

Version Control & SDLC

A comprehensive reference covering every stage of the software delivery lifecycle — from planning and branching strategy through CI/CD, governance, and post-deployment monitoring.

14 lifecycle stages
6 reference tools
153 git commands, each rated for safety
27 rescue recipes, tested against real git

1Develop

Planning

Turn a request into a work item a developer can start on without asking a question, and a branch name that points back to it.

Every change starts as a written work item, not a conversation — so anyone can pick it up without asking what was meant.
A story is ready to start when its acceptance criteria are unambiguous, its dependencies are unblocked, and it fits in a sprint.
Acceptance criteria are written as Given/When/Then, so "done" is a fact everyone can check, not an opinion.
The branch name carries the issue key, so every commit, PR and deploy traces back to the work item that asked for it.
A draft PR opened on day one is a better planning signal than a status update: it shows real progress, in review, before the work is finished.

Match the issue type to the work

Five shapes cover almost everything a team tracks. Pick the narrowest one that fits.

Issue types
Type	Use it for	Typical fields
Story	User-visible feature work	As a / I want to / So that, acceptance criteria, story points
Bug	A defect: something worked and stopped, or never matched the spec	Steps to reproduce, expected vs. actual, environment
Task	Technical work with no direct user visibility (upgrades, refactors)	Objective, definition of done, dependencies
Epic	A body of work spanning multiple sprints, grouping stories	Goal, scope (in/out), success metrics, target quarter
Spike	Time-boxed research to reduce uncertainty before committing to a design	Question to answer, time box, decision criteria

Meet the Definition of Ready before starting
A story a developer cannot start without asking a question is not ready. Check, before it enters a sprint:
- Acceptance criteria are unambiguous and written as Given/When/Then.
- The team doing the work estimated it, not the person who filed it.
- Every dependency is identified and unblocked.
- Designs or wireframes are attached, for UI work.
- No open question would block a developer from starting today.
- It fits comfortably inside a single sprint — if not, it is an epic, not a story.
Write acceptance criteria as Given/When/Then
Behaviour-driven acceptance criteria state a precondition, an action and an observable result, so "done" can be checked mechanically instead of argued about:
acceptance-criteria.mdmarkdown
```
Given a logged-in user on the dashboard
When they click "Export to CSV"
Then a CSV file is downloaded containing all visible rows
And the filename includes today's date
```
Name the branch after the issue, and link the PR to it
A branch name that carries the issue key (feature/PROJ-123-add-oauth) means every commit and PR traces back to the work item without anyone looking it up. On GitHub, a pull request whose description contains a closing keyword and an issue reference (Closes #123) closes that issue automatically when the PR merges GitHub 2026 — one more reason the issue key belongs in the branch and the PR, not only in a person's memory.
Open a draft PR on day one for anything that will take more than a day
A draft pull request cannot be merged until it is marked ready for review, but it is visible, diffable and commentable from the first commit GitHub 2026. It replaces a status update with something reviewers can actually look at, and lets a reviewer flag a wrong direction before the work is finished rather than after.

Priority, separately from size

Priority says how soon; story points say how much work. Conflating them means an easy P3 jumps the queue over a hard P1, or a big P0 sits half-estimated while the team argues about its size.

Priority levels
Priority	Meaning	Response
P0 — Critical	Production is down, or data is being lost	Fix immediately, all hands
P1 — High	A core feature is broken for users	Fix within the current sprint
P2 — Medium	A non-critical degradation	Next sprint or sooner
P3 — Low	A nice-to-have improvement	Scheduled as capacity allows

A story enters the sprint without acceptance criteria
The team discovers what "done" means during the PR review, which is the most expensive place to discover it — the code already exists and now has to change shape.
The branch name has no connection to the issue
Six months later, nobody can tell why fix-thing exists, whether it shipped, or what it was for. git log --grep on an issue key finds every commit for a feature; a name like fix-thing is unsearchable.

Sources

GitHub — Linking a pull request to an issue (2026)
GitHub — About pull requests (draft pull requests) (2026)

2Develop

Repo Foundations

Create the repository, its default branch, its ignore and attributes files, and choose how it will scale before the first commit.

A repository is a directory plus a hidden .git — git init creates the second part; nothing else changes on disk.
.gitignore stops git tracking files it should never track; .gitattributes controls how it treats the files it does.
Neither file has any effect on a file git already tracks — untrack a mistakenly committed secret with git rm --cached, then rotate it.
A monorepo trades independent deploys for atomic cross-project changes; a polyrepo trades that back for isolation. Neither is free.
Sparse checkouts, partial clones and shallow clones each cut a different cost — disk, network, or both — at the price of some command no longer working the normal way.

Start the repository

git initReference

This writes .git/ and nothing else: no commit exists yet, and no files are tracked until you add them. The name of the first branch comes from init.defaultBranch if it is set, or git config --global init.defaultBranch main to set it once for every new repository Git project 2026.

git remote add origin <url>Reference

git add . && git commit -m "Initial commit"

git push -u origin mainReference

README, LICENSE, CONTRIBUTING

Three files a reader looks for before anything else. None is required by git; all three are expected by everyone reading the repository on a host.

Root files
File	Answers
README.md	What this is, how to run it, where to start
LICENSE	What anyone may legally do with the code — required for it to be reused at all outside the org
CONTRIBUTING.md	How to propose a change: branch naming, commit style, how to run tests, who reviews

Ignore build output, dependencies and secrets before the first commit
Write .gitignore before adding files, not after — a pattern only stops git tracking a file it has never seen. A file already committed keeps being tracked no matter what you add to .gitignore later; remove it from the index first with git rm --cached <path> Git project 2026.
Fix line endings and diff behaviour with .gitattributes
* text=auto lets git normalise line endings to LF in the repository and convert them on checkout per core.autocrlf; marking binary files binary stops git trying to diff or merge them as text; marking a lockfile -diff replaces a multi-thousand-line diff with "Binary files differ" without changing how it is stored or merged Git project 2026.
Generate both files from what the project actually uses
Pick languages, tools, editors and operating systems below; every rule comes with the reason it is there, and the tester checks a path the same way git check-ignore -v would.

Monorepo vs. polyrepo

One repository per project, or one for everything
	Monorepo	Polyrepo
Cross-project changes	One commit, one PR, reviewed together	A PR per repository, coordinated by hand or tooling
CI	Needs affected-package detection or every push tests everything	Each repository's pipeline only ever sees its own code
Access control	Coarse — usually the whole repository or nothing	Fine-grained per repository
Shared tooling	One version of every dependency, enforced by the layout	Each repository can pick its own, and drift

Options for a large repository

Each of these makes one specific thing smaller — files on disk, bytes fetched, or history downloaded — none is free, and they compose.

Scale options
Option	What it reduces	What stops working the normal way
`git sparse-checkout`	Files written to disk — only the paths you choose appear in the working tree	A path outside the cone will not appear until you add it back
`git clone --filter=blob:none`	Bytes fetched — file contents download on demand, the first time each is needed	The first checkout, and the first diff or blame touching an old file, fetches over the network
`git clone --depth N`	History downloaded — only the last N commits	log, blame and bisect only see those N commits; pushing new history back can be rejected
Git LFS	Repository size for large binaries — the file is stored on an LFS server, a pointer in git	Everyone who clones needs Git LFS installed, or they get pointer files instead of content
`git maintenance`	Time spent on gc, repacking and the commit-graph, spread out instead of done all at once	Nothing — it runs in the background once <code>git maintenance start</code> schedules it

A clone made with --filter or --depth is a partial or shallow clone respectively; both are configured with --sparse, --filter and --depth on git clone itself Git project 2026, and git sparse-checkout can narrow an existing clone's working tree afterwards Git project 2026. git maintenance start schedules background repository maintenance instead of leaving it to an occasional manual git gc Git project 2026.

A secret was committed before .gitignore existed
Adding the pattern afterwards does not remove it from history — every commit that ever included the file still has it.
Rescue recipe →
A lockfile is in .gitignore
Without the lockfile committed, every install can resolve different transitive versions — the one thing a lockfile exists to prevent.

Sources

Git project — git-init documentation (2026)
Git project — gitignore — specifies intentionally untracked files to ignore (2026)
Git project — gitattributes — defining attributes per path (2026)
Git project — git-clone documentation (2026)
Git project — git-sparse-checkout documentation (2026)
Git project — git-maintenance documentation (2026)

3Develop

Branching Strategy

Decide which branches live long, which live for a day, and how work reaches main — trunk-based, GitHub Flow, GitLab Flow or Git Flow.

A branching strategy answers one question: how does a change reach main, and how long does a branch live before it does?
Trunk-based development and GitHub Flow keep almost everything short-lived; Git Flow adds long-lived develop and release branches for versioned software.
Git Flow's own author, ten years after writing it, now recommends most teams use something simpler Driessen 2010.
The right choice follows release cadence and CI maturity, not preference — see the simulator below with your own team's numbers.

Four strategies, compared

Branching strategies
Strategy	Long-lived branches	Release model	Suits
Trunk-based development	None — everyone commits to main (or trunk) multiple times a day, behind feature flags for anything incomplete	Continuous — main is always releasable	High-velocity teams with strong CI and feature-flag infrastructure
GitHub Flow	None — main, plus a short-lived branch per pull request	Continuous — main deploys as soon as a PR merges	Web apps deployed continuously to one environment
GitLab Flow	Environment branches (e.g. staging, production), or a release branch per version	Either continuous (environment branches) or versioned (release branches) — GitLab documents both variants	Teams that need an explicit environment or version boundary GitHub Flow does not give them
Git Flow	develop (integration) plus one release branch per version	Versioned, scheduled releases, with parallel hotfix support	Software distributed as versioned releases, or supporting multiple versions in the wild at once

GitLab documents its own flow as a family of variants built on top of a GitHub-Flow-like base, not one fixed model GitLab 2026; GitHub's own flow is deliberately the simplest of the four GitHub 2026; trunk-based development is the strategy behind continuous integration's original premise — that everyone's changes meet, in one place, at least daily Hammant 2020.

Match the strategy to release cadence and CI maturity, not preference
Every long-lived branch is a batch of changes that has not yet met the others — the longer it lives, the more expensive the eventual merge. Continuous delivery wants that cost at zero, which is why trunk-based development and GitHub Flow both minimise long-lived branches; software that ships in dated, supported versions needs somewhere to put a fix for a version that already shipped, which is what Git Flow's release branches are for.

Name branches so the type is obvious without opening them

Branch naming
Pattern	Use it for
`feature/PROJ-123-add-oauth`	New functionality
`bugfix/PROJ-456-fix-null-pointer`	A fix for something already merged
`hotfix/v2.1.1-payment-null-fix`	An urgent fix cut from a release branch, not from main
`release/v2.2.0`	A branch that stabilises one version before it ships
`chore/update-dependencies`	No user-visible change

Git Flow adopted for a continuously deployed web app
Every feature waits for develop, then a release branch, before it can ship — for software that could deploy the moment a PR merges, that delay buys nothing.
A feature branch lives for weeks
It drifts further from main every day it is not merged; when it finally does merge, the conflict is bigger than it would have been on day two. Trunk-based development and GitHub Flow both exist specifically to prevent this.

Sources

Driessen, V. — A successful Git branching model (with the 2020 note of reflection) (2010)
GitHub — GitHub flow (2026)
GitLab — Branching strategies (GitLab Flow) (2026)
Hammant, P. — Trunk Based Development (2020)

4Develop

Local Dev

Move changes between the working tree, the index and HEAD; write commits someone can review, revert and bisect.

Every file has up to three versions: in HEAD (the last commit), the index (what the next commit will contain) and the working tree (on disk). Add, commit, restore and reset each copy between two of these.
A commit is a unit of review, revert and bisection — one logical change, not one save point.
Conventional Commits gives a message a type a machine can read (fix:, feat:, a ! or BREAKING CHANGE: footer for a breaking change), which is what makes an automatic changelog and version bump possible.
reset --soft only moves HEAD; reset (mixed) also unstages; reset --hard also overwrites the working tree. Each is a strictly bigger hammer than the last.
A..B on git log means commits reachable from B but not A; A...B means either but not both — the second is what a PR diff and git log --left-right usually want.

The three trees, live

Run a command in this stage's terminal — add, commit, restore, reset — and watch which column changes.

Stage what belongs in this commit, not everything you touched
git add app.js config.jsonReference
Staging the whole working tree with git add . is fine when every change in it really is one commit; when it is not, stage file by file, or use git add -p to stage individual hunks within a file and leave the rest for a later commit.
One logical change per commit
The unit of review, revert and bisection is the commit, not the pull request:
- Revertability — reverting one concern reverts exactly what broke, not unrelated code that happened to ship alongside it.
- Bisectability — git bisect only finds the right commit if every commit in between is a consistent, buildable state.
- Review quality — a reviewer reasons about one change at a time; a commit that mixes a rename with a behaviour change hides the behaviour change inside the noise.
Write commit messages a machine and a person can both use
Conventional Commits gives every message a type, an optional scope, and a description: fix(cart): correct total on discount. fix maps to a patch release and feat to a minor one; a ! before the colon, or a BREAKING CHANGE: footer, means major Conventional Commits contributors 2019. Footers also carry authorship and provenance trailers such as Co-authored-by (a commit with more than one author GitHub 2026) and Signed-off-by (the Developer Certificate of Origin: the signer attests they have the right to submit the change under the project's license Linux Foundation 2004), both parsed the same way by git interpret-trailers Git project 2026.

Fix the last commit or the working tree with the smallest tool that does it

Undo, from smallest to largest
Command	Undoes	Rewrites shared history?
`git commit --amend`	Replaces the last commit — its message, or its content if you staged more first	Yes, if already pushed — don't amend a commit others have based work on
`git restore <path>`	Discards uncommitted changes to a file, back to what the index has	No — nothing was committed
`git restore --staged <path>`	Unstages a file without touching its content	No
`git reset --soft HEAD~1`	Moves HEAD back one commit; index and working tree untouched — the commit's changes are now staged	Yes, if already pushed
`git reset HEAD~1`	The same, and also unstages — the changes are now just in the working tree	Yes, if already pushed
`git reset --hard HEAD~1`	The same, and also overwrites the working tree — uncommitted changes are gone	Yes, if already pushed

Set work aside without committing it
git stash push -m "WIP: add auth"Reference
git switch main
git stash popReference
A stash is a commit outside any branch's history — git stash list shows every one, and popping applies and drops the most recent.

Read history with the flag that answers the actual question

Reading history
Command	Answers
`git log --oneline --graph`	What happened, and in what order, across branches
`git log A..B`	Commits reachable from B but not A — what B has that A doesn't
`git log A...B`	Commits reachable from either but not both — the symmetric difference
`git blame <file>`	Which commit last touched each line
`git log -S"needle"`	Which commits added or removed an exact string — not just touched the file

git log --left-right A...B marks each commit with which side of the symmetric difference it is reachable from (< or >) Git project 2026, which is what most "how have these two branches diverged" questions actually want; the range syntax itself — A..B, A...B, and @{upstream} — is gitrevisions' own subject Git project 2026.

Read a diff

Hooks: local checks that run automatically

Common client-side hooks
Hook	Runs	Typical use
pre-commit	Before a commit is created	Lint, format, type-check, or scan for secrets
commit-msg	After the message is written, before the commit is created	Enforce Conventional Commits or a ticket-number prefix
pre-push	Before git push sends anything	Run the test suite one last time

Hooks live in .git/hooks/, are not cloned with the repository, and must be executable Git project 2026. Most teams install them through a tool (Husky for Node, the Python pre-commit framework) that writes them from a checked-in config, so every clone gets the same ones.

.husky/pre-commitbash

What Husky writes for a Node project; the Python pre-commit framework reads an equivalent .pre-commit-config.yaml instead.

#!/usr/bin/env sh
npx eslint --fix .
npx prettier --write .
git add -u

Work on two branches at once without stashing
git worktree add ../hotfix hotfix/urgentReference
This checks out hotfix/urgent into a second directory, sharing the same .git — no stash, no switching back and forth, and both working trees stay usable at the same time.

git commit --amend after pushing
The pushed commit and the amended one are now different objects with the same message — anyone who already pulled the old one now has a divergent history.
Rescue recipe →
A file was forgotten before committing
Amend it in, rather than adding a second "forgot a file" commit — unless the original commit was already pushed and shared.
Rescue recipe →
git stash pop dropped, and the stash is needed again
A dropped stash is unreachable from any ref, but its commit is not deleted immediately — the reflog and git fsck --unreachable can often still find it.
Rescue recipe →

Sources

Conventional Commits contributors — Conventional Commits 1.0.0 (2019)
GitHub — Creating a commit with multiple authors (2026)
Linux Foundation — Developer Certificate of Origin 1.1 (2004)
Git project — git-interpret-trailers documentation (2026)
Git project — githooks — hooks used by git (2026)
Git project — gitrevisions — specifying revisions and ranges (2026)
Git project — git-add documentation (2026)
Git project — git-commit documentation (2026)
Git project — git-reset documentation (2026)
Git project — git-restore documentation (2026)
Git project — git-stash documentation (2026)
Git project — git-log documentation (2026)
Git project — git-blame documentation (2026)
Git project — git-worktree documentation (2026)

5Review

Pushing & Collab

Share commits through a remote without losing anyone's work: fetch, pull, push, force-with-lease, merge versus rebase, and conflicts.

A remote is just another repository your clone knows the URL of. fetch copies its objects and updates your remote-tracking branches; nothing else changes until you merge or rebase them in.
git pull is fetch plus either a merge or a rebase — which one depends on pull.rebase, and git will refuse to guess once your branch has diverged from upstream.
A push is rejected when the remote has a commit you don't — fetch and integrate first, or force only if you are certain the remote's version is disposable.
--force-with-lease refuses to overwrite a remote-tracking ref that has moved since your last fetch; plain --force has no such check and can silently discard a teammate's push.
The rule that makes all of this safe: never rewrite commits other people have already based work on. Rebase and amend freely on a branch that is yours alone; once it's shared, only add to it.

Remotes, fetch and the state that changes

This stage's repository has a teammate who pushed while you were working locally — fetch shows what they did without touching your working tree.

git fetch originReference

Fetch updates origin/main (your remote-tracking branch) to wherever the remote's main now points. It never touches your own main, your index, or your working tree — that is what makes it safe to run at any time, as often as you like.

git pull origin mainReference

Pull is fetch followed by an integration step. Which step depends on pull.rebase: unset or false merges origin/main into your branch; true rebases your branch onto it instead Git project 2026.

Decide merge pull or rebase pull once, in config, not commit by commit

git pull's two modes
	Merge pull (default)	Rebase pull (--rebase, or pull.rebase=true)
Result	A merge commit joining your local work and the remote's	Your commits replayed on top of the remote's — no merge commit
History shape	Records exactly what happened, including the pull itself	Linear, as if you had started from the latest remote
Safe on a shared branch you also push to?	Yes	Only if you haven't pushed your local commits yet — rebase rewrites them

git pull --rebase origin mainRewrites local historyReference

Force only what you are sure is disposable, and check before you overwrite it
git push --force-with-leaseRewrites shared historyReference
--force-with-lease fails if the remote-tracking ref has moved since your last fetch — meaning someone pushed something you haven't seen — instead of silently overwriting it. --force-if-includes, used alongside it, additionally verifies that whatever updated the remote-tracking ref in the background is already in your own history before allowing the push Git project 2020. Plain --force has neither check.
git push --forceRewrites shared historyReference
Never force-push main, or any branch someone else has pulled or based work on. If their branch pointer gets silently rewound, their next pull looks clean and their commits are simply gone from the branch until someone finds them in a reflog — one they may not have, if it was your push that dropped them and they never fetched the old tip.
Choose how a branch rejoins main: merge, --no-ff, squash, or rebase
Same starting graph, four outcomes — the comparator runs all four through the same commands the terminal uses.
Resolve a conflict, in whichever marker style helps
git rerere ("reuse recorded resolution") remembers how you resolved a conflict and replays that resolution automatically the next time the same conflict appears — useful when rebasing a long branch keeps hitting the same collision on every replayed commit Git project 2026. git merge --abort (or git rebase --abort) bails out of a merge or rebase in progress and restores the state from immediately before it started.
git merge --abortDiscards workReference

git push rejected: the remote has work you don't
Fetch and integrate (merge or rebase) before pushing again — the rejection is git refusing to silently drop the remote's commits, not a bug.
Rescue recipe →
Someone force-pushed the branch you're working on
Your local history and theirs have now diverged in a way a normal pull can't reconcile; check what actually happened before choosing how to reconcile it.
Rescue recipe →
git pull made a merge commit you didn't want
Set pull.rebase if this branch should always integrate by rebasing — or run git pull --rebase explicitly each time.
Rescue recipe →

Sources

Git project — git-config documentation (2026)
Git project — Git 2.30.0 release notes (2020)
Git project — git-rerere documentation (2026)
Git project — git-fetch documentation (2026)
Git project — git-pull documentation (2026)
Git project — git-push documentation (2026)

Merge & Pull Request Process

How code moves from a feature branch into the shared trunk safely.

PR Lifecycle

Open: Ready for review. Reviewers can be requested.

PR Template Anatomy

CODEOWNERS Auto-Assignment

# .github/CODEOWNERS
# Global owners — review everything
*                   @team/platform

# Backend — Python services
/src/api/**         @backend-lead @srini

# Frontend — React components
/src/ui/**          @alice @bob

# Infrastructure
/infra/**           @team/devops

# Security-sensitive paths
/src/auth/**        @team/security

Review States

✓

ApprovedLGTM — ready to merge.

✗

Changes RequestedBlocking — must address before merge.

💬

CommentedNon-blocking feedback or questions.

Merge Strategies

Creates a merge commit that unites the two histories.

PROFull history preserved

CONHistory can become noisy

PR Size Guide

S< 50 lines

Ideal. Fast review, low risk.

M50–250 lines

Good. Single responsibility, reviewable in one sitting.

L250–500 lines

Acceptable. Consider splitting if possible.

XL500+ lines

Avoid. Approval rubber-stamping risk is high.

Code Review Process

How teams verify correctness, share knowledge, and maintain quality standards.

Reviewer Checklist — 8 Dimensions

Comment Types

🚫Blocking

"`user.password` is being logged on line 42 — this is a security incident waiting to happen."

💡Non-blocking

"nit: Could extract this into a `formatDate()` utility. Happy to merge as-is though."

❓Question

"Why are we calling `getUser()` twice here? I may be missing context."

🙌Praise

"Love how you handled the retry logic here — clean and robust."

Review SLA

PriDescriptionSLA

P0Security / Production incident fix< 1 hour

P1Breaking bug, blocking another team< 4 hours

P2Normal feature / bug PR1 business day

P3Docs, chore, low-risk refactor2 business days

Approval Workflow

Minimum 2 approvals required

CODEOWNERS must approve owned paths

Stale reviews dismissed on new push

Branch must be up to date before merge

Review Etiquette

✓ DO

✓Explain the why, not just the what

✓Suggest, don't dictate (use "consider" / "what if")

✓Acknowledge good decisions with praise

✓Separate blocking from non-blocking concerns clearly

✓Review the diff, not the person

✗ DON'T

✗Leave vague comments like "this is wrong"

✗Pile on blocking comments for style nits

✗Ghost a PR — respond even if just "looking at this tomorrow"

✗Approve without reading — rubber-stamping erodes trust

✗Request sweeping refactors unrelated to the PR scope

CI/CD Pipeline

Automated verification and delivery — the heartbeat of modern software teams.

Pipeline idle

Simulate failure

name: CI/CD Pipeline

on:
  push:
    branches: ['**']
  pull_request:

env:
  IMAGE: ghcr.io/${{ github.repository }}

jobs:
  pipeline:
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - run: npm ci
      - run: npm run lint && npm run type-check
      - run: npm test -- --coverage
      - run: npm run test:integration

      - run: npx playwright install --with-deps
      - run: npm run test:e2e
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: playwright-report
          path: playwright-report/

      - uses: github/codeql-action/init@v3
        with:
          languages: javascript, python
      - uses: github/codeql-action/analyze@v3
      - uses: aquasecurity/trivy-action@0.28.0
        with:
          scan-type: fs
          ignore-unfixed: true

      - run: npm run build

      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - uses: docker/build-push-action@v5
        with:
          push: true
          tags: ${{ env.IMAGE }}:${{ github.sha }}

      - uses: azure/k8s-deploy@v4
        with:
          manifests: k8s/

      - name: Health check
        run: |
          for i in {1..10}; do
            STATUS=$(curl -s -o /dev/null -w "%{http_code}" $URL/health)
            [ "$STATUS" = "200" ] && exit 0
            sleep 3
          done
          exit 1

      - uses: grafana/k6-action@v0.3.0
        with:
          filename: tests/load.js
          flags: --vus 50 --duration 60s

Environment Promotion Flow

How a software build travels from laptop to production safely.

Environment Ladder

Click an environment rung to see details.

Blue-Green Deployment

Canary Release

Feature Flagnew-checkout-flow is OFF — all users see legacy checkout

Release Management

Versioning, tagging, changelog generation, and release ceremonies.

Semantic Version Calculator

major

minor

patch

v2.1.0

MAJOR

Breaking change — incompatible API change. Consumers must update.

MINOR

New feature — backwards-compatible addition. Safe to upgrade.

PATCH

Bug fix — backwards-compatible fix. Always safe to upgrade.

Git Tag Anatomy

git tag -a v2.1.0 -m "Release 2.1.0"

git tagGit tag command

-aAnnotated tag (stored as full Git object with tagger, date, message)

v2.1.0Version string — v prefix is convention, not enforced

-m "…"Tag message — describes the release. Appears in `git show <tag>`

Release Candidates

Click to progress through the RC flow. Each RC gets deployed to staging and tested. Once all blockers are resolved, the final tag is cut.

Changelog from Conventional Commits

Raw commits (git log --oneline)

a1b2c3dfeat:add OAuth login via Google and GitHub

e4f5g6hfix:resolve null pointer in user.getRole()

i7j8k9lfeat!:redesign REST API — v2 endpoints

m1n2o3pdocs:update README with new setup steps

q4r5s6tfix:handle empty cart edge case at checkout

u7v8w9xperf:memoize expensive product catalog query

Hotfix Process

1.Branch off main (not develop)

2.Fix the bug in isolation

3.Merge to main + tag patch release

4.Cherry-pick or merge back to develop

Release Train Calendar (2-week sprints)

D10

D11

D12

D13

D14

Sprint start

Dev freeze

RC.1 cut

QA cycle

🚀 RELEASE

Retro

Sprint start

Post-Deployment

Deployment is the beginning, not the end. Observability, incident response, and continuous learning close the loop.

Monitoring Stack

◈APM

Application Performance Monitoring — traces, latency, throughput. (OpenTelemetry is vendor-neutral instrumentation, not a backend — it pairs with any of the tools below.)

Datadog APMNew RelicDynatraceOpenTelemetry

⚡Error Tracking

Real-time exception capture, stack traces, user context

SentryBugsnagRollbarHoneybadger

≡Log Aggregation

Centralised log storage, search, and alerting

ELK StackLoki + GrafanaSplunkDatadog Logs

◎Metrics

Time-series data, dashboards, threshold alerts

PrometheusGrafanaCloudWatchDatadog Metrics

Incident Response Flow

Detect0–2 min

Alert fires in PagerDuty / Slack. On-call engineer acknowledges.

▶ACK alert

▶Check dashboard

▶Assess severity (P1–P4)

SLA / SLO Dashboard

99.97%

Uptime (30d)

42ms

P50 Latency

187ms

P95 Latency

843ms

P99 Latency

0.03%

Error Rate

0.96

Apdex Score

Apdex = (Satisfied + Tolerating ÷ 2) ÷ Total requests, scored 0–1 against a response-time threshold. 0.96 is "Excellent."

A/B Test Result — Checkout Button Colour

Control (Blue)

3.2%

n = 12,400

Variant (Green)

3.9%

n = 12,350

Significance: 99.7%Lift +21.9%

Ship Variant B — statistically significant at p < 0.05

Feature Flag Cleanup Checklist

✓Confirm rollout has held at 100% for a full bake period

✓Remove flag evaluation code from all call sites

✓Remove flag-specific tests and mocks

✓Delete the old code path (the 'off' branch) entirely

✓Delete the flag from LaunchDarkly / ConfigCat

✓Remove the corresponding database column / config key

✓Update changelog and notify stakeholders

Documentation & Knowledge

Code that isn't documented is an asset with an expiry date. The best docs live in the same repo as the code they describe.

Documentation Types

◈API Docs

OpenAPI / Swagger

Machine-readable API specification. Auto-generates SDKs, val…

◇ADRs

Architecture Decision Records

Immutable record of a significant architectural choice, the …

≡Runbooks

Operational How-Tos

Step-by-step operator guides for routine tasks, deployments,…

◎Wiki Pages

Team Knowledge Base

Searchable, collaborative long-form knowledge. Onboarding, p…

//Code Comments

Inline Documentation

JSDoc / docstrings explaining the 'why' not the 'what'. Auto…

⬡Diagrams-as-Code

Mermaid / PlantUML / D2

Version-controlled, diff-able architecture diagrams that liv…

◇ADR Template — Live ExampleADR-0012

▾

Diagram-as-Code (Mermaid)

gitGraph
   commit id: "init"
   branch feature/auth
   checkout feature/auth
   commit id: "add login"
   commit id: "add OAuth"
   checkout main
   branch hotfix/typo
   checkout hotfix/typo
   commit id: "fix typo"
   checkout main
   merge hotfix/typo
   merge feature/auth

Documentation Quality Checklist

◎All examples tested and runnable

◎Covers the most common error cases

◎Has a 'quick start' (< 5 min to first success)

◎Version-tagged and dated

◎Searchable (indexed in Confluence / Notion / Docs site)

◎Ownership clearly attributed

◎Updated as part of the same PR that changes the code

◎Reviewed by a developer who was NOT the author

◎Docs untouched for 6+ months are flagged for re-review against the current codebase

New Team Member — Week 1 Checklist

Day 1

▶Dev environment setup guide

▶Repo access + SSH keys

▶Architecture overview doc

▶Meet the team

Day 2–3

▶First small PR (good-first-issue)

▶Code review process walkthrough

▶CI/CD pipeline tour

▶Codebase walkthrough with lead

Days 4–5

▶Own a small feature end-to-end

▶Runbook for at least one service

▶On-call shadow shift

▶30-day goals set with manager

Governance & Compliance

Git is your audit log. Every merge, every deploy, every config change is evidence — for your team and for your auditors.

Audit Trail

TimestampActorActionDetail

2024-03-15 09:12alice@co.com

PR #821 approved

feat: add payment gateway

2024-03-15 09:31ci-bot

Pipeline passed

build #1203 — all 847 tests green

2024-03-15 09:45bob@co.com

Deployed to prod

v2.14.0 → eu-west-1 (canary 5%)

2024-03-15 10:02bob@co.com

Canary promoted

5% → 100% — error rate stable

2024-03-15 14:20carol@co.com

Config changed

PAYMENT_TIMEOUT: 5s → 10s

2024-03-15 16:55alice@co.com

Tag created

v2.14.1 — hotfix: null check

2024-03-22 03:14dave@co.com

Bypassed branch protection

P1 incident — force-merged past required review (logged admin override)

Compliance Evidence Collection

CC6.1 — Logical access controls

✓Required 2 reviewers on main branch

CC7.2 — System monitoring

✓All merges logged with actor + timestamp

CC8.1 — Change management

✓No direct push to main; PRs mandatory

A1.2 — Availability monitoring

✓Deployment gate: staging tests must pass

Access Control Matrix

Developer

Lead

DevOps

Admin

Merge to main

✗

✓

✗

✓

Deploy to prod

✗

✓

Create release tag

✗

✓

Manage secrets

✗

✓

Add CODEOWNER

✗

✓

✗

✓

Delete branch

✓

Bypass branch protection

✗

✓

⚿Signed Commits with GPG

▾

License Compliance

Scanning tools: FOSSABlack DuckTLDR LegalSnyk License

MITLow

Attribution only. Use freely in proprietary software.

Apache 2.0Low

Attribution + patent grant. Notice file required.

GPL v3Low for SaaS

Derivative works must also be GPL. Copyleft triggers on distribution, not network/SaaS use — see AGPL.

LGPLMedium

Can link to LGPL library without GPL propagation.

AGPLVery High

Network use = distribution. Strongest copyleft.

BSD 2/3Low

Attribution. Non-endorsement clause (3-clause).

CI Security Scanning

Secret Scanning

GitHub secret scanning / gitleaks

Blocks pushes containing credentials.

Dependency Scanning (SCA)

Dependabot / Snyk

CVE alerts surfaced on PRs.

Team Communication & Notifications

The right signal to the right person at the right time. Too little: surprises. Too much: everyone ignores everything.

Integration Map

Notification Preferences Matrix

slack

dashboard

PR Opened

Review Requested

PR Merged

Pipeline Failed

Pipeline Passed

Deployed to Staging

Deployed to Prod

Alert Fired

Deployment Announcement Template

*🚀 Deployed to Production*  v2.15.0

*What shipped:*
• Payment gateway v2 (Stripe + Apple Pay)
• Checkout redesign — 22% fewer steps
• Fix: null pointer in order history (hotfix #863)

*Stats:*
Pipeline: ✅ 847 tests passed | Build: 2m 34s
Canary: 5% for 30min, no error rate change
Rollout: 100% of traffic as of 09:45 UTC

*Risk:* Low — canary held at 5% for 30min with no error-rate increase. No DB/schema migration in this release.

*Rollback:* `kubectl set image deploy/api api=app:v2.14.1` — safe, nothing to reverse migration-wise. Faster option: flip the Apple Pay flag off (seconds, no redeploy) if only the new payment path is misbehaving.

*Links:* Runbook | Grafana | Sentry | Release Notes
*On-call:* @alice (primary) @bob (secondary)

On-Call Rotation

A

Alice

Mar 11–17

ACTIVE

B

Bob

Mar 18–24

C

Carol

Mar 25–31

D

Dave

Apr 1–7

Incident Status Update Template

Investigating→

Identified→

Monitoring→

Resolved

We've identified a spike in 5xx errors on checkout tied to the 09:45 UTC deploy. Rolling back now.

Next update ETA15 min, or on state change

Alert Fatigue Prevention

⏱Set minimum duration thresholds — alerts must fire for >5min before paging

◉Group related alerts into a single incident, not separate pages

◈Use severity tiers: P1 pages, P2 Slack, P3 dashboard-only

◎Review and tune alert thresholds monthly — aim for <2 false positives/week

✓Auto-resolve alerts when metrics recover; no manual ACK needed

Reference

Git Commands

153 entries: what each command does, the flags you will use, examples to copy, and four safety answers — does it rewrite history, can it discard uncommitted work, is it safe on a shared branch, and how to get back if it goes wrong.

Setup & config

git configRead and write settings, per repository (.git/config), per user (~/.gitconfig) or for the whole machine.Safe

git-scm.com documentation ↗

git config set [--global|--local] <name> <value>
git config get [--global|--local] <name>
git config list [--global|--local|--show-origin]
git config unset [--global|--local] <name>
git config [--global] <name> [<value>]   # the older form, still supported

--global: Use ~/.gitconfig (or $XDG_CONFIG_HOME/git/config): your settings for every repository.
--local: Use .git/config of the current repository (the default when writing).
--system: Use the machine-wide file ($(prefix)/etc/gitconfig).
--show-origin: With list or get: show which file each value came from.
--all: With get or unset: act on every value of a multi-valued key.
--type=<type>: Check and normalise the value: bool, int, path, color, expiry-date.
-e, --edit: Open the chosen file in your editor (git config edit is the subcommand form).

git config set --global user.name "Ada Lovelace"
The name recorded in every commit you make.
git config set --global user.email ada@example.com
The email recorded with it; hosts match it to your account.
git config set --global init.defaultBranch main
Name the first branch of new repositories main (Git 2.28+).
git config set --global core.editor "code --wait"
The editor git opens for messages; --wait makes git wait for the tab to close.
git config set --global alias.lg "log --oneline --graph --all"
git lg now runs that log.
git config list --show-origin
Every setting in effect, with the file it comes from.
git config --global user.name "Ada Lovelace"
The same as the first example, in the form older guides use.
git config --list --show-origin
The older spelling of git config list.

Rewrites history?: No.
Discards uncommitted work?: No.
Safe on a shared branch?: Yes.
If it goes wrong: Set the old value again, or unset the key; config changes are not versioned.

The full list of variables is in the git-config documentation; the Appendix has a recommended ~/.gitconfig with every line explained.

Since Git 2.46: The list/get/set/unset subcommands; the older option form keeps working. See also git init, git hook.

git initCreate an empty repository: a .git directory in the current (or named) directory.Safe

git-scm.com documentation ↗

git init [-b <branch>] [--bare] [<directory>]

-b <name>, --initial-branch=<name>: Name of the first branch. Without it git uses init.defaultBranch, else master, and prints a hint that the default becomes main in Git 3.0.
--bare: Create a repository with no working tree, as servers and shared remotes use.
--object-format=<format>: sha1 (the default) or sha256. SHA-256 repositories cannot yet exchange objects with SHA-1 ones.
--template=<dir>: Copy hooks and files from this directory into the new .git.
-q, --quiet: Print only errors.

git init
Make the current directory a repository.
git init -b main my-app
Create my-app/ with a repository whose first branch is main.
git init --bare shared.git
A bare repository others can push to.

Rewrites history?: No.
Discards uncommitted work?: No.
Safe on a shared branch?: Yes.
If it goes wrong: Running it again in an existing repository is safe: it reinitialises without touching history.

Staging & committing

git statusShow the branch you are on, how it compares with its upstream, and which files are staged, changed or untracked.Safe

git-scm.com documentation ↗

git status [-s] [-b] [--] [<pathspec>…]

-s, --short: Two-column output: the index against HEAD, then the working tree against the index.
-b, --branch: In short format, add the branch and ahead/behind line.
--porcelain[=v2]: A format for scripts that does not change between git versions.
-u[<mode>], --untracked-files[=<mode>]: no, normal (the default) or all (list files inside untracked directories).
--ignored: Also list ignored files.
--show-stash: Say how many stash entries there are.
-v, --verbose: Also show the staged diff (-vv adds the unstaged one).

git status
The long form, with a hint for the next command under each section.
git status -sb
One line per file plus the branch line; the form most people alias.

Rewrites history?: No.
Discards uncommitted work?: No.
Safe on a shared branch?: Yes.
If it goes wrong: Nothing to recover: it only reads the repository.

See also git diff, git add, git restore.

git addCopy the current content of files into the index (the staging area), so the next commit records it.Safe

git-scm.com documentation ↗

git add [-A | -u] [-p] [-n] [--] <pathspec>…

-A, --all: Stage every change in the working tree: new, modified and deleted files.
-u, --update: Stage modifications and deletions of tracked files only; new files stay untracked.
-p, --patch: Choose hunks one at a time (y/n/s to split/e to edit).
-N, --intent-to-add: Record that a new file will be added, so git diff shows it; its content is added later.
-n, --dry-run: Show what would be staged.
-f, --force: Add a file even though .gitignore ignores it.
--renormalize: Re-apply line-ending and filter rules to tracked files (after changing .gitattributes).

git add app.js
Stage one file.
git add -p
Stage part of your changes and leave the rest for another commit.
git add -A
Stage everything, deletions included.

Rewrites history?: No.
Discards uncommitted work?: No.
Safe on a shared branch?: Yes.
If it goes wrong: git restore --staged <file> unstages it again; the working tree is not changed.

git add -pStage selected hunks of a file instead of the whole file, so one commit holds one change.Safe

git-scm.com documentation ↗

git add -p [<pathspec>…]

-p, --patch: Walk the hunks: y stage, n skip, s split into smaller hunks, e edit the hunk, q quit, ? help.
-U<n>, --unified=<n>: Show n lines of context around each hunk.

git add -p src/app.js
Stage the fix but not the debugging line next to it.
git diff --staged
Check what you staged before committing.

Rewrites history?: No.
Discards uncommitted work?: No.
Safe on a shared branch?: Yes.
If it goes wrong: git restore --staged -p unstages hunks the same way.

The page's engine does not run -p (an interactive, per-hunk prompt); run it in your own terminal.

See also git add, git restore, git commit.

git rmDelete files from the working tree and the index; the next commit records the deletion.Safe

git-scm.com documentation ↗

git rm [--cached] [-r] [-f] [-n] [--] <pathspec>…

--cached: Remove from the index only: the file stays on disk, now untracked. The way to stop tracking a file.
-r: Recurse into directories.
-f, --force: Remove even if the file has changes that are not committed.
-n, --dry-run: List what would be removed.

git rm old.js
Delete a file and stage the deletion.
git rm --cached .env
Stop tracking .env but keep it on disk (then add it to .gitignore).

Rewrites history?: No.
Discards uncommitted work?: Only with -f: without it git refuses to remove a file whose changes are not committed.
Safe on a shared branch?: Yes.
If it goes wrong: Committed content is in history: git restore --source=HEAD -- <file>, or git checkout HEAD -- <file>.

Removing a file does not remove it from history. A committed secret must be rotated, then purged with git filter-repo (Stage 13).

See also git mv, git restore, git clean.

git mvRename or move a file and stage the rename in one step.Safe

git-scm.com documentation ↗

git mv [-f] [-n] [-k] <source> <destination>

-f, --force: Overwrite an existing destination.
-n, --dry-run: Show what would happen.
-k: Skip moves that would fail instead of stopping.

git mv app.js server.js
Git stores no renames: log --follow and diff detect them from content similarity.

Rewrites history?: No.
Discards uncommitted work?: No.
Safe on a shared branch?: Yes.
If it goes wrong: Nothing to recover: it does not change commits or your files.

Branches & merging

git branchList, create, rename, copy and delete branches. A branch is a movable name for one commit.Rewrites local history

git-scm.com documentation ↗

git branch [-a | -r] [-v | -vv] [--merged | --no-merged] [--sort=<key>]
git branch <name> [<start-point>]
git branch (-m | -M) [<old>] <new>
git branch (-d | -D) <name>…
git branch -u <upstream> [<name>]

-a, --all: List local and remote-tracking branches.
-r, --remotes: List remote-tracking branches.
-v, -vv, --verbose: Show each tip's id and subject; -vv adds the upstream and ahead/behind.
--merged [<commit>]: Only branches whose tip is reachable from <commit> (default HEAD): safe to delete.
--no-merged [<commit>]: Only branches with commits <commit> does not have.
--contains <commit>: Only branches that contain <commit>.
-d, --delete: Delete a branch; refuses if it is not merged into its upstream or HEAD.
-D: Delete even if it is not merged (the same as --delete --force).
-m, --move: Rename; -M renames over an existing name.
-c, --copy: Copy a branch with its config and reflog.
-f, --force: Reset an existing branch to <start-point>.
-u <upstream>, --set-upstream-to=<upstream>: Set the branch's upstream.
--show-current: Print the current branch name (Git 2.22+).
--sort=<key>: Sort, for example --sort=-committerdate for most recent first.

git branch -vv
Every branch, its upstream and how far ahead or behind it is.
git branch --merged main
Branches already merged into main.
git branch -d feature/login
Delete a merged branch.
git branch -m master main
Rename a branch.
git branch --sort=-committerdate
Most recently changed branches first.

Rewrites history?: -f moves an existing branch; -D deletes one with unmerged commits.
Discards uncommitted work?: No uncommitted work; -D can leave commits that no branch names.
Safe on a shared branch?: Yes: it only changes your local branch names.
If it goes wrong: A deleted branch's commits: find the tip in git reflog (HEAD's) and run git branch <name> <id>.

git switchSwitch to another branch, or create a branch and switch to it; the working tree and index change to match.Safe

git-scm.com documentation ↗

git switch <branch>
git switch -c <new-branch> [<start-point>]
git switch --detach <commit>
git switch -

-c <name>, --create <name>: Create the branch at <start-point> (default HEAD) and switch to it.
-C <name>, --force-create <name>: The same, resetting the branch if it exists.
-d, --detach: Check out a commit without a branch (detached HEAD).
--orphan <name>: Start a branch with no history and an empty index.
-t, --track: Set the new branch's upstream to the start point.
--no-guess: Do not create a local branch from a same-named remote-tracking branch.
--discard-changes, -f, --force: Switch even with local changes; they are thrown away.
-m, --merge: Carry local changes across by merging them into the target.

git switch main
Go to main.
git switch -c feature/login
Create feature/login here and switch to it.
git switch -
Back to the previous branch.
git switch feature/x
If only origin/feature/x exists, this creates a local branch that tracks it.

Rewrites history?: No.
Discards uncommitted work?: Only with -f / --discard-changes. Otherwise git refuses when a local change would be overwritten, and carries other changes with you.
Safe on a shared branch?: Yes.
If it goes wrong: git switch - goes back.

Since Git 2.23: The branch-switching half of git checkout. See also git checkout, git branch, git restore.

git checkoutThe older command that both switches branches and restores files. Still supported; git switch and git restore split its two jobs.Discards work

git-scm.com documentation ↗

Replaced by git switch, git restore.

git checkout <branch>              # now: git switch <branch>
git checkout -b <new> [<start>]    # now: git switch -c <new> [<start>]
git checkout <commit>              # now: git switch --detach <commit>
git checkout [<commit>] -- <path>  # now: git restore [--source=<commit>] -- <path>

-b <new>: Create a branch and switch to it.
-B <new>: Create or reset a branch and switch to it.
--detach: Detach HEAD at the commit.
-f, --force: Throw away local changes when switching; with paths, ignore unmerged entries.
--ours, --theirs: With paths during a conflict: take one side.
-p, --patch: Pick hunks to restore.

git checkout feature/login
Switch branches (git switch feature/login).
git checkout HEAD~3 -- src/payments.js
Restore a file from three commits ago (git restore --source=HEAD~3 -- src/payments.js).

Rewrites history?: No.
Discards uncommitted work?: Yes with paths: git checkout -- <path> overwrites edits in those paths without asking.
Safe on a shared branch?: Yes.
If it goes wrong: None for overwritten edits; switching back with git checkout - is fine.

One word doing two jobs is why git checkout is easy to misuse: git checkout name switches to a branch if one is called name, and otherwise overwrites a file called name.

History & inspection

git logList commits reachable from HEAD (or the revisions you name), newest first, with filters and formats.Safe

git-scm.com documentation ↗

git log [<options>] [<revision-range>] [[--] <path>…]

--oneline: One line per commit: short id and subject.
--graph: Draw the branch structure in text beside the commits.
--all: Start from every ref, not just HEAD.
-n <n>, --max-count=<n>: Show at most n commits.
-p, --patch: Show each commit's diff.
--stat: Show each commit's per-file summary.
--author=<pattern>: Only commits whose author matches.
--since=<date>, --until=<date>: Only commits in a date range ("2 weeks ago", "2026-01-01").
-S <string>: The pickaxe: commits that change how many times <string> occurs — when a line appeared or vanished.
-G <regex>: Commits whose diff adds or removes a line matching <regex>.
--follow: With one file: continue past renames.
--first-parent: Follow only the first parent of merges: main's own history.
--merges, --no-merges: Only merge commits, or none.
--format=<format>: Custom output: %h %s %an %ar and more (see git help log, PRETTY FORMATS).
-L <start>,<end>:<file>: The history of a range of lines.

git log --oneline --graph --all
The whole repository's shape.
git log main..feature
Commits on feature that main does not have (A..B).
git log main...feature
Commits on either side but not both (A...B), with --left-right to see which.
git log -S "apiKey" --oneline
Which commit added or removed the string apiKey.
git log --follow -- src/auth/login.ts
A file's history across renames.
git log --merges --first-parent --oneline main
The merges into main: one line per merged pull request.

Rewrites history?: No.
Discards uncommitted work?: No.
Safe on a shared branch?: Yes.
If it goes wrong: Nothing to recover: it only reads the repository.

git showShow one object: a commit's message and diff, an annotated tag, a tree's listing or a file at a revision.Safe

git-scm.com documentation ↗

git show [<options>] [<object>…]
git show <commit>:<path>

--stat: The summary instead of the full diff.
--name-only, --name-status: Just the files changed.
-s, --no-patch: The commit header and message only.
--format=<format>: Custom header, as in git log.

git show
The last commit and its diff.
git show HEAD~2:src/app.ts
The file as it was two commits ago.
git show v1.0.0
An annotated tag: the tagger and message, then the commit.

Rewrites history?: No.
Discards uncommitted work?: No.
Safe on a shared branch?: Yes.
If it goes wrong: Nothing to recover: it only reads the repository.

See also git log, git cat-file, git diff.

git blameShow, for each line of a file, the commit and author that last changed it.Safe

git-scm.com documentation ↗

git blame [-w] [-M] [-C] [-L <range>] [<rev>] [--] <file>

-L <start>,<end>: Only these lines.
-w: Ignore whitespace changes.
-M: Detect lines moved within the file.
-C: Detect lines moved or copied from other files changed in the same commit; twice, also from the commit that created the file; three times, from any commit.
--ignore-rev <rev>: Skip a commit (a formatting sweep); blame the commit before it.
--ignore-revs-file <file>: Skip every commit listed (conventionally .git-blame-ignore-revs).

git blame -w -L 40,60 src/payments.ts
Who last changed lines 40–60, ignoring whitespace.
git config set blame.ignoreRevsFile .git-blame-ignore-revs
Always skip the commits in that file (GitHub reads it too).

Rewrites history?: No.
Discards uncommitted work?: No.
Safe on a shared branch?: Yes.
If it goes wrong: Nothing to recover: it only reads the repository.

Remotes & sharing

git remoteManage the named remotes (origin, upstream…) a repository fetches from and pushes to.Safe

git-scm.com documentation ↗

git remote [-v]
git remote add <name> <url>
git remote rename <old> <new>
git remote remove <name>
git remote set-url <name> <url>
git remote show <name>
git remote prune <name>

-v, --verbose: Show each remote's fetch and push URL.
add <name> <url>: Register a remote; -f fetches it straight away.
set-url <name> <url>: Change a remote's URL (after a repository moves, or to switch HTTPS↔SSH).
show <name>: Branches on the remote, which are tracked, and what push and pull would do.
prune <name>: Delete remote-tracking branches whose branch was deleted on the remote.
rename, remove: Rename a remote (its remote-tracking branches too), or remove it.

git remote -v
Where origin points.
git remote add upstream https://github.com/original/repo.git
Track the project you forked from.
git remote set-url origin git@github.com:new-org/repo.git
The repository moved.

Rewrites history?: No.
Discards uncommitted work?: No.
Safe on a shared branch?: Yes.
If it goes wrong: Remote settings live in .git/config; add the remote back to restore it.

git fetchDownload new commits and refs from a remote and update the remote-tracking branches (origin/main…). Your branches and files do not change.Safe

git-scm.com documentation ↗

git fetch [<remote>] [<refspec>…]
git fetch --all

--all: Fetch every remote.
-p, --prune: Delete remote-tracking branches that no longer exist on the remote.
--tags: Fetch all tags as well.
--depth=<n>, --unshallow: Deepen a shallow clone, or make it complete.
--dry-run: Show what would be fetched.
-f, --force: Allow non-fast-forward updates of the refs being fetched into.

git fetch
Update origin/* from origin.
git fetch --all --prune
Every remote, and forget branches deleted there.
git log --oneline main..origin/main
After fetching: what the remote has that you do not.

Rewrites history?: No.
Discards uncommitted work?: No.
Safe on a shared branch?: Yes.
If it goes wrong: Nothing to recover: only remote-tracking refs move, and their reflogs record it.

See also git pull, git remote, git push.

git pullFetch, then integrate the upstream branch into the current branch — by merging (the default), rebasing or fast-forwarding only.Safe

git-scm.com documentation ↗

git pull [--rebase | --no-rebase | --ff-only] [<remote> [<branch>]]

-r, --rebase: Rebase your local commits onto the fetched branch instead of merging.
--no-rebase: Merge (creates a merge commit when the histories diverged).
--ff-only: Update only if it is a fast-forward; otherwise stop.
--autostash: Stash local changes around the pull.
--squash, --no-commit: Passed to the merge.

git pull --rebase
Replay your unpushed commits on top of what others pushed: a straight history.
git pull --ff-only
Update a branch you do not commit to (a local main, say).
git config set --global pull.rebase true
Make --rebase the default.

Rewrites history?: With --rebase: your unpushed commits get new ids. Merging and fast-forwarding rewrite nothing.
Discards uncommitted work?: No; it refuses when local changes conflict (use --autostash).
Safe on a shared branch?: Yes: it only changes your branch.
If it goes wrong: git reset --hard ORIG_HEAD undoes the merge or rebase it just did.

When your branch and the upstream have diverged and you have not chosen how to reconcile them, git pull stops with "Need to specify how to reconcile divergent branches" and names the three settings: pull.rebase false (merge), pull.rebase true (rebase) and pull.ff only.

See also git fetch, git merge, git rebase.

git pushUpload commits and move a remote's branches to match yours. Refused unless the remote branch is an ancestor of what you push.Safe

git-scm.com documentation ↗

git push [-u] [<remote> [<refspec>…]]
git push <remote> <local>:<remote-branch>
git push --tags

-u, --set-upstream: Record the remote branch as the upstream, so plain git push and git pull know where to go.
--force-with-lease: Overwrite the remote branch only if it is still where your remote-tracking branch says (see its entry).
--force-if-includes: With --force-with-lease: also require that the remote tip is in your branch's reflog (Git 2.30+).
-f, --force: Overwrite unconditionally (see its entry).
-d, --delete: Delete the named remote branches.
--tags: Push every tag.
--follow-tags: Also push annotated tags that point into the pushed commits.
-n, --dry-run: Show what would be updated.
--atomic: All refs update or none do.

git push -u origin feature/login
Publish a new branch and set its upstream.
git push
Push the current branch to its upstream.
git push origin v1.2.0
Publish one tag.

Rewrites history?: No, without --force or --force-with-lease: a non-fast-forward push is rejected.
Discards uncommitted work?: No.
Safe on a shared branch?: Yes.
If it goes wrong: A pushed commit is public; undo it with git revert and push the revert.

git push --force-with-leaseOverwrite a remote branch after rewriting history — but only if nobody pushed to it since you last fetched.Rewrites shared history

git-scm.com documentation ↗

git push --force-with-lease [--force-if-includes] [<remote> <branch>]
git push --force-with-lease=<ref>:<expected-id> <remote> <branch>

--force-with-lease: Require each remote branch to equal your remote-tracking branch for it (origin/x).
--force-with-lease=<ref>:<expect>: Require <ref> to be exactly <expect>: the form git documents as not experimental.
--force-if-includes: Also require the remote tip to be in your branch's reflog, which catches a background fetch having updated origin/x (Git 2.30+).

git push --force-with-lease
After rebasing your own branch.
git push --force-with-lease --force-if-includes
The same, safe even if an editor fetches in the background.
git config set --global alias.pushf "push --force-with-lease --force-if-includes"
Make the safe form the easy one.

Rewrites history?: Yes: it replaces the remote branch's history.
Discards uncommitted work?: Only commits you have seen (they were in origin/x); a teammate's newer push makes it fail instead.
Safe on a shared branch?: Only on a branch you alone push to, or by agreement. Never on main.
If it goes wrong: Anyone who had the old tip can push it back; the old commits are in your reflog (<branch>@{1}).

A plain git fetch updates origin/x, and then --force-with-lease alone will overwrite whatever that fetch brought in. --force-if-includes closes that gap.

Since Git 2.30: --force-if-includes. See also git push, git push --force, git rebase, git commit --amend.

git push --forceOverwrite a remote branch with yours unconditionally. Commits others pushed since you last fetched are removed from it.Rewrites shared history

git-scm.com documentation ↗

Replaced by git push --force-with-lease.

git push --force <remote> <branch>
git push <remote> +<branch>

-f, --force: Skip the fast-forward check for every ref pushed.
+<refspec>: Force just this ref (git push origin +feature).

git push --force-with-lease
Use this instead: it refuses when the remote has commits you have not seen.

Rewrites history?: Yes.
Discards uncommitted work?: Yes, others' pushed commits, silently.
Safe on a shared branch?: No.
If it goes wrong: Someone who still has the lost commits must push them again; the remote keeps no reflog you can reach.

Undo & recovery

git resetMove the current branch to another commit and, depending on the mode, reset the index and working tree to match. With paths, it only unstages.Discards work

git-scm.com documentation ↗

git reset [--soft | --mixed | --hard | --keep | --merge] [<commit>]
git reset [<commit>] -- <path>…     # unstage paths

--soft: Move the branch only. The index and files keep your changes, now staged.
--mixed: The default: move the branch and reset the index. Changes stay in the files, unstaged.
--hard: Move the branch and overwrite the index and working tree. Uncommitted changes to tracked files are lost.
--keep: Like --hard, but refuse if a file with local changes would be overwritten.
--merge: Abort a merge while keeping unrelated local changes.
-q, --quiet: Print only errors.

git reset HEAD~1
Undo the last commit, keep its changes in the files (unstaged). The same as git reset --mixed HEAD~1.
git reset app.js
Unstage app.js (git restore --staged app.js does the same).
git reset --keep origin/main
Reset to the remote, refusing if that would overwrite local edits.

Rewrites history?: Yes when <commit> is not the current one: the branch stops containing the commits after it.
Discards uncommitted work?: --hard does (and --merge for conflicted paths). --soft and --mixed keep every change in the files.
Safe on a shared branch?: Only if the commits leaving the branch were never pushed.
If it goes wrong: Commits: git reset --hard ORIG_HEAD or <branch>@{1}. Discarded uncommitted edits: none.

git reset --softMove the branch back but keep everything staged: the undone commits' changes are ready to commit again.Rewrites local history

git-scm.com documentation ↗

git reset --soft <commit>

--soft: Touch neither the index nor the working tree.

git reset --soft HEAD~3 && git commit -m "Add search"
Squash the last three commits into one.
git reset --soft HEAD~1
Undo the last commit; its changes stay staged.

Rewrites history?: Yes: commits leave the branch.
Discards uncommitted work?: No.
Safe on a shared branch?: Only if the commits were never pushed.
If it goes wrong: git reset --soft ORIG_HEAD (or <branch>@{1}) puts the branch back.

Tags & releases

git tagName a commit permanently: lightweight tags are bare names, annotated tags are objects with a tagger, date, message and optional signature.Safe

git-scm.com documentation ↗

git tag [-a | -s] [-m <msg>] <name> [<commit>]
git tag -l [<pattern>] [--contains <commit>] [--sort=<key>]
git tag -d <name>…

-a, --annotate: Create an annotated tag (a tag object). Use these for releases.
-s, --sign: Create a signed annotated tag.
-m <msg>: The tag message.
-l, --list [<pattern>]: List tags, for example -l "v1.*".
--contains <commit>: Only tags whose commit contains <commit>: which releases include a fix.
--sort=<key>: For example --sort=-v:refname for newest version first.
-n<num>: Show the first lines of each annotation.
-d, --delete: Delete tags (locally).
-f, --force: Replace an existing tag.

git tag -a v1.2.0 -m "Release 1.2.0"
An annotated release tag on HEAD.
git push origin v1.2.0
Tags are not pushed with branches; push them by name (or --follow-tags).
git tag --contains a1b2c3d
Every release that includes commit a1b2c3d.
git tag -l "v2.*" --sort=-v:refname
2.x releases, newest first.

Rewrites history?: -f moves a tag, which is a rewrite for anyone who fetched it.
Discards uncommitted work?: No.
Safe on a shared branch?: Yes, until you move or delete a pushed tag; git fetch does not update tags people already have.
If it goes wrong: A deleted local tag: git tag <name> <id> (the id is in the output of -d).

Never move a published release tag; tag a new version instead. Clients that fetched the old tag keep it.

git archiveWrite a tar or zip of a commit's files, without the .git directory.Safe

git-scm.com documentation ↗

git archive [--format=<fmt>] [--prefix=<dir>/] [-o <file>] <tree-ish> [<path>…]

--format=<fmt>: tar, tgz, tar.gz or zip (inferred from -o's extension).
--prefix=<dir>/: Put every file under <dir>/ in the archive.
-o <file>, --output=<file>: Write to a file.
--remote=<repo>: Ask a remote to produce the archive (if the server allows it).

git archive --format=tar.gz --prefix=app-1.2.0/ -o app-1.2.0.tar.gz v1.2.0
A release tarball from a tag.

Rewrites history?: No.
Discards uncommitted work?: No.
Safe on a shared branch?: Yes.
If it goes wrong: Nothing to recover: it only reads the repository.

Paths marked export-ignore in .gitattributes are left out, and export-subst fills in placeholders such as $Format:%H$.

Rewriting history

git filter-repoRewrite a whole repository's history: remove a file or secret everywhere, move paths, change emails. A separate tool the git project recommends over filter-branch.Rewrites shared history

git-filter-repo (Elijah Newren) ↗

git filter-repo --invert-paths --path <path>
git filter-repo --replace-text <file>
git filter-repo --mailmap <file>

--path <path> --invert-paths: Remove <path> from every commit.
--replace-text <file>: Replace strings (secrets) listed in <file> in every file of every commit.
--subdirectory-filter <dir>: Make <dir> the new root (split a directory out).
--mailmap <file>: Rewrite author and committer names and emails.
--analyze: Report sizes and paths first, to see what to remove.

git filter-repo --invert-paths --path .env
Remove .env from all history (in a fresh clone).
git push --force --all && git push --force --tags
Publish the rewritten history; every clone must be re-cloned.

Rewrites history?: Yes: every commit from the first changed one onward gets a new id, on every branch.
Discards uncommitted work?: It refuses to run outside a fresh clone unless --force, to avoid losing local work.
Safe on a shared branch?: It rewrites shared history by design: coordinate, and have everyone re-clone.
If it goes wrong: Keep the original clone until the rewrite is verified.

A leaked secret must be rotated first: rewriting history does not remove copies in forks, clones, caches or pull request refs on the host. GitHub's guide to removing sensitive data covers the host side.

See also git filter-branch, git log -S. Not part of git: install git-filter-repo (Elijah Newren) separately.

git filter-branchThe original history-rewriting command. Its own documentation warns against it and points to git filter-repo.Rewrites shared history

git-scm.com documentation ↗

Replaced by git filter-repo.

git filter-branch [--index-filter <cmd>] [--tree-filter <cmd>] [--] <rev-list-options>

--index-filter <cmd>: Rewrite the index of each commit (fast).
--tree-filter <cmd>: Check out each commit and run <cmd> in it (slow).
--prune-empty: Drop commits that become empty.

git filter-repo --invert-paths --path secrets.txt
What to run instead.

Rewrites history?: Yes.
Discards uncommitted work?: It keeps the old refs under refs/original/.
Safe on a shared branch?: No.
If it goes wrong: refs/original/ holds the old branch tips until you delete them.

Large repos & maintenance

git sparse-checkoutCheck out only some directories of a large repository; the rest stays in history but not on disk.Safe

git-scm.com documentation ↗

git sparse-checkout set <dir>…
git sparse-checkout add <dir>…
git sparse-checkout list
git sparse-checkout disable

set <dir>…: Check out only these directories (plus files at the top level).
add <dir>…: Add directories to the set.
list: The current directories.
disable: Go back to a full checkout.
reapply: Re-apply the rules after a merge brought in files outside them.
--no-cone: Use full gitignore-style patterns instead of directories (deprecated).

git clone --filter=blob:none --sparse https://github.com/org/monorepo.git
Start with almost nothing on disk.
git sparse-checkout set services/api packages/shared
Work on just these.

Rewrites history?: No.
Discards uncommitted work?: No: files with uncommitted changes outside the new set stay on disk, and git warns about them.
Safe on a shared branch?: Yes.
If it goes wrong: git sparse-checkout disable restores every file.

Since Git 2.25: The sparse-checkout command. Cone mode (whole directories) is the default; non-cone patterns are deprecated since 2.37. See also git clone --filter, git worktree, scalar.

git clone --depthShallow clone: only the last n commits. Fast for CI; limited for development, because history commands see only those commits.Safe

git-scm.com documentation ↗

git clone --depth <n> <url>
git fetch --unshallow

--depth <n>: Fetch only n commits of each branch fetched (implies --single-branch).
--shallow-since=<date>: Fetch commits after a date.
--no-single-branch: Shallow history for every branch.

git clone --depth 1 https://github.com/org/app.git
What CI checkout steps do by default (actions/checkout fetches depth 1).
git fetch --unshallow
Fetch the rest of the history later.

Rewrites history?: No.
Discards uncommitted work?: No.
Safe on a shared branch?: Yes.
If it goes wrong: Nothing to recover: it does not change commits or your files.

git log, blame and bisect stop at the shallow boundary, and merge-base can fail. For developers, prefer a partial clone (--filter=blob:none).

Patches & email

git request-pullPrint a summary of changes for a maintainer to pull, in the format the Linux kernel's email workflow uses.Safe

git-scm.com documentation ↗

git request-pull <start> <url> [<end>]

-p: Include the patch text.

git request-pull v1.0 https://example.com/repo.git main
What main adds since v1.0, and where to pull it from.

Rewrites history?: No.
Discards uncommitted work?: No.
Safe on a shared branch?: Yes.
If it goes wrong: Nothing to recover: it only reads the repository.

Plumbing

git cat-filePrint an object — blob, tree, commit or tag — by id, or its type and size. The way to look inside the object store.Safe

git-scm.com documentation ↗

git cat-file -p <object>
git cat-file -t <object>
git cat-file -s <object>

-p: Pretty-print the content.
-t: The object's type.
-s: Its size in bytes.
-e: Exit 0 if it exists.
--batch: Read ids from stdin, print each object.

git cat-file -p HEAD
The raw commit: tree, parent, author, committer, message.
git cat-file -p HEAD^{tree}
The top-level tree: mode, type, id, name per entry.

Rewrites history?: No.
Discards uncommitted work?: No.
Safe on a shared branch?: Yes.
If it goes wrong: Nothing to recover: it only reads the repository.

The Git Model reference's object inspector builds these objects in the browser, with the same ids.

git hash-objectCompute the id git would give some content (sha1 of "blob <size>\0<content>"), and optionally store it.Safe

git-scm.com documentation ↗

git hash-object [-w] [--stdin] [<file>…]

-w: Write the object into the repository.
--stdin: Read content from standard input.
-t <type>: Hash as another type (default blob).

printf '' | git hash-object --stdin
e69de29bb2d1d6434b8b29ae775ad8c2e48c5391: the empty blob, in every repository.

Rewrites history?: No.
Discards uncommitted work?: No.
Safe on a shared branch?: Yes.
If it goes wrong: Nothing to recover: it only reads the repository.

Other tools & systems

gitkGit's built-in history browser (Tk). git gui is its companion for committing.Safe

git-scm.com documentation ↗

gitk [--all] [<revision-range>]
git gui

--all: Every ref.

gitk --all &
Browse the whole graph.

Rewrites history?: No.
Discards uncommitted work?: No.
Safe on a shared branch?: Yes.
If it goes wrong: Nothing to recover: it only reads the repository.

Rescue

“I did X — how do I undo it?” 27 situations, each with the exact commands in order, a safety rating, and a Preview that loads the broken repository so you can run the fix and watch the graph first.

Find what happened, check the When line, and run the steps in order. Preview loads a repository in exactly that broken state; each step's Run applies it there first. Every recipe here is tested against real git: the broken state is recorded from git 2.55.0, and the fix is checked to produce the outcome it states.

The last commit

I want to undo my last commit but keep the changes

Rewrites local history

When: The commit is not pushed.

git reset --soft HEAD~1Rewrites local history
Move the branch back one commit. The changes stay staged, ready to commit again. (git reset HEAD~1 leaves them unstaged instead.)
git status
The undone commit's files are listed under Changes to be committed.

Fixed when: main is back at Add README, and parser.js is staged with the undone commit's content.

Otherwise: Pushed already? Use git revert HEAD instead, which adds an undoing commit (see "Undo a commit I already pushed").

Commands: git reset --soft, git reset, git revert

I made a typo in my last commit message

Rewrites local history

When: The commit is not pushed.

git commit --amend -m "Fix the login bug"Rewrites local history
Replace the last commit with one that has the new message (and a new id).

Fixed when: The tip commit reads "Fix the login bug" and sits directly on Add README; there is still one commit, not two.

Otherwise: Pushed already? Amending means a force push. On a branch only you use: amend, then git push --force-with-lease. On a shared branch, leave the typo.

Commands: git commit --amend

I forgot to add a file to my last commit

Rewrites local history

When: The commit is not pushed.

git add parser.test.js
Stage the missing file.
git commit --amend --no-editRewrites local history
Fold it into the last commit and keep its message.

Fixed when: The Add parser commit now contains both parser.js and parser.test.js.

Commands: git commit --amend, git add

I amended the wrong commit, or amended when I meant to make a new one

Rewrites local history

When: The amended commit is not pushed.

git reset --soft HEAD@{1}Rewrites local history
HEAD@{1} is where HEAD was before the amend: the original commit. --soft keeps the amend's extra changes staged.
git commit -m "Add lexer"
Commit them as a separate commit, as intended.

Fixed when: Add parser is back as it was, and the lexer change is its own commit on top.

Commands: git commit --amend, git reflog, git reset --soft

I want to combine my last few commits into one

Rewrites local history

When: The commits are on your own branch and not yet merged or shared.

git reset --soft HEAD~3Rewrites local history
Move the branch back three commits; all their changes stay staged.
git commit -m "Add search"
Record them as one commit.

Fixed when: feature/search has one commit, Add search, containing all three changes. (git rebase -i with squash does the same and lets you keep some commits.)

Otherwise: Already pushed to a branch others use? Squash when merging instead (the host's Squash and merge, or git merge --squash).

Commands: git reset --soft, git rebase -i, git merge --squash

My commit has the wrong name or email

Rewrites local history

When: The commit is not pushed.

git config user.name "Ada Lovelace"
Fix the identity for this repository (add --global for all of them).
git config user.email ada@example.com
Hosts link commits to your account by this email.
git commit --amend --reset-author --no-editRewrites local history
Rewrite the last commit with the corrected author.

Fixed when: The last commit's author is Ada Lovelace <ada@example.com>.

Otherwise: Many commits? git rebase --exec "git commit --amend --no-edit --reset-author" <base> rewrites each one. A .mailmap file changes how names display, without rewriting anything.

Commands: git commit --amend, git config

Branches and HEAD

I committed to main instead of a new feature branch

Rewrites local history

When: The commit is not pushed.

git branch feature/login
Create the branch at the commit you just made, so it keeps the work.
git reset --keep HEAD~1Rewrites local history
Move main back one commit. --keep refuses if that would overwrite local changes.
git switch feature/login
Carry on where the commit now lives.

Fixed when: main is back at Add README; feature/login has Add login form, and you are on it.

Otherwise: Pushed main already? Leave main alone: create the branch, then revert the commit on main with git revert.

Commands: git branch, git reset, git switch

I committed to main but it belongs on a branch that already exists

Rewrites local history

When: The commit is not pushed.

git switch feature/search
Go to the branch the commit belongs on.
git cherry-pick main
Copy main's tip commit onto it (a new commit with the same changes).
git switch main
Back to main…
git reset --keep HEAD~1Rewrites local history
…and remove the commit from it.

Fixed when: feature/search ends with Add search; main is back at Add README.

Commands: git cherry-pick, git reset

I deleted a branch that had work on it

Safe

When: It happened recently (reflog entries last 90 days, or 30 for unreachable commits).

git reflog
Find the last commit you made or checked out on that branch; git branch -D also printed its id (was …).
git branch feature/export HEAD@{1}
Here the branch tip is HEAD@{1}, the commit before you switched away. Use the id from the reflog in general.

Fixed when: feature/export exists again, pointing at Add CSV export.

Otherwise: Deleted on the remote too? Restore it locally, then git push -u origin feature/export.

Commands: git reflog, git branch -D

I'm in 'detached HEAD' and made commits

Safe

When: You are still on the detached commits.

git switch -c fix/attempt
Give the commits a branch; nothing else changes.

Fixed when: fix/attempt holds Try a fix, and HEAD is attached to it.

Otherwise: Already switched away? git warned you with the commit's id; or run git branch fix/attempt HEAD@{1}.

Commands: git switch --detach, git switch, git reflog

Lost work

I ran git reset --hard and lost commits

Rewrites local history

When: The commits were committed (uncommitted edits cannot come back).

git reflog
Every place HEAD has been. The line before the reset is the commit you lost.
git reset --hard HEAD@{1}Discards work
Go back to it. (Or git branch rescued HEAD@{1} to keep both.)

Fixed when: main points at Add payments again.

Commands: git reflog, git reset --hard

I dropped a stash I still needed

Safe

When: You still have the id git printed (Dropped refs/stash@{0} (…)).

git stash apply f3b40664f915ae6eedaa6741a6a231045a6e2a9e
A stash is a commit; the id from the Dropped line still reaches it until gc prunes it (two weeks by default).

Fixed when: app.js has the work-in-progress line back.

Otherwise: Lost the id? git fsck --unreachable | grep commit lists candidates; git show <id> to find the right one.

Commands: git stash, git fsck

I deleted a file and committed the deletion

Safe

When: Any time: the file is still in history.

git restore --source=HEAD~1 --staged --worktree README.mdDiscards work
Take the file from the commit before the deletion, into the index and the working tree.
git commit -m "Restore README"
Record it again.

Fixed when: README.md is back in the working tree and in the latest commit.

Otherwise: Deleted but not committed? git restore README.md is enough.

Commands: git restore, git log

Merges and rebases

I merged the wrong branch (not pushed yet)

Rewrites local history

When: The merge is the last thing you did and is not pushed.

git reset --hard ORIG_HEADDiscards work
ORIG_HEAD is where main was before the merge. The tree is clean after a merge, so --hard discards nothing.

Fixed when: main is back at Update app, without the merge; feature/beta is untouched.

Otherwise: Pushed? Use git revert -m 1 on the merge commit (next recipe).

Commands: git reset --hard, git merge

I merged and pushed a branch that broke main

Safe

When: The merge is on the shared main.

git revert -m 1 --no-edit HEAD
A new commit that undoes the merge's changes. -m 1 means "relative to main", the first parent.
git push
Everyone gets the undo; no history is rewritten.

Fixed when: origin's main ends with a revert commit, and beta.js is gone from the working tree.

Otherwise: To merge the branch again later, revert the revert first: git merges nothing otherwise, because its commits are already in main's history.

Commands: git revert

My merge has conflicts and I want to stop

Discards work

When: The merge is still in progress (git status says You have unmerged paths).

git merge --abortDiscards work
Put everything back as it was before git merge. Resolutions you made are lost.

Fixed when: No merge in progress, no conflicts, and app.js is main's version.

Commands: git merge --abort, git merge, git rerere

My rebase finished but the result is wrong

Rewrites local history

When: Right after the rebase (ORIG_HEAD), or any time via the branch's reflog.

git reset --hard ORIG_HEADDiscards work
ORIG_HEAD is the branch tip before the rebase. Later, use git reflog show feature/profile and reset to feature/profile@{1}.

Fixed when: feature/profile's commit sits on Add README again, as before the rebase.

Commands: git rebase, git reset --hard, git reflog

My rebase stopped with a conflict and I want to give up

Discards work

When: The rebase is in progress (git status says You are currently rebasing).

git rebase --abortDiscards work
Return the branch and working tree to where they were before git rebase.

Fixed when: No rebase in progress; feature/theme is back on its own commit, unchanged.

Commands: git rebase --continue, git rebase

Files and staging

I want to throw away my changes to one file

Discards work

When: You are sure: the changes were never committed or stashed, so nothing brings them back.

git restore app.jsDiscards work
Overwrite the file with its staged (or committed) version.

Fixed when: app.js matches the last commit again.

Otherwise: Not sure? git stash keeps the change where git stash pop can bring it back.

Commands: git restore, git stash

I staged a file I didn't mean to

Safe

When: Before committing.

git restore --staged notes.txt
Take it out of the index; the file and your other staged changes are untouched.

Fixed when: notes.txt is untracked again (still on disk), and app.js is still staged.

Otherwise: Already committed it? git rm --cached notes.txt, add it to .gitignore, and commit (or amend).

Commands: git restore --staged, git reset

Remotes and pushing

I need to undo a commit I already pushed

Safe

When: The commit is on a shared branch.

git revert --no-edit HEAD
A new commit that reverses the bad one (use its id when it is not the last commit).
git push
Publish the undo. History is not rewritten, so nobody else has to do anything.

Fixed when: origin's main ends with Revert "Break the build", and app.js is back to its previous content.

Commands: git revert, git push

git push was rejected: "Updates were rejected because the remote contains work that you do not have"

Rewrites local history

When: Someone pushed to the branch since you last pulled.

git pull --rebaseRewrites local history
Fetch their commit and replay yours on top of it (your unpushed commit gets a new id).
git push
Now it is a fast-forward.

Fixed when: origin's main is Move API to /v2 followed by your Add cache flag — nobody's commit lost.

Otherwise: Never answer this rejection with git push --force: that removes the teammate's commit from the remote.

Commands: git pull --rebase, git push, git push --force-with-lease

git pull says "Need to specify how to reconcile divergent branches"

Rewrites local history

When: You and the remote both have new commits on the branch.

git config pull.rebase true
Choose rebase for this repository (add --global for all). Choose pull.rebase false for merge commits, or pull.ff only to refuse.
git pull
Now pull knows what to do: replay your commit on the remote's.

Fixed when: main is the teammate's commit followed by yours, with no merge commit.

Commands: git pull, git pull --rebase, git config

git pull made a merge commit I didn't want

Rewrites local history

When: The merge is not pushed.

git reset --hard ORIG_HEADDiscards work
Undo the merge the pull just made (the tree is clean, so nothing is discarded).
git pull --rebaseRewrites local history
Integrate again by replaying your commit on top instead.

Fixed when: main has no merge commit: the teammate's commit, then yours.

Commands: git pull --rebase, git reset --hard

Someone force-pushed the branch I'm working on

Rewrites local history

When: You have local commits on top of the old version of the branch.

git pull --rebaseRewrites local history
git finds where your work forked from the old branch (from the remote-tracking reflog) and replays only your commits onto the new one.

Fixed when: feature/api is the rewritten Add API (reviewed) followed by your Add API docs; the old Add API commit is gone from the branch.

Otherwise: No local commits on the branch? git reset --hard origin/feature/api simply takes the new version.

Commands: git pull --rebase, git rebase, git push --force-with-lease

Secrets

I committed a secret (.env, a key) and haven't pushed

Rewrites local history

When: The commit is only local.

git rm --cached .env
Stop tracking the file; it stays on disk.
echo .env >> .gitignore
Keep it from being added again.
git add .gitignore
Stage the ignore rule.
git commit --amend --no-editRewrites local history
Rewrite the commit without the secret.

Fixed when: No commit on any branch contains .env; the file is still on disk and now ignored.

Otherwise: The old commit stays in your local reflog until it expires. It was never pushed, so nobody else has it; if the secret was ever pushed, use the next recipe.

Commands: git rm, git commit --amend, git check-ignore

I pushed a secret

Rewrites shared history

When: The commit reached a remote. Treat the secret as public.

git rm --cached .env
First, outside git: revoke and rotate the secret with its provider. Then stop tracking the file.
echo .env >> .gitignore
Ignore it from now on.
git add .gitignore
Stage the rule.
git commit -m "Stop tracking .env"
This removes .env from the latest commit only.
git push
The earlier commit — and the secret — is still in origin's history. Removing it needs git filter-repo and a force push (below).

Fixed when: The latest commit no longer has .env, but origin's history still contains it — the reason rotating the secret comes first.

Otherwise: To purge history (outside this page's engine): in a fresh clone run git filter-repo --invert-paths --path .env, then git push --force --all and --tags; ask everyone to re-clone; ask the host to purge cached views and pull request refs (GitHub's guide: Removing sensitive data from a repository). Secret scanning with push protection stops the next one.

Commands: git filter-repo, git rm, git log -S

Reference

Git Model

What a repository is made of — objects, ids, refs and HEAD, the three trees, and what the reflog keeps — on one screen, with an inspector that computes real object ids as you type.

A repository is a store of four kinds of object — blobs (file contents), trees (directories), commits and annotated tags — each named by a hash of its content.
A commit records a whole snapshot (one tree), its parent commits, who made it and when. Diffs are computed when you ask for them.
A branch is a file holding one commit id. Committing moves it. HEAD names the branch you are on (or, detached, a commit).
Your changes move between three places: the working tree, the index (staging area) and HEAD. Every add, commit, restore and reset is a copy between two of them.
Nothing that was committed is lost at once: the reflog remembers where refs pointed for 90 days, and unreachable objects are deleted only after two weeks.

Snapshots, not diffs

Each commit points at a tree describing every file in the project at that moment. Files that did not change are not stored again: the new tree refers to the same blob id as the old one, because the id depends only on the content. git diff, git show and merges compute differences between snapshots when they need them Chacon 2014.

Renames are not recorded either: git detects them by comparing contents (a file that disappears and a similar one that appears), which is why git log --follow and git diff -M can find them and why a rename with heavy edits may show as a delete and an add.

The four objects, and the inspector

Type below. The blob id is the SHA-1 of the header blob <size>\0 followed by the content, so one changed character gives a different id — and a different tree id, and a different commit id.

File nameFile contentCommit message Show a second commit, with the first as its parent

Author and committer: Ada Lovelace <ada@example.com>, time 1767225600 +0000 (2026-01-01 00:00 UTC). With the defaults, these are the ids git 2.55.0 prints for the same input.

blob82359009487218af7a33dba25d3522d1bf5755fb

# Hello, git

The file's content only — no name, no date. Two files with the same content are one blob.

tree1dd1b4e8b1e2b5771bc74d1231a7ede1460f1af7

100644 blob 82359009487218af7a33dba25d3522d1bf5755fb	README.md

A directory: each entry is a mode, a type, the id of a blob or subtree, and a name.

commit870a871ceb0fdfdc7300b2492d6a6fcf45c2b30e

tree 1dd1b4e8b1e2b5771bc74d1231a7ede1460f1af7
author Ada Lovelace <ada@example.com> 1767225600 +0000
committer Ada Lovelace <ada@example.com> 1767225600 +0000

First commit

A snapshot: the id of the top tree, the parents (none for a first commit), who and when, and the message.

The object types
Object	Holds	Points to	Made by
blob	A file's bytes (no name, no mode)	Nothing	git add, git hash-object -w
tree	One directory: mode, type, id and name per entry	Blobs and other trees	git commit (via git write-tree)
commit	Author, committer, dates, message	One tree and zero or more parent commits	git commit, merge, rebase, cherry-pick…
tag (annotated)	Tagger, date, message, optional signature	One object, usually a commit	git tag -a

Object ids

Ids are 40 hexadecimal characters of SHA-1. Git has hardened its SHA-1 against the known collision attacks, and supports SHA-256 repositories with git init --object-format=sha256; at present a SHA-256 repository cannot exchange objects with a SHA-1 one git-init. The Git project plans to make SHA-256 the default for new repositories in Git 3.0, along with the reftable ref format and main as the initial branch name Git: breaking changes.

A short id such as 1dd1b4e is any unambiguous prefix; git prints 7 characters or more as the repository grows.

Refs and HEAD

Refs
Ref	Example	What it is	Moves when
Branch	refs/heads/main	A name for one commit	You commit, merge, reset or rebase on it
HEAD	ref: refs/heads/main	Which branch you are on — or, detached, a commit id	You switch, or check out a commit
Remote-tracking branch	refs/remotes/origin/main	Where main was on origin when you last fetched	git fetch, pull or push
Tag	refs/tags/v1.0.0	A fixed name for a release	Only if forced (-f)
Stash	refs/stash	The newest stash entry; older ones are its reflog	git stash push, pop, drop
ORIG_HEAD	ORIG_HEAD	HEAD before the last reset, merge or rebase	Those commands

Refs live as files under .git/refs/, packed into .git/packed-refs, or in the newer reftable format (git init --ref-format=reftable, Git 2.45+) gitrepository-layout Git 2.45.

The three trees

Every file has up to three versions: in HEAD (the last commit), in the index (what the next commit will contain) and in the working tree (on disk). Commands copy between them.

Which command moves content where
Command	From	To	HEAD moves?
git add <path>	working tree	index	No
git commit	index	a new commit	Yes: the branch moves to it
git restore <path>	index	working tree	No
git restore --staged <path>	HEAD	index	No
git restore --source=<c> -SW <path>	commit <c>	index and working tree	No
git reset --soft <c>	—	—	Yes, to <c>; index and files unchanged
git reset [--mixed] <c>	commit <c>	index	Yes, to <c>
git reset --hard <c>	commit <c>	index and working tree	Yes, to <c>
git switch <branch>	<branch>'s commit	index and working tree (local changes carried)	Yes: HEAD names <branch>
git stash	index and working tree	a stash commit; both reset to HEAD	No

Stage 4 has the three-trees tool, which shows each file's three versions as you run these commands.

Reachability, the reflog and garbage collection

A commit is reachable if a ref, or a commit reachable from one, points at it. git log, clone and push only see reachable commits. After a reset, amend or rebase, the old commits are unreachable from branches — but not gone:

The reflog records every value HEAD and each branch has had. git reflog lists them; HEAD@{2} and main@{1} name them. Entries expire after 90 days (gc.reflogExpire), or 30 days for commits no longer on the branch (gc.reflogExpireUnreachable) git-config: gc.*.
Objects no ref or reflog reaches are deleted by git gc once they are older than gc.pruneExpire, two weeks by default. git fsck --lost-found finds them before that.
Reflogs are local. They are not pushed, fetched or cloned — your teammate's reflog cannot rescue your commit.

Uncommitted changes are the exception: a working-tree edit that was never staged or stashed is in no object, and reset --hard, restore or checkout -- <path> destroy it for good. The terminal's dry run warns about exactly this.

Distributed, not centralised

Every clone is a complete repository: all commits, all history, its own branches. A remote such as origin is another repository your clone knows the URL of; fetch and push copy objects and move refs between the two. Centralised systems (Subversion, Perforce) keep history on a server and give each client one checkout; there, committing means sending to the server, while in git it is a local operation you publish later.

Sources

Chacon, S. & Straub, B. — Pro Git, ch. 10: Git Internals (2014)
Git project — gitrepository-layout — the .git directory (2026)
Git project — git-init documentation (2026)
Git project — Upcoming breaking changes (Git 3.0: SHA-256 and reftable by default, main as the initial branch) (2026)
Git project — git-config documentation (2026)
Git project — gitglossary — a git glossary (2026)
Git project — Git 2.45.0 release notes (2024)

Interactive Feature

Branch Strategy Comparison

Click any strategy to see the full branching rules, workflow, and commands.

GitFlow

Scheduled releases, complex branching

Branches5+ branch types

PR FrequencyLow — batched

Release CadenceScheduled (sprint / monthly)

Best forEnterprise software, packaged apps

solosmallmediumlargeenterprise

GitHub Flow

Simple, CI/CD-first, one rule

Branches2 branch types

PR FrequencyHigh — every feature

Release CadenceContinuous (every merge to main)

Best forSaaS products, web apps, API services

solosmallmediumlargeenterprise

Trunk-Based

Maximum velocity, feature flags, minimal branching

Branches1 branch (+ short-lived)

PR FrequencyContinuous (daily commits to trunk)

Release CadenceContinuous / on-demand

Best forHigh-velocity teams, mature CI, Google/Meta scale

solosmallmediumlargeenterprise

Interactive Feature

Follow the Code

One feature. Eight milestones. From idea to production — every command, every artifact.

◉

Issue Created

Planning

1 / 8

A bug or feature is captured in the backlog with acceptance criteria and priority.

Key Commands

$ gh issue create --title 'Add Apple Pay to checkout'

$ gh issue view 847

Artifacts

◆JIRA ticket

◆Acceptance criteria

◆Priority label

Reference

Lab

A live repository, full width. Pick a starting repository, type git commands, and watch the graph change. Undo and redo move between states; the session exports as a shell script you can run against real git, and a link replays it.

In progress

Match the issue type to the work#

Meet the Definition of Ready before starting#

Write acceptance criteria as Given/When/Then#

Name the branch after the issue, and link the PR to it#

Open a draft PR on day one for anything that will take more than a day#

Priority, separately from size#

Sources

Start the repository#

README, LICENSE, CONTRIBUTING#

Ignore build output, dependencies and secrets before the first commit#

Fix line endings and diff behaviour with .gitattributes#

Generate both files from what the project actually uses#

Monorepo vs. polyrepo#

Options for a large repository#

Sources

Four strategies, compared#

Match the strategy to release cadence and CI maturity, not preference#

Name branches so the type is obvious without opening them#

Sources

The three trees, live#

Stage what belongs in this commit, not everything you touched#

One logical change per commit#

Write commit messages a machine and a person can both use#

Fix the last commit or the working tree with the smallest tool that does it#

Set work aside without committing it#

Read history with the flag that answers the actual question#

Read a diff#

Hooks: local checks that run automatically#

Work on two branches at once without stashing#

Sources

Remotes, fetch and the state that changes#

Decide merge pull or rebase pull once, in config, not commit by commit#

Force only what you are sure is disposable, and check before you overwrite it#

Choose how a branch rejoins main: merge, --no-ff, squash, or rebase#

Resolve a conflict, in whichever marker style helps#

Sources

Merge & Pull Request Process

PR Lifecycle

PR Template Anatomy

CODEOWNERS Auto-Assignment

Review States

Merge Strategies

PR Size Guide

Code Review Process

Reviewer Checklist — 8 Dimensions

Comment Types

Review SLA

Review Etiquette

CI/CD Pipeline

Environment Promotion Flow

Environment Ladder

Release Management

Semantic Version Calculator

Git Tag Anatomy

Release Candidates

Changelog from Conventional Commits

Hotfix Process

Release Train Calendar (2-week sprints)

Post-Deployment

Monitoring Stack

Incident Response Flow

Documentation & Knowledge

Documentation Types

Diagram-as-Code (Mermaid)

Governance & Compliance

Audit Trail

Compliance Evidence Collection

Access Control Matrix

License Compliance

CI Security Scanning

Team Communication & Notifications

Integration Map

Notification Preferences Matrix

Setup & config

Staging & committing

Branches & merging

History & inspection

Remotes & sharing

Undo & recovery

Tags & releases

Match the issue type to the work

Meet the Definition of Ready before starting

Write acceptance criteria as Given/When/Then

Name the branch after the issue, and link the PR to it

Open a draft PR on day one for anything that will take more than a day

Priority, separately from size

Start the repository

README, LICENSE, CONTRIBUTING

Ignore build output, dependencies and secrets before the first commit

Fix line endings and diff behaviour with .gitattributes

Generate both files from what the project actually uses

Monorepo vs. polyrepo

Options for a large repository

Four strategies, compared

Match the strategy to release cadence and CI maturity, not preference

Name branches so the type is obvious without opening them

The three trees, live

Stage what belongs in this commit, not everything you touched

One logical change per commit

Write commit messages a machine and a person can both use

Fix the last commit or the working tree with the smallest tool that does it

Set work aside without committing it

Read history with the flag that answers the actual question

Read a diff

Hooks: local checks that run automatically

Work on two branches at once without stashing

Remotes, fetch and the state that changes

Decide merge pull or rebase pull once, in config, not commit by commit

Force only what you are sure is disposable, and check before you overwrite it

Choose how a branch rejoins main: merge, --no-ff, squash, or rebase

Resolve a conflict, in whichever marker style helps

Snapshots, not diffs

The four objects, and the inspector

Object ids

Refs and HEAD

The three trees

Reachability, the reflog and garbage collection

Distributed, not centralised