Git Course 0%

git branch

Intermediate Git CLI Careful ≈ 6 min

Summary: git branch manages the labels that point at commits: listing them, creating one without switching, renaming, and deleting. For creating a branch and switching to it, use git switch -c.

Careful — listing and creating are harmless. -d refuses to delete unmerged work; -D deletes anyway, which abandons commits that no other branch points at.

What it does

Reads and writes the files under .git/refs/heads/, each of which contains one commit hash (lesson 6.1). Nothing about your working tree changes: git branch never switches, never edits files, and never touches commits.

Why it exists

Branch labels are how parallel work is named. This command is the label manager; switch is the one that moves you between them.

When to use it

  • Listing what exists, locally or on the remote (-a), with tracking information (-vv).
  • Creating a branch at a specific commit without leaving where you are.
  • Renaming a branch, usually because the name was wrong before the first push.
  • Deleting branches after they are merged.
  • Checking what is merged and what is not (--merged, --no-merged).

When not to use it

  • To create and switch in one step: git switch -c <name>.
  • To delete a branch on the remote: git push origin --delete <name>.
  • To remove stale origin/… entries: git fetch --prune.

Syntax

Form Meaning
git branch List local branches; * marks the current one
git branch -a Also list remote-tracking branches
git branch -vv List with each branch's newest commit and upstream
git branch -r Remote-tracking branches only
git branch <name> Create at the current commit, without switching
git branch <name> <start> Create at a commit, branch or tag
git branch -m <old> <new> Rename (-m <new> renames the current branch)
git branch -d <name> Delete, refusing if unmerged
git branch -D <name> Delete regardless
git branch --merged / --no-merged Which branches are already contained in the current one

Examples

Terminal
$ git branch
* docs/12-windows-install-steps
  main
Terminal
$ git branch -vv
* docs/12-windows-install-steps 510f1e0 [origin/docs/12-windows-install-steps] docs: add Windows steps to installation guide (#12)
  main                          8fa922e [origin/main] Initial import of trailguide
Terminal
$ git branch -a
* main
  remotes/origin/main

Safe delete, and the refusal that protects unmerged work:

Terminal
$ git branch -d docs/33-faq-windows
Deleted branch docs/33-faq-windows (was 3008743).
Terminal
$ git branch -d feature/21-difficulty-filter
error: the branch 'feature/21-difficulty-filter' is not fully merged
hint: If you are sure you want to delete it, run 'git branch -D feature/21-difficulty-filter'
hint: Disable this message with "git config set advice.forceDeleteBranch false"

Checking before deleting:

Terminal
$ git branch --no-merged
  fix/15-empty-distance

Expected result

Listing prints text and changes nothing. Creating writes one small file. Renaming and deleting change only labels; commits are untouched, and a deleted branch's commits remain reachable through git reflog for a while.

Try it here

The simulator below runs a small model of Git in the page. Nothing here touches a real repository, so try the command, then try it wrong (lesson 2.8 explains it).

The Git state simulator loads here.

Common mistakes

  • Expecting git branch <name> to switch. It creates only; use git switch -c.
  • -D by reflex after a refusal. Read it first: a squash-merged branch legitimately needs -D, an abandoned one loses work.
  • Deleting the branch you are on. Git refuses; switch to main first.
  • Renaming after pushing and leaving the old name on the remote. Delete it there too.
  • Seeing a deleted colleague's branch in -a. That is a stale bookmark; git fetch --prune.

How to undo or recover

  • A wrongly deleted branch: git reflog finds its last commit, then git branch <name> <hash> recreates it (lesson 12.5).
  • A rename: rename back with -m.
  • A created branch: delete it; nothing else changed.

In VS Code

The branch name in the status bar opens the list and creates branches; the Command Palette has Git: Create Branch…, Git: Rename Branch… and Git: Delete Branch….

In IntelliJ IDEA

The branches popup (status bar, bottom right) lists local and remote branches, with New Branch, Rename and Delete in the context menu, plus an Undo link on the notification after a delete.

git switch moves between branches · git merge brings a branch's work in · git push publishes and deletes remote branches · git log shows what a branch contains.

Lessons that use this command

What a branch really is · Create, switch, rename, delete · Remote branches and cleanup · Lab 3.

Key terms

Branch main Tracking branch (upstream)

Related