GIT-BRANCH(1)

📦
version 2.56.0 · 28 versions
, in arch rolling

💅 GIT-BRANCH(1) ✨

okay so this is the manual for git-branch, part of the Git Manual — like, the actual git-branch(1) page, and bestie, it's a whole journey. grab a snack 🍓

🌸 NAME 🌸

git-branch — list, create, or delete branches. that's the whole vibe. three jobs, one command, main character energy fr 👑

🎀 SYNOPSIS 🎀

like, here's every shape this command can take, and yes you need to look at all of them:

git branch [--color[=<when>] | --no-color] [--show-current]
           [-v [--abbrev=<n> | --no-abbrev]]
           [--column[=<options>] | --no-column] [--sort=<key>]
           [--merged [<commit>]] [--no-merged [<commit>]]
           [--contains [<commit>]] [--no-contains [<commit>]]
           [(--forked <branch>)...]
           [--points-at <object>] [--format=<format>]
           [(-r|--remotes) | (-a|--all)]
           [--list] [<pattern>...]
git branch [--track[=(direct|inherit)] | --no-track] [-f]
           [--recurse-submodules] <branch-name> [<start-point>]
git branch (--set-upstream-to=<upstream>|-u <upstream>) [<branch-name>]
git branch --unset-upstream [<branch-name>]
git branch (-m|-M) [<old-branch>] <new-branch>
git branch (-c|-C) [<old-branch>] <new-branch>
git branch (-d|-D) [-r] <branch-name>...
git branch --edit-description [<branch-name>]
git branch [--dry-run] (--delete-merged <pattern>)... [<branch-pattern>...]

🦋 DESCRIPTION 🦋

✨ the listing era ✨

so if you pass --list, or if you pass literally no non-option arguments at all, git just lists your existing branches. the current branch gets highlighted in green and marked with an asterisk ⭐. any branches that are checked out in linked worktrees get highlighted in cyan and marked with a plus sign ➕. option -r makes it list the remote-tracking branches instead, and option -a shows both local and remote branches. both, bestie. the whole collection 🫶

if you give it a <pattern>, that thing is used as a shell wildcard to restrict the output to matching branches. give it multiple patterns and a branch shows up if it matches any of them. very "if you're in the group chat you're in" of it.

⚠️ ok important: when you provide a <pattern>, you must use --list. otherwise the command might get interpreted as branch creation. not the read, the create. so slay, but be careful 💀

✨ the filtering era ✨

with --contains, it shows only the branches that contain the named commit — in other words, the branches whose tip commits are descendants of the named commit. --no-contains inverts it (the way that it just flips the whole thing 🙈). with --merged, only branches merged into the named commit get listed, i.e. the branches whose tip commits are reachable from the named commit. with --no-merged, only branches not merged into the named commit get listed. if the <commit> argument is missing it defaults to HEAD — that's the tip of the current branch, iykyk. with --forked, only branches whose configured upstream matches the given branch or pattern get listed. like a vibe check but for upstreams 💅

✨ the creating era ✨

the command's second form creates a new branch head named <branch-name> which points to the current HEAD, or <start-point> if you gave one. as a special case, for <start-point>, you may use <rev-A>...<rev-B> as a shortcut for the merge base of <rev-A> and <rev-B> — but only if there is exactly one merge base. you can leave out at most one of <rev-A> and <rev-B>, in which case it defaults to HEAD. iconic little shortcut tbh 🎀

🚨 note that this creates the new branch but it will not switch the working tree to it. use git switch <new-branch> to switch to the new branch. git is not going to teleport you, bestie, you have to ask.

✨ the upstream era ✨

when a local branch is started off a remote-tracking branch, Git sets up the branch — specifically the branch.<name>.remote and branch.<name>.merge configuration entries — so that git pull will appropriately merge from the remote-tracking branch. this behavior may be changed via the global branch.autoSetupMerge configuration flag. that setting can be overridden by using the --track and --no-track options, and changed later using git branch --set-upstream-to. so many ways to change your mind, we love options 🌈

