Field reference · included in the free path

Git field toolbox

Essentials within reach.
Reason before commanding.

Diagnose a repository, choose a workflow and act with the right level of caution. Built for real work situations.

5 tools · one context at a time

Open the resource you need now.

Keyboard: Left/Right arrows, Home and End.

Anti-panic protocol

Stop. Inspect. Save a return point. Only then repair.

Git often preserves more exits than expected. Start with readable, reversible actions before deletion or rewriting.

Checklist · 90 seconds

Establish the facts

01
Locate yourself
Confirm repository, branch and affected files. Do not repair anything yet.
Command
```
git rev-parse --show-toplevel
git status --short --branch
```
02
Name the in-progress operation
The full status message says whether Git awaits a merge, rebase, cherry-pick or revert.
Command
```
git status
```
03
Refresh without integrating
Fetch updates your remote view without touching the working branch.
Command
```
git fetch --all --prune
git branch -vv
```
04
Draw what happened
The graph shows divergence; the reflog recovers local HEAD movements.
Command
```
git log --oneline --decorate --graph --all -20
git reflog --date=local -20
```
05
Create a return point
Before rewriting, name the current commit. A branch copies nothing: it creates a marker.
Command
```
git branch rescue/before-repair
```

Decision tree

Choose the lowest-risk exit

Starting point

What exactly does `git status` say?

The answer determines the action family. Do not mix several repairs at once.

Operation in progress

Continue or return to the start

Resolve, stage and continue. If the context is wrong, use the matching abort.

Safe path

git merge --abort
git rebase --abort
git cherry-pick --abort
git revert --abort

Uncommitted work

Shelve before moving

Preserve untracked files too, then verify that the working tree is clean.

Safe path

git stash push -u -m "rescue before diagnosis"

Missing commit

Recreate a marker from the reflog

Find the still-visible hash, inspect it, then create a recovery branch.

Safe path

git reflog
git show <hash>
git switch -c rescue/recovered-commit <hash>

Bad published commit

Add the inverse and keep history

On a shared branch, revert communicates the undo without moving teammates.

Safe path

git revert <hash>

Latest local commit

Undo without losing content

Soft reset places changes back in the index so you can rebuild the commit.

Safe path

git branch rescue/before-reset
git reset --soft HEAD~1

Unclear conflict

Compare both intentions

Open each file, remove markers, test, stage, then continue the operation named by status.

Safe path

git diff --name-only --diff-filter=U
git add <resolved-file>
git status

Operational atlas

50 recipes used in real work

Search an intention, command or symptom. Risk describes the reach of an action, not its syntax.

Search the Atlas

50 recipes found

read-onlyOnly observes the repository.
safeCommon action that is easy to undo or does not rewrite history.
localChanges local work or history: inspect first.
sharedAffects a remote repository or team work.

