git branch

List, create without switching, rename, and safely delete branches, checked on Git 2.39.5.

git branch lists branch names, creates a new branch without moving HEAD, renames a branch, or deletes a branch name. Creating a branch this way leaves you on the current branch. To create a branch and switch to it in one step, use git switch -c, which is covered on the git switch page.

Examples were checked on Git 2.39.5 in isolated temporary repositories. They use a fixed practice identity and fixed UTC dates. git branch -D force-deletes an unmerged name; this page shows the safe -d refusal and does not run -D.

Examples were checked against Git 2.39.5. See the official documentation for the complete command.

Git command catalog → · Git tutorial overview →

List, create, and rename

With no arguments, git branch --list prints local branches and marks the current one with *. git branch --show-current prints only that name, which is useful in scripts.

git branch topic creates the name at HEAD and stays on the current branch. The example still reports main after the create. git branch -m topic feature renames a branch you are not on. --merged lists names already reachable from HEAD; --no-merged is empty in this repository because feature still points at the same commit as main.

git branch, git branch --show-current, git branch -m

git branch [--list] [<pattern>...]
git branch --show-current
git branch <branchname>
git branch -m <oldbranch> <newbranch>

List local branches, create a name without switching, and rename a branch.

ParameterDescription
<branchname>The new branch name. The new ref points at HEAD, and the current branch does not change.
--show-currentPrint only the current branch name, or print nothing in detached HEAD.
-m <old> <new>Rename a branch. Use this to rename a branch you are not currently on; git switch has its own rename form if you need to rename the branch you are on.
--merged / --no-mergedList branches that are, or are not, reachable from HEAD (or from a given commit).

Returns: A branch list on standard output, or a new or renamed ref. The working tree and index are not changed by a plain create or rename of another branch.

  • git branch -a and -r list remote-tracking names as well. This example stays with local branches.
bash
git init -b main >/dev/null
git config user.name "Practice Author"
git config user.email "[email protected]"
git config commit.gpgsign false
git config color.ui false
mkdir -p .disabled-hooks
git config core.hooksPath ".disabled-hooks"
printf 'base\n' > README.md
git add README.md
git commit -m "Add README" >/dev/null
echo "show-current"
git branch --show-current
git branch topic
echo "after-create current=$(git branch --show-current)"
echo "list"
git branch --list
git branch -m topic feature
echo "after-rename"
git branch --list
echo "merged"
git branch --merged
echo "no-merged"
nm=$(git branch --no-merged)
if [ -z "$nm" ]; then echo "(empty-list)"; else printf '%s\n' "$nm"; fi

Expected output

show-current
main
after-create current=main
list
* main
  topic
after-rename
  feature
* main
merged
  feature
* main
no-merged
(empty-list)

Related: git switch, git merge

Official documentation →

Safe delete versus an unmerged branch

git branch -d <name> deletes a branch only when it is fully merged into its upstream, or into HEAD when no upstream is set. In the example, merged-topic still points at the same commit as main, so -d succeeds and prints the short SHA that the name last pointed at.

unmerged has a commit that main does not contain, so -d exits 1 and leaves the name in place. Git itself suggests git branch -D. That force delete drops the branch name even if the tip is not merged, which can make the commit harder to find. This page does not run -D, and it is not a casual shortcut.

git branch -d, git branch --no-merged

git branch -d <branchname>
git branch --no-merged

Delete a fully merged branch name, and refuse when the tip is not merged.

ParameterDescription
-d / --deleteDelete the branch if it is fully merged. This is the safe form.
-DEquivalent to --delete --force. Not run in the example. It removes the name regardless of merge status.

Returns: On success, the branch ref is removed and Git prints the short SHA it last pointed at.

Exit status

  • 0 — A fully merged branch was deleted. Measured for merged-topic on Git 2.39.5.
  • 1 — The branch is not fully merged. Git prints an error on standard error, and the name remains. Measured for unmerged on Git 2.39.5.
  • The error text, including the -D suggestion, comes from Git. Read it as a warning, not as a recommended next command.
bash
git init -b main >/dev/null
git config user.name "Practice Author"
git config user.email "[email protected]"
git config commit.gpgsign false
git config color.ui false
mkdir -p .disabled-hooks
git config core.hooksPath ".disabled-hooks"
printf 'base\n' > README.md
git add README.md
git commit -m "Add README" >/dev/null
git branch merged-topic
git switch -c unmerged >/dev/null 2>&1
printf 'extra\n' > extra.txt
git add extra.txt
GIT_AUTHOR_DATE='2024-01-15T13:00:00+0000' GIT_COMMITTER_DATE='2024-01-15T13:00:00+0000' git commit -m "Add extra" >/dev/null
git switch main >/dev/null 2>&1
echo "before"
git branch --list
echo "no-merged"
git branch --no-merged
echo "delete-merged"
git branch -d merged-topic
echo "del-merged-exit=$?"
echo "delete-unmerged"
git branch -d unmerged 2>&1
echo "del-unmerged-exit=$?"
echo "after"
git branch --list

Expected output

before
* main
  merged-topic
  unmerged
no-merged
  unmerged
delete-merged
Deleted branch merged-topic (was c38acd9).
del-merged-exit=0
delete-unmerged
error: The branch 'unmerged' is not fully merged.
If you are sure you want to delete it, run 'git branch -D unmerged'.
del-unmerged-exit=1
after
* main
  unmerged

Official documentation →