Searchable Git Command Reference

git init

Category: Basics

Initialize a new empty Git repository or reinitialize an existing one.

Example:

git init

Preconditions: None. Can be run in an empty directory or existing project folder.

Expected effect: Creates a hidden `.git` directory containing object database, refs, and default HEAD pointer to "main".

Common errors: Running git commands before git init yields "fatal: not a git repository".

Related commands: git clone, git status

git status [-s]

Category: Basics

Display state of the working directory and the staging area.

Example:

git status

Preconditions: Must be inside an initialized Git repository.

Expected effect: Shows tracked modified files, untracked files, staged files, active branch, and tracking status.

Common errors: None. Safe read-only inspection command.

Related commands: git diff, git log

git add <pathspec...>

Category: Files and Staging

Add file contents from working directory to the Staging Area (index).

Example:

git add index.js style.css
git add .

Preconditions: Target files must exist in the working directory.

Expected effect: Copies working file content snapshots into index, staging them for the next commit.

Common errors: fatal: pathspec "file" did not match any files.

Related commands: git restore --staged, git status, git commit

git restore --staged <file>

Category: Files and Staging

Remove files from the Staging Area without modifying the working directory.

Example:

git restore --staged app.py

Preconditions: File must currently be staged in the index.

Expected effect: Replaces index version with HEAD version. Working directory changes remain safely intact.

Common errors: Omitting --staged restores the working directory instead!

Safety: Ensure you include --staged if you do NOT want working directory edits discarded.

Related commands: git add, git restore

git restore <file>

Category: Files and Staging

Discard unstaged modifications in the working tree to match the index or HEAD.

Example:

git restore index.js

Preconditions: File must have tracked modifications in working directory.

Expected effect: Overwrites working tree file with the staged index version.

Common errors: fatal: pathspec did not match any file known to git.

Safety: Destructive: Unstaged edits in the working file will be permanently discarded.

Related commands: git restore --staged, git checkout -- <file>

git commit -m "<message>"

Category: Commits

Record staged changes from the index into a permanent commit in repository history.

Example:

git commit -m "feat: implement user authentication"

Preconditions: Must have at least one change staged in the index (unless using -a flag).

Expected effect: Creates a new commit object pointing to current HEAD commit, advances active branch pointer and HEAD.

Common errors: "nothing to commit, working tree clean" when forgetting to git add first.

Related commands: git add, git log, git status

git commit -am "<message>"

Category: Commits

Automatically stage all modified tracked files and commit in a single step.

Example:

git commit -am "fix: correct typo in layout"

Preconditions: Target files must already be tracked by Git (does not include untracked new files).

Expected effect: Stages modified tracked files and creates a new commit.

Common errors: Will NOT stage brand new untracked files.

Related commands: git commit, git add -u

git branch [<branchname> | -d <branchname>]

Category: Branching

List, create, or delete branches.

Example:

git branch
git branch feature/login
git branch -d feature/login

Preconditions: Repo must have at least one commit to create a branch.

Expected effect: With no arguments: lists branches with * on active branch. With name: creates branch pointer at HEAD.

Common errors: fatal: a branch named "x" already exists. Cannot delete currently checked out branch.

Related commands: git switch, git checkout

git switch [-c] <branchname>

Category: Branching

Switch branches or create and switch to a new branch.

Example:

git switch feature/login
git switch -c feature/payments

Preconditions: Target branch must exist (unless -c flag is passed).

Expected effect: Moves HEAD to target branch pointer, updates working directory to match target commit tree.

Common errors: fatal: invalid reference when branch does not exist.

Related commands: git branch, git checkout

git checkout [-b <branch>] [<commit/branch>]

Category: Branching

Switch branches, restore files, or checkout a specific commit hash (detached HEAD).

Example:

git checkout -b feature/auth
git checkout c1a2b34

Preconditions: Target commit or branch must be valid.

Expected effect: Updates HEAD and working files. Checking out a commit hash puts repo in Detached HEAD state.

Common errors: Confusing branch checkout with file checkout (`git checkout -- <file>`). Modern Git prefers `git switch` and `git restore`.

Related commands: git switch, git restore

git merge <branch>

Category: Merging and Rebasing

Join two or more development histories together.

Example:

git merge feature/auth

Preconditions: Must be on the receiving branch. Target branch must exist.

Expected effect: If linear: Fast-Forward merge (moves branch pointer). If diverged: creates a 3-way merge commit with two parents. If overlapping edits: pauses with conflict markers.

Common errors: Merge conflict requires manual resolution and git commit.

Related commands: git merge --abort, git rebase, git log --graph

git merge --abort

Category: Merging and Rebasing

Abort an unmerged conflict state and restore pre-merge state.

Example:

git merge --abort

Preconditions: A merge conflict must be actively in progress.

Expected effect: Restores working directory and index to the pre-merge HEAD commit state.

Common errors: fatal: There is no merge to abort.

Related commands: git merge

git rebase <upstream-branch>

Category: Merging and Rebasing

Reapply commits from current branch on top of another base tip.

Example:

git rebase main

Preconditions: Current branch must have commits that diverge from upstream branch.

