6.5.2 The Branch Popup

The popup magit-branch-popup 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 popup deals with branches themselves, not with the commits reachable from them. Those features are available from separate popups.

b     (magit-branch-popup)

This prefix command shows the following suffix commands in a popup buffer.

By default it also displays the values of some branch-related Git variables and allows changing their values, just like the specialized magit-branch-config-popup does.

User Option: magit-branch-popup-show-variables

Whether the magit-branch-popup shows Git variables. This defaults to t to avoid changing key bindings. When set to nil, no variables are displayed directly in this popup, and the sub-popup magit-branch-config-popup has to be used instead to view and change branch related variables.

b C     (magit-branch-config-popup)

This command shows branch related variables in a separate popup. By default this asks the user for which branch the variables should be shown. When magit-branch-popup-show-variables is nil, then it shows the variables for the current branch, unless a prefix argument is used.

b b     (magit-checkout)

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 else then HEAD becomes detached. Checkout fails if the working tree or the staging area contain changes.

b n     (magit-branch)

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 magit-branch-prefer-remote-upstream.

b c     (magit-branch-and-checkout)

This command creates a new branch like magit-branch, but then also checks it out.

Also see option magit-branch-prefer-remote-upstream.

b l     (magit-branch-checkout)

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.

• If the user selects an existing local branch, then that is checked out.
• If the user selects a remote branch, then it creates and checks out a new local branch with the same name, and configures the selected remote branch as the push target.
• If the user enters a new branch name, then it creates and checks that out, after also reading the starting-point from the user.

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 of magit-branch-adjust-remote-upstream-alist.

b s     (magit-branch-spinoff)

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 to 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 branch.

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.

b Y     (magit-branch-pull-request)

This command creates and configures a new branch from a Github pull-request, creating and configuring a new remote if necessary.

The name of the local branch is the same as the name of the remote branch that you are being asked to merge, unless the contributor could not be bother to properly name the branch before opening the pull-request. The most likely such case is when you are being asked to merge something like "fork/master" into "origin/master". In such cases the local branch will be named "pr-N", where N is the pull-request number.

These variables are always set by this command:

• branch.<name>.pullRequest is set to the pull-request number.
• branch.<name>.pullRequestRemote is set to the remote on which the pull-request branch is located.
• branch.<name>.pushRemote is set to the same remote as branch.<name>.pullRequestRemote if that is possible, otherwise it is set to the upstream remote.
• branch.<name>.description is set to the pull-request title.
• branch.<name>.rebase is set to true because there should be no merge commits among the commits in a pull-request.

This command also configures the upstream and the push-remote of the local branch that it creates.

The branch against which the pull-request was opened, is always used as the upstream. This makes it easy to see what commits you are being asked to merge in the section titled something like "Unmerged into origin/master".

Like for other commands that create a branch it depends on the option magit-branch-prefer-remote-upstream whether the remote branch itself or the respective local branch is used as the upstream, so this section may also be titled e.g. "Unmerged into master".

When necessary and possible, then the remote pull-request branch is configured to be used as the push-target. This makes it easy to see what further changes the contributor has made since you last reviewed their changes in the section titled something like "Unpulled from origin/new-feature" or "Unpulled from fork/new-feature".

• If the pull-request branch is located in the upstream repository, then you probably have set remote.pushDefault to that repository. However some users like to set that variable to their personal fork, even if they have push access to the upstream, so branch.<name>.pushRemote is set anyway.
• If the pull-request branch is located inside a fork, then you are usually able to push to that branch, because Github by default allows the recipient of a pull-request to push to the remote pull-request branch even if it is located in a fork. The contributor has to explicitly disable this.
  • If you are not allowed to push to the pull-request branch on the fork, then a branch by the same name located in the upstream repository is configured as the push-target.
  • A — sadly rather common — special case is when the contributor didn’t bother to use a dedicated branch for the pull-request.

    The most likely such case is when you are being asked to merge something like "fork/master" into "origin/master". The special push permission mentioned above is never granted for the branch that is the repository’s default branch, and that would almost certainly be the case in this scenario.

    To enable you to easily push somewhere anyway, the local branch is named "pr-N" (where N is the pull-request number) and the upstream repository is used as the push-remote.

  • Finally, if you are allowed to push to the pull-request branch and the contributor had the foresight to use a dedicated branch, then the fork is configured as the push-remote.

  The push-remote is configured using branch.<name>.pushRemote, even if the used value is identical to that of remote.pushDefault, just in case you change the value of the latter later on. Additionally the variable branch.<name>.pullRequestRemote is set to the remote on which the pull-request branch is located.

When you later delete the local pull-request branch, then you are offered to also delete the corresponding remote, provided it is not the upstream remote and that the tracking branch that corresponds to the deleted branch is the only remaining tracked branch. If you don’t confirm, then only the tracking branch itself is deleted in addition to the local branch.

Do not delete the tracking branch instead of the local branch. The cleanup mentioned in the previous paragraph is not performed if you do that.

b y     (magit-checkout-pull-request)

This command creates and configures a new branch from a pull request, the same way magit-branch-pull-request does. Additionally it checks out the new branch.

b x     (magit-branch-reset)

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.

b k     (magit-branch-delete)

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.

b r     (magit-branch-rename)

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.

User Option: magit-branch-read-upstream-first

When creating a branch, whether to read the upstream branch before the name of the branch that is to be created. The default is nil, and I recommend you leave it at that.

User Option: magit-branch-prefer-remote-upstream

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, if ‘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

instead of

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 master, next, and maint to the value of this options.

User Option: magit-branch-adjust-remote-upstream-alist

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/"))

Command: magit-branch-orphan

This command creates and checks out a new orphan branch with contents from a given revision.

Command: magit-branch-or-checkout

This command is a hybrid between magit-checkout and magit-branch-and-checkout and is intended as a replacement for the former in magit-branch-popup.

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 magit-checkout would.

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 magit-branch-and-checkout does.

To use this command instead of magit-checkout add this to your init file:

(magit-remove-popup-key 'magit-branch-popup :action ?b)
(magit-define-popup-action 'magit-branch-popup
  ?b "Checkout" 'magit-branch-or-checkout
  'magit-branch t)