Start
Initialize a modern repository
safe
Command
```
git init -b main
```
Creates the .git directory and starts directly on main.
Start
Clone an existing repository
safe
Command
```
git clone <repository-url>
```
Downloads history, configures origin and creates a working tree.
Inspect
Read the essential state
read-only
Command
```
git status --short --branch
```
Shows branch, ahead/behind state, staged, modified and untracked files.
Inspect
See every branch
read-only
Command
```
git log --oneline --decorate --graph --all
```
Draws condensed history with branch and tag references.
Inspect
Inspect unstaged work
read-only
Command
```
git diff
```
Compares the working tree with the index before git add.
Inspect
Inspect the next commit
read-only
Command
```
git diff --staged
```
Shows exactly what the next commit would contain.
Inspect
Inspect a commit
read-only
Command
```
git show <hash-or-reference>
```
Shows metadata and the patch for a commit, tag or HEAD.
Inspect
Check branch tracking
read-only
Command
```
git branch --verbose --verbose
```
Lists the current branch, latest commit and tracked remote branch.
Inspect
Check remote repositories
read-only
Command
```
git remote -v
```
Shows addresses used to fetch and push commits.
Inspect
Find the repository root
read-only
Command
```
git rev-parse --show-toplevel
```
Reveals the root directory when the terminal is inside a subdirectory.
Inspect
Find the context for lines
read-only
Command
```
git blame -L 20,40 -- src/app.js
```
Links every line in the range to its latest commit so you can recover context.
This is not a tool for assigning blame: open the commit and read its discussion.
Recover
Recover a lost state
read-only
Command
```
git reflog --date=local
```
Lists local HEAD movements, including after reset or rebase.
The reflog is local and temporary. Do not treat it as durable backup.
Inspect
Find the common ancestor
read-only
Command
```
git merge-base main feature/payment
```
Returns the commit where two branches diverged.
Record
Stage one exact file
safe
Command
```
git add src/app.js
```
Prepares the current version of this file for the next commit.
Record
Build a commit by hunks
safe
Command
```
git add --patch
```
Interactively selects hunks so each commit remains coherent.
Undo
Remove from the index without losing work
safe
Command
```
git restore --staged src/app.js
```
Takes the file out of the next commit while preserving its changes.
Undo
Discard a local modification
local
Command
```
git restore src/app.js
```
Restores the file to the state recorded in the index.
Uncommitted changes in this file are deleted. Run git diff first.
Record
Create an explicit commit
safe
Command
```
git commit -m "Add cart validation"
```
Records index contents with an intent-oriented message.
Undo
Complete the latest commit
local
Command
```
git commit --amend --no-edit
```
Replaces the latest commit with currently staged content.
This changes the hash. Avoid it after publishing unless the team explicitly agrees.
Branches
Create and enter a branch
safe
Command
```
git switch -c feature/payment
```
Creates a branch at the current commit and moves HEAD to it.
Branches
Change branch
safe
Command
```
git switch main
```
Moves HEAD to the requested branch and updates the working tree.
Branches
Rename a local branch
safe
Command
```
git branch -m old-name new-name
```
Changes the local name without changing commits.
If the old name is published, coordinate the remote and teammates too.
Branches
Delete a merged branch
safe
Command
```
git branch -d feature/payment
```
Deletes the local reference only when Git considers it integrated.
Prefer -d to -D: uppercase forces deletion even when the branch is not merged.
Shelve
Shelve all current work
safe
Command
```
git stash push -u -m "WIP cart"
```
Stores tracked and untracked files, then cleans the working tree.
Shelve
List temporary snapshots
read-only
Command
```
git stash list
```
Shows available stashes and their stash@{n} references.
Shelve
Inspect a stash
read-only
Command
```
git stash show --patch stash@{0}
```
Shows the stored patch before you decide to reapply it.
Shelve
Reapply the latest stash
local
Command
```
git stash pop
```
Reapplies the stash, then removes it from the list if successful.
Conflicts are possible. Use git stash apply to preserve the original.
Synchronize
Refresh the remote view
safe
Command
```
git fetch --all --prune
```
Downloads remote references and prunes references deleted on the server.
Synchronize
Update without a surprise merge
safe
Command
```
git pull --ff-only
```
Moves the branch only when local commits have not created divergence.
Synchronize
Replay local commits after the remote
local
Command
```
git pull --rebase
```
Fetches the remote and places local commits on top.
Use for your unpublished commits and according to project convention.
Share
Publish a new branch
shared
Command
```
git push -u origin feature/payment
```
Sends the branch and configures tracking for later push and pull.
Share
Publish rewritten history with a guardrail
shared
Command
```
git push --force-with-lease origin feature/payment
```
Forces only when the remote branch has not changed since your last fetch.
Ask the team first. Never use --force by reflex on a shared branch.
Integrate
Merge while preserving the branch event
local
Command
```
git merge --no-ff feature/payment
```
Creates a merge commit even when a fast-forward is possible.
Fast-forward, squash or merge commit is a team convention.
Repair
Abort an in-progress merge
safe
Command
```
git merge --abort
```
Attempts to return to the state before the interrupted merge.
Read git status first. Pre-existing changes can complicate recovery.
Integrate
Update a branch with rebase
local
Command
```
git rebase origin/main
```
Replays current-branch commits on top of origin/main.
Hashes change. Reserve it for your commits or coordinate publication.
Repair
Continue a resolved rebase
local
Command
```
git add <resolved-files>
git rebase --continue
```
Records conflict resolution and proceeds to the next commit.
Repair
Abort a rebase
safe
Command
```
git rebase --abort
```
Returns the branch to its state before the rebase started.
Clean up
Reorganize local commits
local
Command
```
git rebase -i HEAD~4
```
Allows reordering, squashing, rewording or dropping the latest four commits.
Create a rescue branch first and never silently rewrite shared work.
Integrate
Apply one targeted commit
local
Command
```
git cherry-pick <hash>
```
Copies a commit change onto the current branch with a new hash.
It can duplicate an already integrated change. Inspect the graph first.
Repair
Undo an already shared commit
shared
Command
```
git revert <hash>
```
Creates a new commit applying the inverse without erasing history.
Release
Mark a release
safe
Command
```
git tag -a v1.4.0 -m "Release 1.4.0"
```
Creates a dated, documented annotated tag at the current commit.
Release
Publish one exact tag
shared
Command
```
git push origin v1.4.0
```
Sends only this tag to the remote repository.
A published release tag is often consumed by CI and should not move.
Work in parallel
Open a second working directory
safe
Command
```
git worktree add ../hotfix -b hotfix/login origin/main
```
Creates a branch and another working tree without cloning again.
Work in parallel
Remove a finished worktree
local
Command
```
git worktree remove ../hotfix
```
Removes the linked working tree after checking it is clean.
Git normally refuses when uncommitted changes remain. Avoid --force.
Debug
Bound a regression
safe
Command
```
git bisect start
git bisect bad
git bisect good <known-good-hash>
```
Starts a binary search between a broken state and a known healthy state.
Debug
Classify each bisect test
safe
Command
```
git bisect good
# or
git bisect bad
```
Halves the search area after each manual or automated test.
Debug
Leave the binary search
safe
Command
```
git bisect reset
```
Ends bisect and returns to the starting branch or commit.
Clean up
Preview files to clean
read-only
Command
```
git clean -nd
```
Lists untracked files and directories that would be deleted, without acting.
Clean up
Delete untracked files
local
Command
```
git clean -fd
```
Actually deletes untracked files and directories.
Git cannot recover them. Always run git clean -nd immediately before and back up anything important.
Repair
Undo the latest commit without losing content
local
Command
```
git reset --soft HEAD~1
```
Moves the branch back one commit and keeps every change staged.
This rewrites history. Reserve it for unpublished local commits.

