Custom Formatting

Custom Formatting

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: ${expression}. The set of available replacement tokens is dependent upon what is being formatted, a commit or a file.

Examples:

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

Commit Formatting

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 date (e.g. 1 day ago)
  • Date source (authored vs committed) is controlled by the gitlens.defaultDateSource setting
• ${date} — formatted commit date
  • Date source (authored vs committed) is controlled by the [gitlens.defaultDateSource setting (https://github.com/eamodio/vscode-gitlens#general-settings-)
  • Date formatting is controlled by the gitlens.defaultDateFormat setting
• ${agoOrDate} — relative or formatted commit date controlled by the gitlens.defaultDateStyle setting
  • Date source (authored vs committed) is controlled by the gitlens.defaultDateSource setting
• ${authorAgo} — relative authored date (e.g. 1 day ago)
• ${authorDate} — formatted authored date
  • Date formatting is controlled by the gitlens.defaultDateFormat setting
• ${authorAgoOrDate} — relative or formatted authored date controlled by the gitlens.defaultDateStyle setting
  • Date formatting is controlled by the gitlens.defaultDateFormat setting
• ${avatar} — commit author avatar
• ${changes} — a commit indicator of adds, changes, renames, and deletes (e.g. 1 file added, 3 files changed, 1 file deleted)
• ${changesShort} — a shortened commit indicator of adds, changes, renames, and deletes (e.g. +1 ~3 -1)
• ${commands} — a set of commit command "buttons"
• ${committerAgo} — relative committed date (e.g. 1 day ago)
• ${committerDate} — formatted committed date
  • Date formatting is controlled by the gitlens.defaultDateFormat setting
• ${committerAgoOrDate} — relative or formatted committed date controlled by the gitlens.defaultDateStyle setting

File Formatting

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