Variable: magit-blame-styles

magit-blame-styles is a customizable variable defined in magit-blame.el.

Value

((headings (heading-format . "%-20a %C %s\n"))
 (highlight (highlight-face . magit-blame-highlight))
 (lines (show-lines . t) (show-message . t)))

Documentation

List of styles used to visualize blame information.

The style used in the current buffer can be cycled from the blame popup. Blame commands (except magit-blame-echo) use the first style as the initial style when beginning to blame in a buffer.

Each entry has the form (IDENT (KEY . VALUE)...). IDENT has to be a symbol uniquely identifying the style. The following KEYs are recognized:

 show-lines
    Whether to prefix each chunk of lines with a thin line.
    This has no effect if heading-format is non-nil.
 show-message
    Whether to display a commit's summary line in the echo area
    when crossing chunks.
 highlight-face
    Face used to highlight the first line of each chunk.
    If this is nil, then those lines are not highlighted.
 heading-format
    String specifying the information to be shown above each
    chunk of lines. It must end with a newline character.
 margin-format
    String specifying the information to be shown in the left
    buffer margin. It must NOT end with a newline character.
    This can also be a list of formats used for the lines at
    the same positions within the chunk. If the chunk has
    more lines than formats are specified, then the last is
    repeated. WARNING: Adding this key affects performance;
    see the note at the end of this docstring.
 margin-width
    Width of the margin, provided margin-format is non-nil.
 margin-face
    Face used in the margin, provided margin-format is
    non-nil. This face is used in combination with the faces
    that are specific to the used %-specs. If this is nil,
    then magit-blame-margin is used.
 margin-body-face
    Face used in the margin for all but first line of a chunk.
    This face is used in combination with the faces that are
    specific to the used %-specs. This can also be a list of
    faces (usually one face), in which case only these faces
    are used and the %-spec faces are ignored. A good value
    might be (magit-blame-dimmed). If this is nil, then
    the same face as for the first line is used.

The following %-specs can be used in heading-format and margin-format:

  %H hash using face magit-blame-hash
  %h truncated hash using face magit-blame-hash
  %s summary using face magit-blame-summary
  %a author using face magit-blame-name
  %A author time using face magit-blame-date
  %c committer using face magit-blame-name
  %C committer time using face magit-blame-date

Note that for performance reasons %h results in truncated hashes, as opposed to properly abbreviated hashes that are guaranteed to uniquely identify a commit.

Additionally if margin-format ends with %f, then the string that is displayed in the margin is made at least margin-width characters wide, which may be desirable if the used face sets the background color.

Blame information is displayed using overlays. Such extensive use of overlays is known to slow down even basic operations, such as moving the cursor. To reduce the number of overlays the margin style had to be removed from the default value of this option.

Note that the margin overlays are created even if another style is currently active. This can only be prevented by not even defining a style that uses the margin. If you want to use this style anyway, you can restore this definition, which used to be part of the default value:

  (margin
   (margin-format . (" %s%f" " %C %a" " %H"))
   (margin-width . 42)
   (margin-face . magit-blame-margin)
   (margin-body-face . (magit-blame-dimmed)))

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

Source Code

;; Defined in ~/.emacs.d/elpa/magit-20260411.1452/magit-blame.el
(defcustom magit-blame-styles
  '((headings
     (heading-format   . "%-20a %C %s\n"))
    (highlight
     (highlight-face   . magit-blame-highlight))
    (lines
     (show-lines       . t)
     (show-message     . t)))
  "List of styles used to visualize blame information.

The style used in the current buffer can be cycled from the blame
popup.  Blame commands (except `magit-blame-echo') use the first
style as the initial style when beginning to blame in a buffer.

Each entry has the form (IDENT (KEY . VALUE)...).  IDENT has
to be a symbol uniquely identifying the style.  The following
KEYs are recognized:

 `show-lines'
    Whether to prefix each chunk of lines with a thin line.
    This has no effect if `heading-format' is non-nil.
 `show-message'
    Whether to display a commit's summary line in the echo area
    when crossing chunks.
 `highlight-face'
    Face used to highlight the first line of each chunk.
    If this is nil, then those lines are not highlighted.
 `heading-format'
    String specifying the information to be shown above each
    chunk of lines.  It must end with a newline character.
 `margin-format'
    String specifying the information to be shown in the left
    buffer margin.  It must NOT end with a newline character.
    This can also be a list of formats used for the lines at
    the same positions within the chunk.  If the chunk has
    more lines than formats are specified, then the last is
    repeated.  WARNING: Adding this key affects performance;
    see the note at the end of this docstring.
 `margin-width'
    Width of the margin, provided `margin-format' is non-nil.
 `margin-face'
    Face used in the margin, provided `margin-format' is
    non-nil.  This face is used in combination with the faces
    that are specific to the used %-specs.  If this is nil,
    then `magit-blame-margin' is used.
 `margin-body-face'
    Face used in the margin for all but first line of a chunk.
    This face is used in combination with the faces that are
    specific to the used %-specs.  This can also be a list of
    faces (usually one face), in which case only these faces
    are used and the %-spec faces are ignored.  A good value
    might be `(magit-blame-dimmed)'.  If this is nil, then
    the same face as for the first line is used.

The following %-specs can be used in `heading-format' and
`margin-format':

  %H    hash              using face `magit-blame-hash'
  %h    truncated hash    using face `magit-blame-hash'
  %s    summary           using face `magit-blame-summary'
  %a    author            using face `magit-blame-name'
  %A    author time       using face `magit-blame-date'
  %c    committer         using face `magit-blame-name'
  %C    committer time    using face `magit-blame-date'

Note that for performance reasons %h results in truncated
hashes, as opposed to properly abbreviated hashes that are
guaranteed to uniquely identify a commit.

Additionally if `margin-format' ends with %f, then the string
that is displayed in the margin is made at least `margin-width'
characters wide, which may be desirable if the used face sets
the background color.

Blame information is displayed using overlays.  Such extensive
use of overlays is known to slow down even basic operations, such
as moving the cursor.  To reduce the number of overlays the margin
style had to be removed from the default value of this option.

Note that the margin overlays are created even if another style
is currently active.  This can only be prevented by not even
defining a style that uses the margin.  If you want to use this
style anyway, you can restore this definition, which used to be
part of the default value:

  (margin
   (margin-format    . (\" %s%f\" \" %C %a\" \" %H\"))
   (margin-width     . 42)
   (margin-face      . magit-blame-margin)
   (margin-body-face . (magit-blame-dimmed)))"
  :package-version '(magit . "2.13.0")
  :group 'magit-blame
  :type '(alist :key-type symbol
                :value-type (alist :key-type symbol :value-type sexp)))