✨ the renaming era ✨

with a -m or -M option, <old-branch> will be renamed to <new-branch>. if <old-branch> had a corresponding reflog, it is renamed to match <new-branch>, and a reflog entry is created to remember the branch renaming. if <new-branch> exists, -M must be used to force the rename to happen. no -M, no force, no rename. periodt 💅

✨ the copying era ✨

the -c and -C options have the exact same semantics as -m and -M, except instead of the branch being renamed, it will be copied to a new name, along with its config and reflog. it's giving "duplicate but make it legal" 🦋

✨ the deleting era ✨

with a -d or -D option, <branch-name> will be deleted. you may specify more than one branch for deletion — go off, clear the whole shelf 🧹. if the branch currently has a reflog then the reflog will also be deleted. gone means gone, no crumbs.

use -r together with -d to delete remote-tracking branches. note that it only makes sense to delete remote-tracking branches if they no longer exist in the remote repository or if git fetch was configured not to fetch them again. see also the prune subcommand of git-remote(1) for a way to clean up all obsolete remote-tracking branches. that's the "delete the ones that are already dead" angle, and git-remote(1) has the receipts 🔥

💜 OPTIONS 💜

  • -d, --delete — delete a branch. the branch must be fully merged in its upstream branch, or in HEAD if no upstream was set with --track or --set-upstream-to. git is being protective of your work, respectfully.
  • -D — shortcut for --delete --force. that's it. that's the whole flag. brute force 💀
  • --create-reflog — create the branch's reflog. this activates recording of all changes made to the branch ref, enabling use of date based sha1 expressions such as <branch-name>@{yesterday}. so you can time travel, bestie 🕰️. note that in non-bare repositories, reflogs are usually enabled by default by the core.logAllRefUpdates config option. the negated form --no-create-reflog only overrides an earlier --create-reflog, but currently does not negate the setting of core.logAllRefUpdates. it's a little one-way, ngl 🙈
  • -f, --force — reset <branch-name> to <start-point>, even if <branch-name> already exists already. without -f, git branch refuses to change an existing branch. in combination with -d (or --delete), allow deleting the branch irrespective of its merged status, or whether it even points to a valid commit. in combination with -m (or --move), allow renaming the branch even if the new branch name already exists, and the same applies for -c (or --copy). it's the "yes I know what I'm doing" button ✨
🚨 and this caveat is real: git branch -f <branch-name> [<start-point>], even with -f, refuses to change an existing branch <branch-name> that is checked out in another worktree linked to the same repository. no cap, it will simply not do it.
  • -m, --move — move/rename a branch, together with its config and reflog. the glow-up comes with accessories 🎀
  • -M — shortcut for --move --force.
  • -c, --copy — copy a branch, together with its config and reflog. twin where? 🫶
  • -C — shortcut for --copy --force.
  • --color[=<when>] — color branches to highlight current, local, and remote-tracking branches. the value must be always (the default), never, or auto. the lights are on 🌈
  • --no-color — turn off branch colors, even when the configuration file gives the default to color output. same as --color=never. boring mode, but valid 💅
  • -i, --ignore-case — sorting and filtering branches are case insensitive. Topic and topic are the same girl to this flag 👑
  • --omit-empty — do not print a newline after formatted refs where the format expands to the empty string. tiny detail, huge difference ✨
  • --column[=<options>], --no-column — display branch listing in columns. see configuration variable column.branch for option syntax. --column and --no-column without options are equivalent to always and never respectively. oh and heads up: this option is only applicable in non-verbose mode. the columns and the verbosity are not friends, lowkey.
  • --sort=<key> — sort based on <key>. prefix - to sort in descending order of the value. you may use the --sort=<key> option multiple times, in which case the last key becomes the primary key. the keys supported are the same as those in git-for-each-ref(1). sort order defaults to the value configured for the branch.sort variable if it exists, or to sorting based on the full refname (including refs/... prefix). this lists detached HEAD (if present) first, then local branches and finally remote-tracking branches. see git-config(1). it's giving perfectly organized closet 🧚
  • -r, --remotes — list or delete (if used with -d) the remote-tracking branches. combine with --list to match the optional pattern(s). remote girlies represent 🌍
  • -a, --all — list both remote-tracking branches and local branches. combine with --list to match optional pattern(s). everybody's invited to this party 🎉
  • -l, --list — list branches. with optional <pattern>..., e.g. git branch --list 'maint-*', list only the branches that match the pattern(s). the pattern is the bouncer 🚪
  • --show-current — print the name of the current branch. in detached HEAD state, nothing is printed. the void, but make it quiet 💀
  • --delete-merged <pattern> — delete local branches whose configured upstream matches <pattern>, but only when their tip is reachable from that upstream. in other words, the work on the branch has already landed on the upstream it tracks, so the local copy is no longer needed. <pattern> may name a ref, a remote (using the branch its HEAD points at), or a shell-style glob. the option can be repeated to widen the upstream match. optional <branch-pattern> arguments limit which local branches are considered, e.g. git branch --delete-merged 'origin/*' 'topic-*'. it's the cleanup crew and it has standards 🧹✨

