Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Branches and Tags

git branch command

Reference for git branch: list local and remote branches, create, rename (-m), delete (-d, -D), set upstreams, filter with --merged and format the output.

git branch manages branches: it lists them, creates a new one at a given commit, renames and deletes them, and sets which remote branch each one tracks. A branch is only a movable pointer to a commit, stored as a file under refs/heads/, so creating one is nearly free.

Importantly, git branch <name> creates the branch but does not switch to it. Use git switch -c <name> to create and switch in one step.

Terminal
git branch                  # list local branches
git branch feature          # create at HEAD
git branch -d feature       # delete if merged

Try it

Bash Create, list, rename and delete

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Filter and format

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Tracking a remote branch

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
git branch [--list] [-v | -vv] [-a | -r] [--merged [<c>]] [--no-merged [<c>]]
           [--contains <c>] [--sort=<key>] [--format=<fmt>] [<pattern>...]
git branch [-f] [--track] <name> [<start-point>]
git branch (-m | -M) [<old>] <new>
git branch (-c | -C) [<old>] <new>
git branch (-d | -D) [-r] <name>...
git branch (--set-upstream-to=<upstream> | -u) [<name>]
git branch --unset-upstream [<name>]
git branch --show-current
Name Description
<name> [<start-point>] Create a branch at the start point (default HEAD); does not switch.
-m, -M Rename (move); -M overwrites an existing target.
-c, -C Copy a branch; -C overwrites.
-d, -D Delete; -d only if merged into its upstream or HEAD, -D forces.
-a, -r List all branches or only remote-tracking ones.
-v, -vv Show the tip commit; -vv also upstream and ahead/behind counts.
--merged, --no-merged Filter by whether the tip is reachable from a commit (default HEAD).
--contains <c> Only branches that include the commit.
-u, --set-upstream-to Set the tracking branch.
--show-current Print the current branch name (empty when detached).
--format, --sort Control output using for-each-ref fields.

Returns: a listing, or no output when creating, renaming or setting upstream; delete prints Deleted branch <name> (was <hash>).

Errors: an unmerged -d fails with "the branch is not fully merged"; deleting the checked-out branch fails ("Cannot delete branch ... checked out at ..."); creating an existing name fails with "a branch named ... already exists".

Usage notes

  • Creating does not switch. This is the most common beginner surprise.
  • Branch names must satisfy git check-ref-format: no spaces, .., ~, ^, : or trailing .lock; slashes make namespaces (feature/login).
  • Deleting a branch deletes only the pointer. The commits stay until garbage collection; recover with git branch <name> <hash> using the hash printed on delete or found in the reflog.
  • -d checks against the upstream when one is configured, otherwise HEAD.
  • Remote branches are deleted on the server with git push origin --delete <name>; git branch -dr origin/x only removes your local tracking ref.
  • Renaming the current branch (git branch -m new) works without naming the old one. Renaming master to main also needs the remote and default branch updated.
  • git branch with a pattern (git branch --list 'feature/*') filters by glob.
  • Detached HEAD shows as (HEAD detached at <hash>) at the top of the list.