howtos/topics/git.md

Git

Distributed version control — track, branch, merge, and collaborate.

Config

# Identity
git config --global user.name "Your Name"
git config --global user.email "you@example.com"

# Editor
git config --global core.editor vim

# Default branch name
git config --global init.defaultBranch main

# Useful defaults
git config --global pull.rebase true
git config --global push.autoSetupRemote true
git config --global rerere.enabled true
git config --global diff.algorithm histogram
git config --global merge.conflictstyle zdiff3

# Aliases
git config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.lg "log --oneline --graph --all"

# Show current config
git config --list --show-origin

Config Scope

Flag	File	Purpose
--system	/etc/gitconfig	All users
--global	~/.gitconfig	Current user
--local	.git/config	Current repo

Local overrides global overrides system.

Init and Clone

git init
git init --bare repo.git               # server-side (no working tree)
git clone https://github.com/user/repo.git
git clone --depth 1 https://...        # shallow (latest commit only)
git clone --branch v2.0 https://...    # specific branch/tag

Daily Workflow

# Status
git status
git status -s                          # short format

# Stage
git add file.txt                       # specific file
git add src/                           # directory
git add -p                             # interactive hunk staging
git add -u                             # stage modified/deleted, not new

# Unstage
git restore --staged file.txt
git reset HEAD file.txt                # older syntax, same effect

# Discard working tree changes
git restore file.txt
git checkout -- file.txt               # older syntax

# Commit
git commit -m "feat: add login page"
git commit -am "fix: typo"            # stage tracked + commit
git commit --amend                     # rewrite last commit
git commit --amend --no-edit           # amend without changing message
git commit --allow-empty -m "trigger"  # empty commit (CI triggers)

Diff

# Working tree vs staging
git diff

# Staging vs last commit
git diff --cached
git diff --staged                      # same thing

# Between commits
git diff abc123..def456
git diff HEAD~3..HEAD

# Between branches
git diff main..feature

# Specific file
git diff -- path/to/file.txt

# Stats only
git diff --stat
git diff --name-only
git diff --name-status                 # with A/M/D markers

# Word-level diff
git diff --word-diff

Log

# Compact
git log --oneline
git log --oneline -10                  # last 10

# Graph
git log --oneline --graph --all

# Detailed
git log -p                             # with diffs
git log --stat                         # with file stats

# Filter
git log --author="alice"
git log --since="2025-01-01"
git log --after="2 weeks ago"
git log --grep="fix:"                  # search commit messages
git log -S "function_name"            # search for string in diffs (pickaxe)
git log -G "regex_pattern"            # search diffs with regex
git log -- path/to/file               # commits touching file

# Format
git log --pretty=format:"%h %an %ar %s"
git log --pretty=format:"%C(yellow)%h%Creset %s %C(dim)(%ar)%Creset"

# Show single commit
git show abc123
git show HEAD~2:path/to/file          # file at specific commit

Stash

# Save work in progress
git stash
git stash push -m "wip: api refactor"
git stash push path/to/file            # stash specific files

# List stashes
git stash list

# Restore
git stash pop                          # apply + remove from stash
git stash apply                        # apply, keep in stash
git stash apply stash@{2}             # specific stash

# Inspect
git stash show                         # stat
git stash show -p                      # full diff

# Drop
git stash drop stash@{0}
git stash clear                        # drop all

# Stash untracked files too
git stash -u
git stash --include-untracked

Remotes

# List
git remote -v

# Add
git remote add origin https://github.com/user/repo.git
git remote add upstream https://github.com/original/repo.git

# Change URL
git remote set-url origin git@github.com:user/repo.git

# Fetch
git fetch                              # default remote
git fetch --all                        # all remotes
git fetch --prune                      # remove stale remote branches

# Pull
git pull                               # fetch + merge (or rebase if configured)
git pull --rebase                      # fetch + rebase

# Push
git push
git push -u origin main               # set upstream
git push origin --delete feature-branch # delete remote branch
git push --tags                        # push all tags
git push origin v1.0                   # push specific tag

Tags

# List
git tag
git tag -l "v1.*"

# Create
git tag v1.0                           # lightweight
git tag -a v1.0 -m "Release 1.0"      # annotated (preferred)
git tag -a v1.0 abc123                 # tag specific commit

# Delete
git tag -d v1.0
git push origin --delete v1.0          # delete remote tag

# Show
git show v1.0

.gitignore

# Patterns
*.log                  # all .log files
build/                 # directory
!important.log         # exception (don't ignore this one)
**/temp                # temp in any subdirectory
doc/*.txt              # doc/notes.txt but not doc/sub/notes.txt

# Ignore already-tracked file
git rm --cached file.txt               # untrack without deleting
echo "file.txt" >> .gitignore

# Debug ignore rules
git check-ignore -v path/to/file

Gotchas

• git pull without --rebase creates merge commits — set pull.rebase true globally
• git add . stages everything including untracked — review with git status first
• --amend rewrites history — never amend commits already pushed to shared branches
• git stash does not stash untracked files unless -u is passed
• -S (pickaxe) finds where a string was added/removed, not where it appears
• git log -- file stops at renames — add --follow to track across renames
• Tags aren't pushed by default — use --tags or push individually

See Also

• git-branching — branches, merge, rebase, cherry-pick, recovery
• Pro Git book
• git help <command> — built-in manual pages