Skip to content

Custom Formatting

Jump to bottom
Eric Amodio edited this page Jul 18, 2019 · 7 revisions

GitLens supports rich customization options over how commits and files are displayed within GitLens' views. Many of these flexible customizations are expressed as template strings, which can contain replacement placeholders (tokens). Replacement tokens are indicated by the dollar sign and curly braces: ${token}. The set of available replacement tokens is dependent upon what is being formatted, a commit or a file. Any spaces in the template strings will be preserved.

Examples: (spaces are shown as ·)

  • "${author}"
    • → Eric·Amodio
  • "${author},··${date}"
    • → Eric·Amodio,··Jan,·1,·2019

Token Formatting

Template string tokens can additionally contain non-word characters surrounding the token within the token expression, e.g. ${ token!}. This allows for both conditional spacing and formatting, since the additional characters are only included if the token itself isn't empty. Also, just as with spaces in the template strings themselves, any spaces in the token expression will be preserved.

Examples: (spaces are shown as ·)

  • "${directory}${··←··originalPath}"
    • → src/app
    • → src/app··←··src/index.html
  • "${changes··•··}${author},·${agoOrDate}"
    • → +1·~3·-0··•··Eric Amodio,·1·day·ago
    • → Eric·Amodio,·1·day·ago

Formatting Directives

Template string tokens expressions can also contain a formatting directive. A directive must be preceeded by a vertical bar | and use the structure ${token|number?-}:

  • number — specifies the length of the replacement string; the string will be truncated or padded as needed
  • ? — indicates that whitespace can be reclaimed between this token and the next one
  • - — specifies left-padding instead of the default right-padding

Note, ? and - cannot be used within the same token.

In the example below, the commit message will be truncated or right-padded to 40 characters and relative commit date will be truncated or left-padded to around 14 characters. Because of the ? any whitespace between the two tokens can be reclaimed so that the relative commit date could expand beyond 14 characters, if needed and the commit message was less than 40 characters. Overall the combined length will always be 55 characters (40 + 1 + 14), but how much whitespace can be reclaimed is dependent on the actual length of the tokens.

Example: (spaces are shown as ·)

  • ${message|40?}·${ago|14-}
    • → Uncommitted Changes···················a few seconds ago
    • → A long commit message describing the ch…······1 day ago
    • → A long commit message describing the ch…·over 10 years…

Commit Tokens

Template strings for formatting commits support the following replacement tokens:

  • ${id} — commit id (sha)
  • ${author} — commit author
  • ${email} — commit author e-mail
  • ${message} — commit message
  • ${ago} — relative commit or authored date (e.g. 1 day ago)
  • ${date} — formatted commit or authored date
  • ${agoOrDate} — relative or formatted commit or authored date controlled by the gitlens.defaultDateStyle setting
  • ${authorAgo} — relative authored date (e.g. 1 day ago)
  • ${authorDate} — formatted authored date
  • ${authorAgoOrDate} — relative or formatted authored date controlled by the gitlens.defaultDateStyle setting
  • ${committerAgo} — relative committed date (e.g. 1 day ago)
  • ${committerDate} — formatted committed date
  • ${committerAgoOrDate} — relative or formatted committed date controlled by the gitlens.defaultDateStyle setting
  • ${tips} — an indicator if the commit is a tip of any branches or tags
  • ${changes} — a commit indicator of adds, changes, renames, and deletes (e.g. +1 ~3 -0) — not always available
  • ${changesShort} — a shortened commit indicator of adds, changes, renames, and deletes (e.g. +1~3) — not always available
  • ${avatar} — commit author avatar — only available in hovers
  • ${commands} — a set of commit command buttons — only available in hovers

File Tokens

Template strings for formatting files support the following replacement tokens:

  • ${directory} — directory name
  • ${file} — file name
  • ${filePath} — formatted file name and path (e.g. README.md • src)
  • ${originalPath} — full file path of the original file, if renamed
  • ${path} — full file path
  • ${status} — commit status of the file, if any (e.g. Modified)
  • ${working} — working tree status indicator of the file, if any (e.g. ✎ ✓)
    • ✎ — indicates the file has unstaged changes in the working tree
    • ✓ — indicates the file has staged changes in the working tree
Clone this wiki locally