-
Notifications
You must be signed in to change notification settings - Fork 1.8k
Custom Formatting
GitLens supports rich customization options of many of its appearances via template strings with replacement "tokens", written as ${token}. Any text or spacing around tokens is preserved in the output.
For example, with the commit format template:
${author}, ${agoOrDate} • ${message}
GitLens would render something like:
Eric Amodio, 3 days ago • Adds a welcome view to the Home view
These settings accept templates using the commit tokens below:
| Setting | Controls |
|---|---|
gitlens.blame.format |
File blame annotations (gutter) |
gitlens.currentLine.format |
Inline blame annotation on the current line |
gitlens.currentLine.uncommittedChangesFormat |
Inline blame annotation when the line has uncommitted changes |
gitlens.statusBar.format |
Blame information in the status bar |
gitlens.statusBar.tooltipFormat |
Tooltip of the status bar blame item |
gitlens.hovers.detailsMarkdownFormat |
Commit details in hovers |
gitlens.views.commitFormat |
Commits shown in the views (sidebar) |
gitlens.views.commitDescriptionFormat |
Description (dimmed text) of commits in the views |
gitlens.views.stashFormat |
Stashes shown in the views |
gitlens.views.stashDescriptionFormat |
Description of stashes in the views |
These settings accept templates using the file tokens below:
| Setting | Controls |
|---|---|
gitlens.views.commitFileFormat |
Files within commits in the views |
gitlens.views.commitFileDescriptionFormat |
Description of files within commits in the views |
gitlens.views.stashFileFormat |
Files within stashes in the views |
gitlens.views.stashFileDescriptionFormat |
Description of files within stashes in the views |
gitlens.views.statusFileFormat |
Working/status files in the views |
gitlens.views.statusFileDescriptionFormat |
Description of working/status files in the views |
Text placed inside the token braces, before or after the token name, is only rendered when the token resolves to a non-empty value. This lets you add separators or labels that disappear when there is nothing to show.
-
Non-word characters (spaces, punctuation) can be placed directly inside the braces:
${ message}— renders a leading space only if there is a message${message • }— renders " • " after the message only if there is a message -
Word characters (letters, numbers) must be wrapped in single quotes:
${'PR 'pullRequest}— rendersPR #123only when a pull request is found${pullRequest' found'}— renders a quoted suffix only when the token is non-empty
Prefix and suffix can be combined: ${' via 'pullRequest}.
Directives are specified after the token name, following a vertical bar |, in the form ${token|number?-}:
| Directive | Effect |
|---|---|
number |
Truncates or pads the value to the given width. Longer values are truncated with an ellipsis (…); shorter values are padded with non-breaking spaces. 0 is a special case that collapses the token to just its prefix/suffix. |
? |
Collapses whitespace — if the value is shorter than number, the unused width is donated to the next token instead of padding this one. Useful for tabular layouts (e.g. blame annotations) that should stay compact. |
- |
Pads on the left (right-aligns the value). The default is right-padding (left-aligned). |
For example: ${author|20?} truncates/pads the author to 20 characters, letting a following token reclaim any unused space, and ${id|-10} right-aligns the commit id within 10 characters.
NOTE:
?and-cannot be combined on the same token — only the first one after the number is applied.
| Token | Description |
|---|---|
${id} |
Short commit SHA (marks unpublished commits in hovers) |
${sha} |
Short commit SHA |
${message} |
Commit message |
${tips} |
Indicators for any branches or tags pointing at the commit |
${link} |
Commit SHA rendered as a clickable link that opens the commit in Commit Details (hovers & markdown contexts only) |
${signature} |
Icon indicating the commit is signed, linking to Commit Details for verification (markdown contexts only) |
| Token | Description |
|---|---|
${author} |
Author name (respects gitlens.defaultCurrentUserNameStyle, e.g. showing "You" for your own commits; rendered as an email link in hovers) |
${authorFirst} |
Author's first name |
${authorLast} |
Author's last name |
${authorNotYou} |
Author name, but empty when you are the author — useful for hiding your own name in blame annotations |
${email} |
Author email address |
The unprefixed date tokens use the authored or committed date according to gitlens.defaultDateSource. The author- and committer-prefixed variants are pinned to that specific date regardless of the setting.
| Token | Description |
|---|---|
${ago} |
Relative date (e.g. "1 day ago") |
${date} |
Absolute date, formatted via gitlens.defaultDateFormat (or the feature-specific *.dateFormat setting) |
${agoOrDate} |
Relative or absolute date, based on gitlens.defaultDateStyle
|
${agoOrDateShort} |
As above, using the short relative format (e.g. "1d") |
${agoAndDate} |
Relative and absolute date together, e.g. "1 day ago (June 9th, 2026 1:00pm)" |
${agoAndDateShort} |
As above, using the short relative format |
${agoAndDateBothSources} |
Relative and absolute date, also showing the other date source when the authored and committed dates differ |
${authorAgo} |
Relative authored date |
${authorDate} |
Absolute authored date |
${authorAgoOrDate} |
Relative or absolute authored date, based on gitlens.defaultDateStyle
|
${authorAgoOrDateShort} |
As above, using the short relative format |
${committerAgo} |
Relative committed date |
${committerDate} |
Absolute committed date |
${committerAgoOrDate} |
Relative or absolute committed date, based on gitlens.defaultDateStyle
|
${committerAgoOrDateShort} |
As above, using the short relative format |
Related settings: gitlens.defaultDateSource, gitlens.defaultDateStyle, gitlens.defaultDateFormat, gitlens.defaultDateShortFormat, gitlens.defaultTimeFormat
| Token | Description |
|---|---|
${changes} |
Files added, changed, and deleted (e.g. "+1 ~3 -0"; colorized in hovers) |
${changesDetail} |
As above, followed by an expanded description (e.g. "+1 ~3 -0 (1 file added, 3 files changed)") |
${changesShort} |
Compact indicator omitting zero counts (e.g. "+1~3") |
These tokens resolve the pull request that introduced the commit and require a connected integration (GitHub, GitLab, etc.). They are only filled in contexts that look up pull requests, such as hovers and the views.
| Token | Description |
|---|---|
${pullRequest} |
Associated pull request (e.g. "PR #123"; rendered as a link with details in hovers) |
${pullRequestState} |
State of the pull request (e.g. "opened", "merged", "closed") |
${pullRequestDate} |
Absolute date of the pull request |
${pullRequestAgo} |
Relative date of the pull request |
${pullRequestAgoOrDate} |
Relative or absolute date, based on gitlens.defaultDateStyle
|
Only meaningful for stash entries (e.g. in gitlens.views.stashFormat).
| Token | Description |
|---|---|
${stashName} |
Stash name (e.g. "stash@{0}") |
${stashNumber} |
Stash number |
${stashOnRef} |
Branch the stash was created on |
These tokens render rich (markdown/HTML) content and produce nothing in plaintext contexts such as blame annotations or the status bar text.
| Token | Description |
|---|---|
${avatar} |
Author avatar image (requires gitlens.hovers.avatars) |
${commands} |
Commit command buttons (Open Changes, Compare, etc.) |
${footnotes} |
Footnotes accumulated by other tokens in the template (e.g. pull request details) |
| Token | Description |
|---|---|
${file} |
File name (e.g. "README.md") |
${directory} |
Directory name (e.g. "src") |
${path} |
Full file path (e.g. "src/README.md") |
${filePath} |
Formatted file name and path (e.g. "README.md • src") |
${originalPath} |
Original file path, if the file was renamed |
${status} |
Status of the file in the commit (e.g. "Modified", "Added", "Deleted") |
${working} |
Working tree indicator — ✎ for working tree (unstaged) changes, ✔ for staged changes, ✎ ✔ for both |
${changes} |
Lines added and deleted (e.g. "+1 -2"; colorized in rich contexts) |
${changesDetail} |
Expanded description of the line changes |
${changesShort} |
Compact line-change indicator omitting zero counts |
Show the commit message with the author appended only when it isn't you:
${message}${' by 'authorNotYou}
Compact, aligned blame annotation that reclaims unused space:
${author|20?} ${agoOrDate|14-}
Commit format with pull request and branch/tag tips:
${author}${' via 'pullRequest}, ${agoOrDate} • ${message} ${tips}