Variable: magit-branch-adjust-remote-upstream-alist

magit-branch-adjust-remote-upstream-alist is a customizable variable defined in magit-branch.el.

Value

nil

Documentation

Alist of upstreams to be used when branching from remote branches.

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 element is used whose UPSTREAM exists and whose RULE matches the name of the new branch. Subsequent 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/"))

UPSTREAM can be a local branch:

  (("master" . ("master" "next" "maint")))

Because the main branch is no longer almost always named "master" you should also account for other common names:

  (("main" . ("main" "master" "next" "maint"))
   ("master" . ("main" "master" "next" "maint")))

If you use remote branches as UPSTREAM, then you might also want to set magit-branch-prefer-remote-upstream to a non-nil value. However, I recommend that you use local branches as UPSTREAM.

This variable was added, or its default value changed, in magit version 2.9.0.

Source Code

;; Defined in ~/.emacs.d/elpa/magit-20260411.1452/magit-branch.el
(defcustom magit-branch-adjust-remote-upstream-alist nil
  "Alist of upstreams to be used when branching from remote branches.

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
element is used whose UPSTREAM exists and whose RULE matches
the name of the new branch.  Subsequent 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/\"))

UPSTREAM can be a local branch:

  ((\"master\" . (\"master\" \"next\" \"maint\")))

Because the main branch is no longer almost always named \"master\"
you should also account for other common names:

  ((\"main\"  . (\"main\" \"master\" \"next\" \"maint\"))
   (\"master\" . (\"main\" \"master\" \"next\" \"maint\")))

If you use remote branches as UPSTREAM, then you might also want
to set `magit-branch-prefer-remote-upstream' to a non-nil value.
However, I recommend that you use local branches as UPSTREAM."
  :package-version '(magit . "2.9.0")
  :group 'magit-commands
  :type '(alist :key-type (string :tag "Use upstream")
                :value-type (choice :tag "For branches" ;???
                                    (regexp :tag "Matching")
                                    (repeat :tag "Except"
                                            (string :tag "Branch")))))