a branch is not deleted when:

  • its configured upstream ref no longer exists,
  • it is checked out in any worktree,
  • pushing it to the remote configured by branch.<name>.remote would update its upstream, so it cannot be distinguished from a branch that just looks fully merged right after a pull; this is determined by the remote's configured push and fetch refspecs,
  • it is the local upstream of a branch that is not being deleted, or
  • branch.<name>.deleteMerged is set to false.

when such a local upstream branch has its own upstream deleted by the same operation, its upstream configuration is cleared. tidying up on the way out, we love to see it 🫶

a branch whose work has not yet been merged into its upstream is silently skipped. delete it with git branch -D if you want to remove it anyway. no warning, no drama, just ignored 🙈

  • --dry-run — with --delete-merged, print which branches would be deleted and exit without touching any ref. useful for sanity-checking a wide pattern like 'origin/*' before committing to the deletion. look before you yeet, bestie 👀🔥
  • -v, -vv, --verbose — when in list mode, show sha1 and commit subject line for each head, along with relationship to upstream branch (if any). if given twice, print the path of the linked worktree (if any) and the name of the upstream branch, as well — see also git remote show <remote>. note that the current worktree's HEAD will not have its path printed; it will always be your current directory. so you don't get your own address back, which is honestly fair 🏠
  • -q, --quiet — be more quiet when creating or deleting a branch, suppressing non-error messages. shhh, but only the non-error kind 🤫
  • --abbrev=<n> — in the verbose listing that shows the commit object name, show the shortest prefix that is at least <n> hexdigits long that uniquely refers the object. the default value is 7 and can be overridden by the core.abbrev config option. short but unique, the dream 💫
  • --no-abbrev — display the full sha1s in the output listing rather than abbreviating them. no shortcuts, full send, the entire sha1 🌸

