4.1.2 Naming Buffers

User Option: magit-generate-buffer-name-function

The function used to generate the names of Magit buffers.

Such a function should take the options magit-uniquify-buffer-names as well as magit-buffer-name-format into account. If it doesn’t, then should be clearly stated in the doc-string. And if it supports %-sequences beyond those mentioned in the doc-string of the option magit-buffer-name-format, then its own doc-string should describe the additions.

Function: magit-generate-buffer-name-default-function mode

This function returns a buffer name suitable for a buffer whose major-mode is MODE and which shows information about the repository in which default-directory is located.

This function uses magit-buffer-name-format and supporting all of the %-sequences mentioned the documentation of that option. It also respects the option magit-uniquify-buffer-names.

User Option: magit-buffer-name-format

The format string used to name Magit buffers.

At least the following %-sequences are supported:

• %m

  The name of the major-mode, but with the -mode suffix removed.

• %M

  Like %m but abbreviate magit-status-mode as magit.

• %v

  The value the buffer is locked to, in parentheses, or an empty string if the buffer is not locked to a value.

• %V

  Like %v, but the string is prefixed with a space, unless it is an empty string.

• %t

  The top-level directory of the working tree of the repository, or if magit-uniquify-buffer-names is non-nil an abbreviation of that.

• %x

  If magit-uniquify-buffer-names is nil "*", otherwise the empty string. Due to limitations of the uniquify package, buffer names must end with the path.

• %T

  Obsolete, use "%t%x" instead. Like %t, but append an asterisk if and only if magit-uniquify-buffer-names is nil.

The value should always contain %m or %M, %v or %V, and %t (or the obsolete %T). If magit-uniquify-buffer-names is non-nil, then the value must end with %t or %t%x (or the obsolete %T). See issue #2841.

User Option: magit-uniquify-buffer-names

This option controls whether the names of Magit buffers are uniquified. If the names are not being uniquified, then they contain the full path of the top-level of the working tree of the corresponding repository. If they are being uniquified, then they end with the basename of the top-level, or if that would conflict with the name used for other buffers, then the names of all these buffers are adjusted until they no longer conflict.

This is done using the uniquify package; customize its options to control how buffer names are uniquified.