Team architecture

The right workflow depends on release cadence

No flow is universal. Choose from delivery frequency, CI maturity, review duration and maintained versions, then write the rules in the repository.

GitHub Flow

One releasable main branch and short branches reviewed through pull requests.

When to choose it: Frequently shipped web product, small or medium team, fast rollback and reliable automation.
Branches: main plus feature/* or fix/* for hours to a few days.
Release: Every approved merge may reach production. Tags can still mark milestones.

What it optimizes

Simple to explain
Fast review feedback
History close to the shipped product

What it requires

Depends on reliable CI
Large work must be split or hidden by feature flags

Typical sequence

git switch -c feature/payment
git push -u origin feature/payment
git fetch origin && git rebase origin/main
git switch main && git pull --ff-only

Git Flow

Dedicated branches separate development, release preparation and urgent fixes.

When to choose it: Scheduled versions, multiple maintained releases, mobile/desktop app or long business validation.
Branches: main, develop, feature/*, release/* and hotfix/* with precise roles.
Release: A release branch is stabilized, merged into main and develop, then tagged.

What it optimizes

Explicit release framework
Hotfix isolated from future development
Fits long validation cycles

What it requires

More merges and rules
Too heavy for a service deployed many times a day

Typical sequence

git switch develop && git switch -c feature/payment
git switch develop && git merge --no-ff feature/payment
git switch -c release/1.4 develop
git switch main && git merge --no-ff release/1.4

Trunk-Based

Everyone integrates very small changes into an always-healthy trunk.

When to choose it: Mature CI/CD team, fast tests, feature flags and a strong need to minimize divergence.
Branches: main/trunk, optionally branches living less than one day.
Release: The trunk stays deployable. Releases are deployments or tags, not long-lived branches.

What it optimizes

Small, frequent conflicts
Minimal integration time
Compatible with continuous delivery

What it requires

Requires discipline, fast tests and flags
A broken trunk blocks the team immediately

Typical sequence

git switch main && git pull --ff-only
git switch -c task/cvv-validation
git commit -m "Add CVV validation"
git rebase origin/main && git push -u origin task/cvv-validation

Mental model

43 terms for reading Git clearly

Read reset/revert, fetch/pull and working tree/index/commit together: their differences explain most mistakes.

Alias: Configuration shortcut mapping a short name to a longer Git command.
Ancestor: Commit reachable by following the parents of another commit.
Branch: Movable name pointing to the latest commit in a line of work.
Cherry-pick: Application of one commit change onto the current branch, producing a new hash.
Clone: Local repository copy with history and usually an origin remote.
Commit: Immutable snapshot with author, date, message and one or more parents.
Conflict: Situation where Git cannot automatically combine two competing intentions.
DAG: Directed acyclic graph formed by commits and their parent relationships.
Detached HEAD: State where HEAD points directly to a commit instead of a movable branch.
Diff: Line-by-line comparison between working tree, index, commits or branches.
Fast-forward: Integration where Git only advances a branch because no parallel history diverged.
Fetch: Download of new remote references without changing the working branch.
Force push: Publication allowing a remote branch to move other than by fast-forward.
Fork: Platform-side repository copy under another account or namespace.
Git LFS: Extension replacing large files with pointers while storing content separately.
.gitignore: Pattern file telling Git which untracked files to ignore.
Hash / SHA: Computed Git object identifier; a short form works while unambiguous.
HEAD: Pointer identifying the branch or commit currently checked out.
Hook: Script triggered by a local Git event, such as before commit or after merge.
Index (staging area): Intermediate area preparing the exact contents of the next commit.
Merge: Combination of multiple histories into the current branch.
Merge commit: Commit with multiple parents recording a non-fast-forward merge.
Origin: Conventional name for the remote automatically created by clone.
Parent: Previous commit referenced by a commit; a merge commit has several.
Pull: Shortcut that fetches then integrates changes through merge or rebase.
Push: Sending commits and requested reference movements to a remote.
Rebase: Replay of commits on a new base; replayed commits receive new hashes.
Ref: Stable or movable name pointing to an object: branch, tag or remote-tracking ref.
Reflog: Local journal of recent reference movements, useful for finding a commit.
Remote: Local name associated with another repository address, often shared by a team.
Repository: Git database containing objects, references, configuration and project history.
Reset: Branch movement that can also change the index and files depending on mode.
Restore: Targeted command to restore files or remove content from the index.
Revert: New commit reversing an earlier change without erasing shared history.
Squash: Combination of several commits into one logical change.
Stash: Local stack of temporary changes shelved outside the working tree.
Submodule: Reference to an exact commit in another repository, managed as a nested dependency.
Tag: Usually immovable reference naming an important commit, often a version.
Tracking branch: Relationship between a local branch and its upstream used by pull and push.
Trunk: Main branch where changes are integrated very frequently.
Upstream: Tracked remote branch, or source repository of a fork depending on context.
Working tree: Files physically present and editable on disk.
Worktree: Additional working directory tied to the same Git repository and another branch.

Workstation + repository

A predictable setup before a fast one

Apply these settings deliberately, then let the repository and platform enforce shared rules.

Identity and initial branch

Attributable commits and a consistent branch name from repository creation.

Global configuration

git config --global user.name "First Last"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main

Inspect origin

git config --show-origin --get-regexp "user\.(name|email)|init\.defaultBranch"

Explicit pull policy

Prevent a plain pull from creating an unexpected merge. Choose a policy with the team.

Option A · linear history

git config --global pull.rebase true
git config --global rebase.autoStash true

Option B · fast-forward only

git config --global pull.rebase false
git config --global pull.ff only

Clean references and remembered conflicts

Prune deleted remote branches and reuse a conflict resolution already performed.

Recommended settings

git config --global fetch.prune true
git config --global rerere.enabled true
git config --global rerere.autoupdate true

Project-versioned hooks

Share local checks instead of relying on the unversioned .git/hooks directory.

Repository hooks directory

mkdir -p .githooks
git config core.hooksPath .githooks
chmod +x .githooks/pre-commit

Safe, readable aliases

Speed up inspection without hiding destructive operations.

Three unsurprising shortcuts

git config --global alias.st "status --short --branch"
git config --global alias.lg "log --graph --decorate --oneline --all"
git config --global alias.unstage "restore --staged --"

Minimal .gitignore, secrets excluded

Exclude dependencies, generated outputs, local files and secrets before first staging.

.gitignore

node_modules/
dist/
.env*
!.env.example
.DS_Store
*.log

Inspect the matching rule

git check-ignore -v .env.local

Commit signatures

Let the platform verify the cryptographic origin of sensitive commits and tags.

Example using an existing SSH key

git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub
git config --global commit.gpgsign true
git config --global tag.gpgsign true

Inspect a signature

git log --show-signature -1

Server protections and CI

Enforce critical rules on the platform where they apply to the entire team.

Pull request required for main.
At least one approval and resolved conversations.
Required tests, lint, build and security checks.
Up-to-date branch or merge queue before integration.
Force push and deletion of main forbidden.
Bypass rights limited and audited.

Audit before the first push

Inspect what Git will actually use.

Origin information explains why a local value can override a global setting.

Configuration audit

git config --show-origin --list
git status --short --branch
git remote -v
git branch -vv

Open the resource you need now.

Establish the facts

Locate yourself

Name the in-progress operation

Refresh without integrating

Draw what happened

Create a return point

Choose the lowest-risk exit

What exactly does git status say?

Continue or return to the start

Shelve before moving

Recreate a marker from the reflog

Add the inverse and keep history

Undo without losing content

Compare both intentions

What it optimizes

What it requires

What it optimizes

What it requires

What it optimizes

What it requires

Inspect what Git will actually use.

What exactly does `git status` say?