git branch

It's just a movable pointer. Treat it like one.

🎯 What & why

List, create, rename, delete, or annotate branches. Branches in Git are literally one-line files in .git/refs/heads/ (or entries in packed-refs) — each containing a 40-character SHA. That cheapness is why branching workflows became practical.

🧠 Mental model

A branch is a movable pointer to a commit. git branch reads, writes, or deletes those pointers. It does not move HEAD; that's the job of switch/checkout. Knowing this lets you reason about every branch operation as 'move/create/delete a 41-byte file.'

🛠️ Synopsis

git branch [--color[=<when>] | --no-color] [--show-current] [-v [--abbrev=<n>]]
           [--list] [<pattern>...]
git branch [--track[=(direct|inherit)] | --no-track] [-f] [--recurse-submodules]
           <branchname> [<start-point>]
git branch (-c | -C) [<oldbranch>] <newbranch>
git branch (-m | -M) [<oldbranch>] <newbranch>
git branch (-d | -D) [-r] [-f] <branchname>...

🎚️ Switches & options

Flag	What it does
`-a`	List all branches (local + remote-tracking).
`-r`	List only remote-tracking branches.
`-v, -vv`	Verbose: show tip SHA and (with `-vv`) upstream tracking info.
`-d, --delete`	Delete a fully merged branch.
`-D`	⚠️ Force-delete, even if unmerged. ⚠️ Lost commits go to reflog only.
`-m, --move`	Rename a branch.
`--track <upstream>`	Set upstream tracking on creation.
`--show-current`	Print just the current branch name.

💡 Use cases

Daily branch hygiene — listing, deleting merged ones.
Creating release branches at a specific tag.
Renaming a typo branch before pushing.

🧪 Examples

List local branches.

$ git branch

List all branches with tracking info.

$ git branch -vva

Create a branch from a tag without switching.

$ git branch hotfix/1.2 v1.2

Rename current branch.

$ git branch -m new-name

Delete a merged branch.

$ git branch -d old-feature

🎓 Recommendations

Use git switch -c <name> for create-and-switch. Use git branch <name> only when you want to create without switching.
Set up branch.autoSetupMerge = always so new branches track their start point automatically.
Prune dead remote-tracking branches: git fetch --prune (or git remote prune origin).

🪤 Common pitfalls

-d won't delete an unmerged branch. -D will, silently. Look before you leap.
Renaming a published branch is awkward: rename, delete remote, re-push, retell collaborators.
Branch names are case-sensitive in the ref store, but case-insensitive on macOS/Windows filesystems — avoid case-only differences.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.