Skip to main content

5.6 References Buffer

y     (magit-show-refs)​

This command lists branches and tags in a dedicated buffer.

However if this command is invoked again from this buffer or if it is invoked with a prefix argument, then it acts as a transient prefix command, which binds the following suffix commands and some infix arguments.

All of the following suffix commands list exactly the same branches and tags. The only difference the optional feature that can be enabled by changing the value of magit-refs-show-commit-count (see below). These commands specify a different branch or commit against which all the other references are compared.

y y     (magit-show-refs-head)​

This command lists branches and tags in a dedicated buffer. Each reference is being compared with HEAD.

y c     (magit-show-refs-current)​

This command lists branches and tags in a dedicated buffer. Each reference is being compared with the current branch or HEAD if it is detached.

y o     (magit-show-refs-other)​

This command lists branches and tags in a dedicated buffer. Each reference is being compared with a branch read from the user.

y r     (magit-refs-set-show-commit-count)​

This command changes for which refs the commit count is shown.

user option magit-refs-show-commit-count​

Whether to show commit counts in Magit-Refs mode buffers.

  • all Show counts for branches and tags.
  • branch Show counts for branches only.
  • nil Never show counts.

The default is nil because anything else can be very expensive.

user option magit-refs-pad-commit-counts​

Whether to pad all commit counts on all sides in Magit-Refs mode buffers.

If this is nil, then some commit counts are displayed right next to one of the branches that appear next to the count, without any space in between. This might look bad if the branch name faces look too similar to magit-dimmed.

If this is non-nil, then spaces are placed on both sides of all commit counts.

user option magit-refs-show-remote-prefix​

Whether to show the remote prefix in lists of remote branches.

Showing the prefix is redundant because the name of the remote is already shown in the heading preceding the list of its branches.

user option magit-refs-primary-column-width​

Width of the primary column in ‘magit-refs-mode’ buffers. The primary column is the column that contains the name of the branch that the current row is about.

If this is an integer, then the column is that many columns wide. Otherwise it has to be a cons-cell of two integers. The first specifies the minimal width, the second the maximal width. In that case the actual width is determined using the length of the names of the shown local branches. (Remote branches and tags are not taken into account when calculating to optimal width.)

user option magit-refs-focus-column-width​

Width of the focus column in ‘magit-refs-mode’ buffers.

The focus column is the first column, which marks one branch (usually the current branch) as the focused branch using * or @. For each other reference, this column optionally shows how many commits it is ahead of the focused branch and <, or if it isn’t ahead then the commits it is behind and >, or if it isn’t behind either, then a =.

This column may also display only * or @ for the focused branch, in which case this option is ignored. Use L v to change the verbosity of this column.

user option magit-refs-margin​

This option specifies whether the margin is initially shown in Magit-Refs mode buffers and how it is formatted.

The value has the form (INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH).

  • If INIT is non-nil, then the margin is shown initially.
  • STYLE controls how to format the author or committer date. It can be one of age (to show the age of the commit), age-abbreviated (to abbreviate the time unit to a character), or a string (suitable for format-time-string) to show the actual date. Option magit-log-margin-show-committer-date controls which date is being displayed.
  • WIDTH controls the width of the margin. This exists for forward compatibility and currently the value should not be changed.
  • AUTHOR controls whether the name of the author is also shown by default.
  • AUTHOR-WIDTH has to be an integer. When the name of the author is shown, then this specifies how much space is used to do so.

user option magit-refs-margin-for-tags​

This option specifies whether to show information about tags in the margin. This is disabled by default because it is slow if there are many tags.

The following variables control how individual refs are displayed. If you change one of these variables (especially the "%c" part), then you should also change the others to keep things aligned. The following %-sequences are supported:

  • %a Number of commits this ref has over the one we compare to.
  • %b Number of commits the ref we compare to has over this one.
  • %c Number of commits this ref has over the one we compare to. For the ref which all other refs are compared this is instead "@", if it is the current branch, or "#" otherwise.
  • %C For the ref which all other refs are compared this is "@", if it is the current branch, or "#" otherwise. For all other refs " ".
  • %h Hash of this ref’s tip.
  • %m Commit summary of the tip of this ref.
  • %n Name of this ref.
  • %u Upstream of this local branch.
  • %U Upstream of this local branch and additional local vs. upstream information.

user option magit-refs-filter-alist​

The purpose of this option is to forgo displaying certain refs based on their name. If you want to not display any refs of a certain type, then you should remove the appropriate function from magit-refs-sections-hook instead.

This alist controls which tags and branches are omitted from being displayed in magit-refs-mode buffers. If it is nil, then all refs are displayed (subject to magit-refs-sections-hook).

All keys are tried in order until one matches. Then its value is used and subsequent elements are ignored. If the value is non-nil, then the reference is displayed, otherwise it is not. If no element matches, then the reference is displayed.

A key can either be a regular expression that the refname has to match, or a function that takes the refname as only argument and returns a boolean. A remote branch such as "origin/master" is displayed as just "master", however for this comparison the former is used.

RET     (magit-visit-ref)​

This command visits the reference or revision at point in another buffer. If there is no revision at point or with a prefix argument then it prompts for a revision.

This command behaves just like magit-show-commit as described above, except if point is on a reference in a magit-refs-mode buffer, in which case the behavior may be different, but only if you have customized the option magit-visit-ref-behavior.

user option magit-visit-ref-behavior​

This option controls how magit-visit-ref behaves in magit-refs-mode buffers.

By default magit-visit-ref behaves like magit-show-commit, in all buffers, including magit-refs-mode buffers. When the type of the section at point is commit then "RET" is bound to magit-show-commit, and when the type is either branch or tag then it is bound to magit-visit-ref.

"RET" is one of Magit’s most essential keys and at least by default it should behave consistently across all of Magit, especially because users quickly learn that it does something very harmless; it shows more information about the thing at point in another buffer.

However "RET" used to behave differently in magit-refs-mode buffers, doing surprising things, some of which cannot really be described as "visit this thing". If you’ve grown accustomed this behavior, you can restore it by adding one or more of the below symbols to the value of this option. But keep in mind that by doing so you don’t only introduce inconsistencies, you also lose some functionality and might have to resort to M-x magit-show-commit to get it back.

magit-visit-ref looks for these symbols in the order in which they are described here. If the presence of a symbol applies to the current situation, then the symbols that follow do not affect the outcome.

  • focus-on-ref

    With a prefix argument update the buffer to show commit counts and lists of cherry commits relative to the reference at point instead of relative to the current buffer or HEAD.

    Instead of adding this symbol, consider pressing "C-u y o RET".

  • create-branch

    If point is on a remote branch, then create a new local branch with the same name, use the remote branch as its upstream, and then check out the local branch.

    Instead of adding this symbol, consider pressing "b c RET RET", like you would do in other buffers.

  • checkout-any

    Check out the reference at point. If that reference is a tag or a remote branch, then this results in a detached HEAD.

    Instead of adding this symbol, consider pressing "b b RET", like you would do in other buffers.

  • checkout-branch

    Check out the local branch at point.

    Instead of adding this symbol, consider pressing "b b RET", like you would do in other buffers.

• References Sections: