The transient prefix command
magit-branch is used to create and
checkout branches, and to make changes to existing branches. It is
not used to fetch, pull, merge, rebase, or push branches, i.e. this
command deals with branches themselves, not with the commits reachable
from them. Those features are available from separate transient
This transient prefix command binds the following suffix commands and displays them in a temporary buffer until a suffix is invoked.
By default it also binds and displays the values of some branch-related Git variables and allows changing their values.
This option controls whether the transient command
be used directly change the values Git variables. This defaults to
t (to avoid changing key bindings). When set to
nil, then no
variables are displayed by that transient command, and its suffix
magit-branch-configure has to be used instead to view and
change branch related variables.
This transient prefix command binds commands that set the value of branch-related variables and displays them in a temporary buffer until the transient is exited.
With a prefix argument, this command always prompts for a branch.
Without a prefix argument this depends on whether it was invoked as
a suffix of
magit-branch and on the
magit-branch already displays the variables for the
current branch, then it isn’t useful to invoke another transient
that displays them for the same branch. In that case this command
prompts for a branch.
The variables are described in Branch Git Variables.
Checkout a revision read in the minibuffer and defaulting to the
branch or arbitrary revision at point. If the revision is a local
branch then that becomes the current branch. If it is something
HEAD becomes detached. Checkout fails if the working tree
or the staging area contain changes.
Create a new branch. The user is asked for a branch or arbitrary revision to use as the starting point of the new branch. When a branch name is provided, then that becomes the upstream branch of the new branch. The name of the new branch is also read in the minibuffer.
Also see option
This command creates a new branch like
magit-branch, but then also
checks it out.
Also see option
This command checks out an existing or new local branch. It reads a branch name from the user offering all local branches and a subset of remote branches as candidates. Remote branches for which a local branch by the same name exists are omitted from the list of candidates. The user can also enter a completely new branch name.
In the latter two cases the upstream is also set. Whether it is set
to the chosen starting point or something else depends on the value
This command creates and checks out a new branch starting at and tracking the current branch. That branch in turn is reset to the last commit it shares with its upstream. If the current branch has no upstream or no unpushed commits, then the new branch is created anyway and the previously current branch is not touched.
This is useful to create a feature branch after work has already began on the old branch (likely but not necessarily "master").
If the current branch is a member of the value of option
magit-branch-prefer-remote-upstream (which see), then the current
branch will be used as the starting point as usual, but the upstream
of the starting-point may be used as the upstream of the new branch,
instead of the starting-point itself.
If optional FROM is non-nil, then the source branch is reset
FROM~, instead of to the last commit it shares with its
upstream. Interactively, FROM is only ever non-nil, if the
region selects some commits, and among those commits, FROM is
the commit that is the fewest commits ahead of the source
The commit at the other end of the selection actually does not
matter, all commits between FROM and
HEAD are moved to the new
branch. If FROM is not reachable from
HEAD or is reachable from the
source branch’s upstream, then an error is raised.
This command behaves like
magit-branch-spinoff, except that it does
not change the current branch. If there are any uncommitted changes,
then it behaves exactly like
This command resets a branch, defaulting to the branch at point, to the tip of another branch or any other commit.
When the branch being reset is the current branch, then a hard reset is performed. If there are any uncommitted changes, then the user has to confirm the reset because those changes would be lost.
This is useful when you have started work on a feature branch but realize it’s all crap and want to start over.
When resetting to another branch and a prefix argument is used, then the target branch is set as the upstream of the branch that is being reset.
Delete one or multiple branches. If the region marks multiple branches, then offer to delete those. Otherwise, prompt for a single branch to be deleted, defaulting to the branch at point.
Rename a branch. The branch and the new name are read in the minibuffer. With prefix argument the branch is renamed even if that name conflicts with an existing branch.
When creating a branch, whether to read the upstream branch before
the name of the branch that is to be created. The default is
and I recommend you leave it at that.
This option specifies whether remote upstreams are favored over local upstreams when creating new branches.
When a new branch is created, then the branch, commit, or stash at point is suggested as the starting point of the new branch, or if there is no such revision at point the current branch. In either case the user may choose another starting point.
If the chosen starting point is a branch, then it may also be set as the upstream of the new branch, depending on the value of the Git variable ‘branch.autoSetupMerge’. By default this is done for remote branches, but not for local branches.
You might prefer to always use some remote branch as upstream. If the chosen starting point is (1) a local branch, (2) whose name matches a member of the value of this option, (3) the upstream of that local branch is a remote branch with the same name, and (4) that remote branch can be fast-forwarded to the local branch, then the chosen branch is used as starting point, but its own upstream is used as the upstream of the new branch.
Members of this option’s value are treated as branch names that
have to match exactly unless they contain a character that makes
them invalid as a branch name. Recommended characters to use
to trigger interpretation as a regexp are "*" and "^". Some
other characters which you might expect to be invalid, actually
are not, e.g. ".+$" are all perfectly valid. More precisely,
git check-ref-format --branch STRING exits with a non-zero
status, then treat STRING as a regexp.
Assuming the chosen branch matches these conditions you would end up with with e.g.:
feature --upstream--> origin/master
feature --upstream--> master --upstream--> origin/master
Which you prefer is a matter of personal preference. If you do
prefer the former, then you should add branches such as
maint to the value of this options.
The value of this option is an alist of branches to be used as the upstream when branching a remote branch.
When creating a local branch from an ephemeral branch located on a remote, e.g. a feature or hotfix branch, then that remote branch should usually not be used as the upstream branch, since the push-remote already allows accessing it and having both the upstream and the push-remote reference the same related branch would be wasteful. Instead a branch like "maint" or "master" should be used as the upstream.
This option allows specifying the branch that should be used as the
upstream when branching certain remote branches. The value is an
alist of the form
((UPSTREAM . RULE)...). The first matching
element is used, the following elements are ignored.
UPSTREAM is the branch to be used as the upstream for branches specified by RULE. It can be a local or a remote branch.
RULE can either be a regular expression, matching branches whose upstream should be the one specified by UPSTREAM. Or it can be a list of the only branches that should not use UPSTREAM; all other branches will. Matching is done after stripping the remote part of the name of the branch that is being branched from.
If you use a finite set of non-ephemeral branches across all your repositories, then you might use something like:
(("origin/master" "master" "next" "maint"))
Or if the names of all your ephemeral branches contain a slash, at least in some repositories, then a good value could be:
(("origin/master" . "/"))
Of course you can also fine-tune:
(("origin/maint" . "\\`hotfix/") ("origin/master" . "\\`feature/"))
This command creates and checks out a new orphan branch with contents from a given revision.
This command is a hybrid between
magit-branch-and-checkout and is intended as a replacement for the
It first asks the user for an existing branch or revision. If the
user input actually can be resolved as a branch or revision, then it
checks that out, just like
Otherwise it creates and checks out a new branch using the input as
its name. Before doing so it reads the starting-point for the new
branch. This is similar to what
To use this command instead of
magit-checkout add this to your init
(transient-replace-suffix 'magit-branch 'magit-checkout '("b" "dwim" magit-branch-or-checkout))