(more parts coming, don't go anywhere bestie 💖)

  • -t, --track[=(direct|inherit)] — okay so when you're making a new branch, this sets up the branch.<name>.remote and branch.<name>.merge config entries, which is the whole "upstream" tracking situation for your new baby branch. ✨ And like, this is not just cosmetic — that config is what tells git to show you the relationship between the two branches in git status and git branch -v. AND it's what makes bare git pull (no arguments, we love a no-thoughts-just-vibes command) pull from the upstream once you check out the new branch. 💅

Which upstream actually gets picked depends on the optional argument, bestie:

  • -t, --track, or --track=direct → use the start-point branch itself as the upstream.
  • --track=inherit → copy the upstream configuration of the start-point branch.

Now, the branch.autoSetupMerge config variable is the main character here — it decides how git switch, git checkout and git branch behave when you specify neither --track nor --no-track:

  • true (the default option) — behaves as though --track=direct were given whenever the start-point is a remote-tracking branch. 🫶
  • false — behaves as if --no-track were given.
  • always — behaves as though --track=direct were given.
  • inherit — behaves as though --track=inherit were given.
  • simple — behaves as though --track=direct were given only when the <start-point> is a remote-tracking branch and the new branch has the same name as the remote branch.

See git-pull(1) and git-config(1) for additional discussion on how the branch.<name>.remote and branch.<name>.merge options are used. iykyk 📚

  • --no-track — literally do not set up "upstream" configuration. Like, at all. Even if the branch.autoSetupMerge configuration variable is set. Your branch, your rules. 🙈
  • --recurse-submodules — ⚠️ THIS OPTION IS EXPERIMENTAL! ⚠️ It causes the current command to recurse into submodules if submodule.propagateBranches is enabled. See submodule.propagateBranches in git-config(1). Currently, only branch creation is supported — so don't go expecting the world, bestie.

When used in branch creation, a new branch <branch-name> will be created in the superproject and all of the submodules in the superproject's <start-point>. In submodules, the branch will point to the submodule commit in the superproject's <start-point>, but the branch's tracking information will be set up based on the submodule's branches and remotes. Example time, because this one is giving "explain it in a group chat":

git branch --recurse-submodules topic origin/main

That will create the submodule branch "topic" that points to the submodule commit in the superproject's "origin/main", but tracks the submodule's "origin/main". Two different origin/mains, no cap. 🌀

  • --set-upstream — bestie, this option had confusing syntax so it is no longer supported. Rip to a legend but it's gone. 😭 Please use --track or --set-upstream-to instead. 💖
  • -u <upstream>, --set-upstream-to=<upstream> — sets up <branch-name>'s tracking information so <upstream> is considered <branch-name>'s upstream branch. If you don't specify a <branch-name>, then it defaults to the current branch. Slay, convenient. ✨
  • --unset-upstream — removes the upstream information for <branch-name>. If no branch is specified it defaults to the current branch. We're breaking up with the upstream, it's not me it's you. 💔
  • --edit-description — opens an editor and lets you edit the text that explains what the branch is even for. This is used by various other commands (e.g. format-patch, request-pull, and merge (if enabled)). Multi-line explanations may be used — go off, write a whole essay. 📝
  • --contains [<commit>] — only list branches which contain <commit> (HEAD if not specified). Implies --list.
  • --no-contains [<commit>] — only list branches which don't contain <commit> (HEAD if not specified). Implies --list.
  • --merged [<commit>] — only list branches whose tips are reachable from <commit> (HEAD if not specified). Implies --list.
  • --no-merged [<commit>] — only list branches whose tips are not reachable from <commit> (HEAD if not specified). Implies --list.
  • --forked <branch> — only list branches whose configured upstream matches <branch>. And the argument is flexible bestie, it can be:
    • a ref (e.g. origin/main, master)
    • a remote name like origin, for the branch its origin/HEAD points at
    • a shell-style glob (e.g. 'origin/*')

The option can be repeated to widen the filter — yes, stacking them, we love a filter that grows. Implies --list. 🔍

  • --points-at <object> — only list branches of <object>. Simple, clean, iconic.
  • --format <format> — a string that interpolates %(fieldname) from a branch ref being shown and the object it points at. The <format> is the same as that of git-for-each-ref(1) — so if you already know that one, you're seated with the cool kids. 🎀
  • <branch-name> — the name of the branch to create or delete. Heads up: the new branch name must pass all checks defined by git-check-ref-format(1), and some of those checks may restrict the characters allowed in a branch name. So like, no chaos characters, the ref cops are watching. 👮‍♀️
  • <start-point> — the new branch head will point to this commit. It may be given as a branch name, a commit-id, or a tag. If this option is omitted, the current HEAD will be used instead. Default behavior, we stan. 🌸
  • <old-branch> — the name of an existing branch. If this option is omitted, the name of the current branch will be used instead. Very "it's giving current branch energy". ⭐
  • <new-branch> — the new name for an existing branch. Same restrictions as for <branch-name> apply. No shortcuts, no exceptions. 🦋

✨ CONFIGURATION ✨

So pager.branch — bestie listen — it's only respected when you're listing branches, like when --list is used or implied. The default is to use a pager. Peep git-config(1) for the deets. 💅

Everything above this line in this section isn't included from the git-config(1) documentation. The content that follows is the same as what's found there:

🌸 branch.autoSetupMerge

Tells git branch, git switch and git checkout to set up new branches so that git-pull(1) will appropriately merge from the starting point branch. And lowkey — even if this option is not set, this behavior can be chosen per-branch using the --track and --no-track options. This option defaults to true. The valid settings are:

  • false — no automatic setup is done. literally none. zero. nada.
  • true — automatic setup is done when the starting point is a remote-tracking branch.
  • always — automatic setup is done when the starting point is either a local branch or remote-tracking branch.
  • inherit — if the starting point has a tracking configuration, it is copied to the new branch. passing down the family lore fr.
  • simple — automatic setup is done only when the starting point is a remote-tracking branch and the new branch has the same name as the remote branch. matchy matchy ✨

🦋 branch.autoSetupRebase

When a new branch is created with git branch, git switch or git checkout that tracks another branch, this variable tells Git to set up pull to rebase instead of merge (see branch.<name>.rebase). The valid settings are:

  • never — rebase is never automatically set to true.
  • local — rebase is set to true for tracked branches of other local branches.
  • remote — rebase is set to true for tracked branches of remote-tracking branches.
  • always — rebase will be set to true for all tracking branches.

See branch.autoSetupMerge for details on how to set up a branch to track another branch. This option defaults to never. 🫶

🎀 branch.sort

This variable controls the sort ordering of branches when displayed by git-branch(1). Without the --sort=<value> option provided, the value of this variable will be used as the default. See git-for-each-ref(1) field names for valid values. sorting is such a main character activity, ngl.

💖 branch.<name>.remote

When on branch <name>, it tells git fetch and git push which remote to fetch from or push to. The remote to push to may be overridden with remote.pushDefault (for all branches). The remote to push to, for the current branch, may be further overridden by branch.<name>.pushRemote. If no remote is configured, or if you are not on any branch and there is more than one remote defined in the repository, it defaults to origin for fetching and remote.pushDefault for pushing. Additionally, . (a period) is the current local repository (a dot-repository), see branch.<name>.merge's final note below. 🫡

🌈 branch.<name>.pushRemote

When on branch <name>, it overrides branch.<name>.remote for pushing. It also overrides remote.pushDefault for pushing from branch <name>. When you pull from one place (e.g. your upstream) and push to another place (e.g. your own publishing repository), you would want to set remote.pushDefault to specify the remote to push to for all branches, and use this option to override it for a specific branch. The value may be the name of a configured remote or a repository URL. one remote for pulling, one for pushing — it's giving dual citizenship 💅

⭐ branch.<name>.merge

Defines, together with branch.<name>.remote, the upstream branch for the given branch. It tells git fetch/git pull/git rebase which branch to merge and can also affect git push (see push.default). When in branch <name>, it tells git fetch the default refspec to be marked for merging in FETCH_HEAD. The value is handled like the remote part of a refspec, and must match a ref which is fetched from the remote given by branch.<name>.remote. The merge information is used by git pull (which first calls git fetch) to lookup the default branch for merging. Without this option, git pull defaults to merge the first refspec fetched. Specify multiple values to get an octopus merge. 🐙 If you wish to setup git pull so that it merges into <name> from another branch in the local repository, you can point branch.<name>.merge to the desired branch, and use the relative path setting . (a period) for branch.<name>.remote.

🧚 branch.<name>.mergeOptions

Sets default options for merging into branch <name>. The syntax and supported options are the same as those of git-merge(1), but option values containing whitespace characters are currently not supported. whitespace? not invited to the party. 🙈

🔥 branch.<name>.rebase

When true, rebase the branch <name> on top of the fetched branch, instead of merging the default branch from the default remote when git pull is run. See pull.rebase for doing this in a non branch-specific manner.

When merges (or just m), pass the --rebase-merges option to git rebase so that the local merge commits are included in the rebase (see git-rebase(1) for details).

When the value is interactive (or just i), the rebase is run in interactive mode.

NOTE: this is a possibly dangerous operation; do not use it unless you understand the implications (see git-rebase(1) for details). seriously bestie, read up first. 😭

🍓 branch.<name>.description

Branch description, can be edited with git branch --edit-description. Branch description is automatically added to the format-patch cover letter or request-pull summary. give ur branches a little bio, they deserve it ✨

💜 branch.<name>.deleteMerged

If set to false, branch <name> is exempt from git branch --delete-merged. Useful for a topic branch you intend to develop further after an initial round has been merged upstream. Defaults to true. Explicit deletion via git branch -d is unaffected. so you can shield a branch from the mass deletion and still yeet it manually if you want. queen behavior 👑

💖 EXAMPLES 💖

🌸 Start development from a known tag

$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6
$ cd my2.6
$ git branch my2.6.14 v2.6.14   (1)
$ git switch my2.6.14
  1. This step and the next one could be combined into a single step with "checkout -b my2.6.14 v2.6.14". efficiency!! ⚡

🦋 Delete an unneeded branch

$ git clone git://git.kernel.org/.../git.git my.git
$ cd my.git
$ git branch -d -r origin/todo origin/html origin/man   (1)
$ git branch -D test                                    (2)
  1. Delete the remote-tracking branches "todo", "html" and "man". The next git fetch or git pull will create them again unless you configure them not to. See git-fetch(1). they come back like a horror movie sequel 💀
  2. Delete the "test" branch even if the "master" branch (or whichever branch is currently checked out) does not have all commits from the test branch.

🎀 Listing branches from a specific remote

$ git branch -r -l '<remote>/<pattern>'                 (1)
$ git for-each-ref 'refs/remotes/<remote>/<pattern>'    (2)
  1. Using -a would conflate <remote> with any local branches you happen to have been prefixed with the same <remote> pattern.
  2. for-each-ref can take a wide range of options. See git-for-each-ref(1)

Patterns will normally need quoting. don't forget ur quotes bestie, the shell will absolutely humble you 🙈

🎀 NOTES 🎀

If you are creating a branch that you want to switch to immediately, it is easier to use the git switch command with its -c option to do the same thing with a single command. one command instead of two? we love efficiency 💅

The options --contains, --no-contains, --merged and --no-merged serve four related but different purposes:

  • --contains <commit> is used to find all branches which will need special attention if <commit> were to be rebased or amended, since those branches contain the specified <commit>.
  • --no-contains <commit> is the inverse of that, i.e. branches that don't contain the specified <commit>.
  • --merged is used to find all branches which can be safely deleted, since those branches are fully contained by HEAD.
  • --no-merged is used to find branches which are candidates for merging into HEAD, since those branches are not fully contained by HEAD.

When combining multiple --contains and --no-contains filters, only references that contain at least one of the --contains commits and contain none of the --no-contains commits are shown. ✨

When combining multiple --merged and --no-merged filters, only references that are reachable from at least one of the --merged commits and from none of the --no-merged commits are shown. 🫶

🦋 SEE ALSO 🦋

👑 GIT 👑

Part of the git(1) suite. obviously. royalty. 🌈

🧚 NOTES (the footnotes, bestie) 🧚

  1. "Understanding history: What is a branch?" — file:///usr/share/doc/git-doc/user-manual.html#what-is-a-branch ⭐

aaaand that's a wrap on GIT-BRANCH(1)! 💖 this whole masterpiece is from Git 2.56.0, dated 2026-09-27 — go forth and branch responsibly, bestie, ily 🫶✨🌸

📦 where this page comes from