430 lines
16 KiB
Plaintext
430 lines
16 KiB
Plaintext
git-branch(1)
|
|
=============
|
|
|
|
NAME
|
|
----
|
|
git-branch - List, create, or delete branches
|
|
|
|
SYNOPSIS
|
|
--------
|
|
[synopsis]
|
|
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>]]
|
|
[--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>]
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
|
|
If `--list` is given, or if there are no non-option arguments, existing
|
|
branches are listed; the current branch will be highlighted in green and
|
|
marked with an asterisk. Any branches checked out in linked worktrees will
|
|
be highlighted in cyan and marked with a plus sign. Option `-r` causes the
|
|
remote-tracking branches to be listed,
|
|
and option `-a` shows both local and remote branches.
|
|
|
|
If a `<pattern>`
|
|
is given, it is used as a shell wildcard to restrict the output to
|
|
matching branches. If multiple patterns are given, a branch is shown if
|
|
it matches any of the patterns.
|
|
|
|
Note that when providing a
|
|
`<pattern>`, you must use `--list`; otherwise the command may be interpreted
|
|
as branch creation.
|
|
|
|
With `--contains`, 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. With `--merged`, only branches
|
|
merged into the named commit (i.e. the branches whose tip commits are
|
|
reachable from the named commit) will be listed. With `--no-merged` only
|
|
branches not merged into the named commit will be listed. If the _<commit>_
|
|
argument is missing it defaults to `HEAD` (i.e. the tip of the current
|
|
branch).
|
|
|
|
The command's second form creates a new branch head named _<branch-name>_
|
|
which points to the current `HEAD`, or _<start-point>_ if given. 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>_ 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`.
|
|
|
|
Note that this will create the new branch, but it will not switch the
|
|
working tree to it; use `git switch <new-branch>` to switch to the
|
|
new branch.
|
|
|
|
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`.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
With a `-d` or `-D` option, _<branch-name>_ will be deleted. You may
|
|
specify more than one branch for deletion. If the branch currently
|
|
has a reflog then the reflog will also be deleted.
|
|
|
|
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 linkgit:git-remote[1] for a
|
|
way to clean up all obsolete remote-tracking branches.
|
|
|
|
|
|
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`.
|
|
|
|
`-D`::
|
|
Shortcut for `--delete --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}`.
|
|
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`.
|
|
|
|
`-f`::
|
|
`--force`::
|
|
Reset _<branch-name>_ to _<start-point>_, even if _<branch-name>_ 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, the same applies for `-c` (or `--copy`).
|
|
+
|
|
Note that `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.
|
|
|
|
`-m`::
|
|
`--move`::
|
|
Move/rename a branch, together with its config and reflog.
|
|
|
|
`-M`::
|
|
Shortcut for `--move --force`.
|
|
|
|
`-c`::
|
|
`--copy`::
|
|
Copy a branch, together with its config and reflog.
|
|
|
|
`-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`.
|
|
|
|
`--no-color`::
|
|
Turn off branch colors, even when the configuration file gives the
|
|
default to color output.
|
|
Same as `--color=never`.
|
|
|
|
`-i`::
|
|
`--ignore-case`::
|
|
Sorting and filtering branches are case insensitive.
|
|
|
|
`--omit-empty`::
|
|
Do not print a newline after formatted refs where the format expands
|
|
to the empty string.
|
|
|
|
`--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.
|
|
+
|
|
This option is only applicable in non-verbose mode.
|
|
|
|
`--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 linkgit: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 linkgit:git-config[1].
|
|
|
|
`-r`::
|
|
`--remotes`::
|
|
List or delete (if used with `-d`) the remote-tracking branches.
|
|
Combine with `--list` to match the optional pattern(s).
|
|
|
|
`-a`::
|
|
`--all`::
|
|
List both remote-tracking branches and local branches.
|
|
Combine with `--list` to match optional pattern(s).
|
|
|
|
`-l`::
|
|
`--list`::
|
|
List branches. With optional `<pattern>...`, e.g. `git
|
|
branch --list 'maint-*'`, list only the branches that match
|
|
the pattern(s).
|
|
|
|
`--show-current`::
|
|
Print the name of the current branch. In detached `HEAD` state,
|
|
nothing is printed.
|
|
|
|
`-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).
|
|
|
|
`-q`::
|
|
`--quiet`::
|
|
Be more quiet when creating or deleting a branch, suppressing
|
|
non-error messages.
|
|
|
|
`--abbrev=<n>`::
|
|
In the verbose listing that show 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.
|
|
|
|
`--no-abbrev`::
|
|
Display the full sha1s in the output listing rather than abbreviating them.
|
|
|
|
`-t`::
|
|
`--track[=(direct|inherit)]`::
|
|
When creating a new branch, set up `branch.<name>.remote` and
|
|
`branch.<name>.merge` configuration entries to set "upstream" tracking
|
|
configuration for the new branch. This
|
|
configuration will tell git to show the relationship between the
|
|
two branches in `git status` and `git branch -v`. Furthermore,
|
|
it directs `git pull` without arguments to pull from the
|
|
upstream when the new branch is checked out.
|
|
+
|
|
The exact upstream branch is chosen depending on the optional argument:
|
|
`-t`, `--track`, or `--track=direct` means to use the start-point branch
|
|
itself as the upstream; `--track=inherit` means to copy the upstream
|
|
configuration of the start-point branch.
|
|
+
|
|
The `branch.autoSetupMerge` configuration variable specifies how `git switch`,
|
|
`git checkout` and `git branch` should behave when neither `--track` nor
|
|
`--no-track` are specified:
|
|
+
|
|
The default option, `true`, 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 linkgit:git-pull[1] and linkgit:git-config[1] for additional discussion on
|
|
how the `branch.<name>.remote` and `branch.<name>.merge` options are used.
|
|
|
|
`--no-track`::
|
|
Do not set up "upstream" configuration, even if the
|
|
`branch.autoSetupMerge` configuration variable is set.
|
|
|
|
`--recurse-submodules`::
|
|
THIS OPTION IS EXPERIMENTAL! Cause the current command to
|
|
recurse into submodules if `submodule.propagateBranches` is
|
|
enabled. See `submodule.propagateBranches` in
|
|
linkgit:git-config[1]. Currently, only branch creation is
|
|
supported.
|
|
+
|
|
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
|
|
e.g. `git branch --recurse-submodules topic origin/main` 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".
|
|
|
|
`--set-upstream`::
|
|
As this option had confusing syntax, it is no longer supported.
|
|
Please use `--track` or `--set-upstream-to` instead.
|
|
|
|
`-u <upstream>`::
|
|
`--set-upstream-to=<upstream>`::
|
|
Set up _<branch-name>_'s tracking information so _<upstream>_ is
|
|
considered _<branch-name>_'s upstream branch. If no _<branch-name>_
|
|
is specified, then it defaults to the current branch.
|
|
|
|
`--unset-upstream`::
|
|
Remove the upstream information for _<branch-name>_. If no branch
|
|
is specified it defaults to the current branch.
|
|
|
|
`--edit-description`::
|
|
Open an editor and edit the text to explain what the branch is
|
|
for, to be used by various other commands (e.g. `format-patch`,
|
|
`request-pull`, and `merge` (if enabled)). Multi-line explanations
|
|
may be used.
|
|
|
|
`--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`.
|
|
|
|
`--points-at <object>`::
|
|
Only list branches of _<object>_.
|
|
|
|
`--format <format>`::
|
|
A string that interpolates `%(fieldname)` from a branch ref being shown
|
|
and the object it points at. _<format>_ is the same as
|
|
that of linkgit:git-for-each-ref[1].
|
|
|
|
_<branch-name>_::
|
|
The name of the branch to create or delete.
|
|
The new branch name must pass all checks defined by
|
|
linkgit:git-check-ref-format[1]. Some of these checks
|
|
may restrict the characters allowed in a branch name.
|
|
|
|
_<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.
|
|
|
|
_<old-branch>_::
|
|
The name of an existing branch. If this option is omitted,
|
|
the name of the current branch will be used instead.
|
|
|
|
_<new-branch>_::
|
|
The new name for an existing branch. The same restrictions as for
|
|
_<branch-name>_ apply.
|
|
|
|
CONFIGURATION
|
|
-------------
|
|
`pager.branch` is only respected when listing branches, i.e., when
|
|
`--list` is used or implied. The default is to use a pager.
|
|
See linkgit:git-config[1].
|
|
|
|
include::includes/cmd-config-section-rest.adoc[]
|
|
|
|
include::config/branch.adoc[]
|
|
|
|
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".
|
|
|
|
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 linkgit:git-fetch[1].
|
|
<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 linkgit:git-for-each-ref[1]
|
|
|
|
Patterns will normally need quoting.
|
|
|
|
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.
|
|
|
|
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`.
|
|
|
|
include::ref-reachability-filters.adoc[]
|
|
|
|
SEE ALSO
|
|
--------
|
|
linkgit:git-check-ref-format[1],
|
|
linkgit:git-fetch[1],
|
|
linkgit:git-remote[1],
|
|
link:user-manual.html#what-is-a-branch["Understanding history: What is
|
|
a branch?"] in the Git User's Manual.
|
|
|
|
GIT
|
|
---
|
|
Part of the linkgit:git[1] suite
|