Expected effect: Replays each commit onto target tip. Generates NEW commit hashes because parent hashes change. Yields linear history.

Common errors: Never rebase public shared commits pushed to team branches!

Safety: Caution: Rewrites commit hashes. Do not rebase branches that have already been pushed to a public shared remote.

Related commands: git merge, git cherry-pick

git reset --soft <commit>

Category: Undo and Recovery

Move HEAD and branch pointer back without touching Index or Working Directory.

Example:

git reset --soft HEAD~1

Preconditions: Target commit must exist.

Expected effect: Branch pointer moves to target commit. All changes between target and previous HEAD remain staged in the Index.

Common errors: Resetting past initial commit.

Safety: Safe: files are preserved in the staging area.

Related commands: git reset --mixed, git reset --hard, git revert

git reset [--mixed] <commit>

Category: Undo and Recovery

Move HEAD and reset Index to target commit, keeping working directory changes unstaged.

Example:

git reset HEAD~1

Preconditions: Target commit must exist.

Expected effect: Branch pointer moves to target commit, index reset. Working tree retains modifications as unstaged files.

Common errors: Forgetting that files become unstaged in working tree.

Safety: Safe: files are preserved in the working directory.

Related commands: git reset --soft, git reset --hard

git reset --hard <commit>

Category: Undo and Recovery

Reset HEAD, Index, AND Working Directory to match the target commit snapshot.

Example:

git reset --hard HEAD~1

Preconditions: Target commit must exist.

Expected effect: Moves branch pointer and forcibly discards all uncommitted working tree and staged index changes.

Common errors: Accidentally losing uncommitted work that was not stashed or committed.

Safety: Danger: Uncommitted work in the working directory will be permanently destroyed!

Related commands: git reflog, git stash

git revert <commit>

Category: Undo and Recovery

Safely undo a commit by creating a new inverse commit.

Example:

git revert HEAD

Preconditions: Target commit must exist.

Expected effect: Calculates the inverse diff of target commit and records a new commit without altering past history.

Common errors: Reverting merge commits without specifying -m parent.

Safety: Safe and recommended for public shared branches.

Related commands: git reset, git log

git reflog

Category: Undo and Recovery

Inspect reference logs showing all movements of HEAD.

Example:

git reflog

Preconditions: None.

Expected effect: Lists sequential record of every commit hash HEAD visited (commits, checkouts, merges, resets).

Common errors: Reflog is local-only; not pushed to remotes.

Related commands: git log, git reset --hard HEAD@{n}

git stash [push -m "<message>"]

Category: Stashing

Temporarily shelve dirty working directory and staged index changes.

Example:

git stash
git stash push -m "work in progress on auth"

Preconditions: Working tree must have modified or staged files.

Expected effect: Saves dirty changes onto stash stack and restores working directory to clean HEAD state.

Common errors: Untracked files are not stashed unless -u flag is used.

Related commands: git stash pop, git stash list

git stash pop

Category: Stashing

Restore the top stashed state and remove it from the stash stack.

Example:

git stash pop

Preconditions: Stash stack must contain at least one entry.

Expected effect: Applies stash@{0} modifications back to working directory and index, then deletes stash@{0}.

Common errors: error: No stash entries found.

Related commands: git stash apply, git stash drop

git fetch [<remote>]

Category: Remotes

Download objects and refs from remote repository without integrating them into local branches.

Example:

git fetch origin

Preconditions: Remote must be configured and network accessible.

Expected effect: Updates remote tracking branches like origin/main. Working directory and local branches untouched.

Common errors: fatal: origin does not appear to be a git repository.

Related commands: git pull, git remote

git pull [<remote>] [<branch>]

Category: Remotes

Fetch from remote and integrate (merge) with current local branch.

Example:

git pull origin main

Preconditions: Remote tracking branch must exist. Clean working directory recommended.

Expected effect: Executes git fetch followed by git merge origin/<branch>.

Common errors: Merge conflict during pull if remote and local diverged.

Related commands: git fetch, git merge

git push [<remote>] [<branch>]

Category: Remotes

Update remote repository with local branch commits.

Example:

git push origin main

Preconditions: Remote branch must be an ancestor of local branch (fast-forward push).

Expected effect: Uploads commits and updates remote branch pointer.

Common errors: Rejected non-fast-forward push if remote has newer commits. Fix with git pull first.

Safety: Avoid `git push --force` on shared main branches.

Related commands: git fetch, git pull

git cherry-pick <commit>

Category: Advanced workflows

Apply changes introduced by an existing commit to current HEAD as a new commit.

Example:

git cherry-pick c2d3e4f

Preconditions: Target commit must exist.

Expected effect: Extracts diff of target commit and applies it as a brand-new commit on current branch.

Common errors: Conflicts if target commit changes lines already modified on HEAD.

Related commands: git rebase, git revert

git tag [<tagname>]

Category: Advanced workflows

Create, list, or delete tags (permanent release labels on commits).

Example:

git tag v1.0.0

Preconditions: Must have at least one commit in repository.

Expected effect: Attaches permanent label to current HEAD commit.

Common errors: fatal: tag already exists.

Related commands: git show, git log