GitLens Documentation

Install  
Contact Support  
GitHub.com Repository  
GitKraken.com  

Features

Core features availible to both free and paid GitLens users.

Revision Navigation

  • Adds an Open Changes with Previous Revision command (gitlens.diffWithPrevious) to compare the current file or revision with the previous commit revision
  • Adds an Open Changes with Next Revision command (gitlens.diffWithNext) to compare the current file or revision with the next commit revision
  • Adds an Open Line Changes with Previous Revision command (gitlens.diffLineWithPrevious) to compare the current file or revision with the previous line commit revision
  • Adds an Open Changes with Working File command (gitlens.diffWithWorking) to compare the current revision or most recent commit revision of the current file with the working tree
  • Adds an Open Line Changes with Working File command (gitlens.diffLineWithWorking) to compare the commit revision of the current line with the working tree
  • Adds an Open Changes with Branch or Tag… command (gitlens.diffWithRevisionFrom) to compare the current file or revision with another revision of the same file on the selected reference
  • Adds an Open Changes with Revision… command (gitlens.diffWithRevision) to compare the current file or revision with another revision of the same file

Current Line Blame

Adds an unobtrusive, customizable, and themable, blame annotation at the end of the current line.

  • Contains the author, date, and message of the current line’s most recent commit (by default)
  • Adds a Toggle Line Blame Annotations (gitlens.toggleLineBlame) to toggle the blame annotation on and off

Git CodeLens

Adds Git authorship CodeLens to the top of the file and on code blocks (optional, on by default)

  • Recent Change — author and date of the most recent commit for the file or code block

    • Click the CodeLens to show a commit file details quick pick menu with commands for comparing, navigating and exploring commits, and more (by default)
  • Authors — number of authors of the file or code block and the most prominent author (if there is more than one)

    • Click the CodeLens to toggle the file Git blame annotations on and off of the whole file (by default)
    • Will be hidden if the author of the most recent commit is also the only author of the file or block, to avoid duplicate information and reduce visual noise
  • Provides customizable click behavior for each CodeLens — choose between one of the following

    • Toggle file blame annotations on and off
    • Compare the commit with the previous commit
    • Show a quick pick menu with details and commands for the commit
    • Show a quick pick menu with file details and commands for the commit
    • Show a quick pick menu with the commit history of the file
    • Show a quick pick menu with the commit history of the current branch
  • Adds a Toggle Git CodeLens command (gitlens.toggleCodeLens) with a shortcut of shift+alt+b to toggle the CodeLens on and off


Status Bar Blame

Adds a customizable Git blame annotation showing the commit and author who last modified the current line to the status bar (optional, on by default)

  • Contains the commit author and date (by default)

  • Click the status bar item to show a commit details quick pick menu with commands for comparing, navigating and exploring commits, and more (by default)

  • Provides customizable click behavior — choose between one of the following

    • Toggle file blame annotations on and off
    • Toggle CodeLens on and off
    • Compare the line commit with the previous commit
    • Compare the line commit with the working tree
    • Show a quick pick menu with details and commands for the commit (default)
    • Show a quick pick menu with file details and commands for the commit
    • Show a quick pick menu with the commit history of the file
    • Show a quick pick menu with the commit history of the current branch

Hovers

Current Line Hovers

Adds customizable Git blame hovers accessible over the current line

Details Hover

Adds a details hover annotation to the current line to show more commit details (optional, on by default)

  • Provides automatic issue linking to Bitbucket, Gerrit, Gitea, GitHub, GitLab, and Azure DevOps in commit messages
  • Provides a quick-access command bar with Open Changes, Blame Previous Revision, Open on Remote, Invite to Live Share (if available), and Show More Actions command buttons
  • Click the commit SHA to execute the Show Commit command

Changes (diff) Hover

Adds a changes (diff) hover annotation to the current line to show the line’s previous version (optional, on by default)

  • Click the Changes to execute the Open Changes command
  • Click the current and previous commit SHAs to execute the Show Commit command

Annotation Hovers

Adds customizable Git blame hovers accessible when annotating

Details Hover

Adds a details hover annotation to each line while annotating to show more commit details (optional, on by default)

  • Provides automatic issue linking to Bitbucket, Gerrit, Gitea, GitHub, GitLab, and Azure DevOps in commit messages
  • Provides a quick-access command bar with Open Changes, Blame Previous Revision, Open on Remote, Invite to Live Share (if available), and Show More Actions command buttons
  • Click the commit SHA to execute the Show Commit command

Changes (diff) Hover

Adds a changes (diff) hover annotation to each line while annotating to show the line’s previous version (optional, on by default)

  • Click the Changes to execute the Open Changes command
  • Click the current and previous commit SHAs to execute the Show Commit command

File Blame

Adds on-demand, customizable, and themable, gutter blame annotations to show the commit and author who last modified each line of a file

  • Contains the commit message and date, by default
  • Adds a heatmap (age) indicator on right edge (by default,) of the gutter to provide an easy, at-a-glance way to tell how recently lines were changed (optional, on by default)
  • See the gutter heatmap section below for more details
  • Adds a Toggle File Blame Annotations command (gitlens.toggleFileBlame) with a shortcut of alt+b to toggle the blame annotations on and off
  • Press Escape to turn off the annotations

Gutter Changes

Adds an on-demand, customizable, and themable, gutter changes annotation to highlight any local (unpublished) changes or lines changed by the most recent commit.

  • Adds Toggle File Changes command (gitlens.toggleFileChanges) to toggle the changes annotations on and off
  • Press Escape to turn off the annotations

Gutter Heatmap

Adds an on-demand heatmap to the edge of the gutter to show how recently lines were changed

  • The indicator’s customizable color will either be hot or cold based on the age of the most recent change (cold after 90 days by default)
  • The indicator’s brightness ranges from bright (newer) to dim (older) based on the relative age, which is calculated from the median age of all the changes in the file
  • Adds Toggle File Heatmap Annotations command (gitlens.toggleFileHeatmap) to toggle the heatmap on and off
  • Press Escape to turn off the annotations

Side Bar Views

GitLens adds many side bar views to provide additional rich functionality. The default layout (location) of these views can be quickly customized via the GitLens: Set Views Layout (gitlens.setViewsLayout) command from the VS Code Command Palette.

  • Source Control Layout — shows all the views together on the Source Control side bar
  • GitLens Layout — shows all the views together on the GitLens side bar

Check out the Side Bar documentation for more information.


Git Command Palette

Adds a customizable Git Command Palette command (gitlens.gitCommands) to provide guided (step-by-step) access to many common Git commands, as well as quick access to commit history and search, stashes, and more

  • Quickly navigate and execute Git commands through easy-to-use menus where each command can require an explicit confirmation step before executing

Quick Commit Access

  • Adds a Show Branch History command (gitlens.showQuickBranchHistory) to show a quick pick menu to explore the commit history of the selected branch
  • Adds a Show Current Branch History command (gitlens.showQuickRepoHistory) to show a quick pick menu to explore the commit history of the current branch

  • Adds a Show File History command (gitlens.showQuickFileHistory) to show quick pick menu to explore the commit history of the current file

Adds a Search Commits command (gitlens.showCommitSearch) to show quick pick menu to search for commits

  • by message — use <message> to find commits with messages that match <message> — See Git docs
  • or, by author — use @<pattern> to find commits with authors that match <pattern> — See Git docs
  • or, by commit SHA — use #<sha> to find a commit with id of <sha> — See Git docs
  • or, by files — use :<path/glob> to find commits with file names that match <path/glob> — See Git docs
  • or, by changes — use ~<pattern> to find commits with differences whose patch text contains added/removed lines that match <pattern> — See Git docs

  • Adds a Show Commit command (gitlens.showQuickCommitDetails) to show a quick pick menu to explore a commit and take action upon it

Adds a Show Line Commit command (gitlens.showQuickCommitFileDetails) to show a quick pick menu to explore a file of a commit and take action upon it

Quick Stash Access


  • Adds a Show Stashes command (gitlens.showQuickStashList) to show a quick pick menu to explore your stashes

Quick Status Access

  • Adds a Show Repository Status command (gitlens.showQuickRepoStatus) to show a quick pick menu to for visualizing the current repository status


Interactive Rebase Editor

Adds a user-friendly interactive rebase editor to more easily configure an interactive rebase session

  • Quickly re-order, edit, squash, and drop commits
  • Includes drag & drop support!

To use this directly from your terminal, e.g. when running git rebase -i:

  • set VS Code as your default Git editor
    • git config --global core.editor "code --wait"
  • or, to only affect rebase, set VS Code as your Git rebase editor
    • git config --global sequence.editor "code --wait"

To use the Insiders edition of VS Code, replace code in the above with code-insiders


Terminal Links

  • Optionally adds autolinks for branches, tags, and commit ranges in the integrated terminal to quickly explore their commit history
  • Optionally adds autolinks for commits in the integrated terminal to quickly explore the commit and take action upon it

Remote Provider Integrations

GitLens provides rich integrations with many remote providers, including GitHub, GitHub Enterprise, GitLab, Gitea, Gerrit, Bitbucket, Bitbucket Server, and Azure DevOps. You can also define custom remote providers or remote providers with custom domains as well.

Basic integrations provide issue and pull request auto-linking, while richer integrations (e.g. GitHub) can provide rich hover information provided for auto-linked issues and pull requests, associate pull requests with branches and commits, and provide avatars.

Additionally, these integrations provide commands to copy the url of or open, files, commits, branches, and the repository on the remote provider.

  • Open File from Remote command (gitlens.openFileFromRemote) — opens the local file from a url of a file on a remote provider
  • Open File on Remote command (gitlens.openFileOnRemote) — opens a file or revision on the remote provider
  • Copy Remote File Url command (gitlens.copyRemoteFileUrlToClipboard) — copies the url of a file or revision on the remote provider
  • Open File on Remote From… command (gitlens.openFileOnRemoteFrom) — opens a file or revision on a specific branch or tag on the remote provider
  • Copy _Remote File Url From… command (gitlens.copyRemoteFileUrlFrom) — copies the url of a file or revision on a specific branch or tag the remote provider
  • Open Commit on Remote command (gitlens.openCommitOnRemote) — opens a commit on the remote provider
  • Copy Remote Commit Url command (gitlens.copyRemoteCommitUrl) — copies the url of a commit on the remote provider
  • Open Branch on Remote command (gitlens.openBranchOnRemote) — opens the branch on the remote provider
  • Copy Remote Branch Url command (gitlens.copyRemoteBranchUrl) — copies the url of a branch on the remote provider
  • Open Branches on Remote command (gitlens.openBranchesOnRemote) — opens the branches on the remote provider
  • Copy Remote Branches Url command (gitlens.copyRemoteBranchesUrl) — copies the url of the branches on the remote provider
  • Open Comparison on Remote command (gitlens.openComparisonOnRemote) — opens the comparison on the remote provider
  • Copy Remote Comparison Url command (gitlens.copyRemoteComparisonUrl) — copies the url of the comparison on the remote provider
  • Open Pull Request command (gitlens.openPullRequestOnRemote) — opens the pull request on the remote provider
  • Copy Pull Request Url command (gitlens.copyRemotePullRequestUrl) — copies the url of the pull request on the remote provider
  • Open Repository on Remote command (gitlens.openRepoOnRemote) — opens the repository on the remote provider
  • Copy Remote Repository Url command (gitlens.copyRemoteRepositoryUrl) — copies the url of the repository on the remote provider

Powerful Commands

  • Adds an Add Co-authors command (gitlens.addAuthors) to add a co-author to the commit message input box

  • Adds a _Copy SH_A command (gitlens.copyShaToClipboard) to copy the commit SHA of the current line to the clipboard or from the most recent commit to the current branch, if there is no current editor

  • Adds a Copy Message command (gitlens.copyMessageToClipboard) to copy the commit message of the current line to the clipboard or from the most recent commit to the current branch, if there is no current editor

  • Adds a Copy Current Branch command (gitlens.copyCurrentBranch) to copy the name of the current branch to the clipboard

  • Adds a Switch to Another Branch (gitlens.views.switchToAnotherBranch) command — to quickly switch the current branch

  • Adds a Compare References… command (gitlens.compareWith) to compare two selected references

  • Adds a Compare HEAD with… command (gitlens.compareHeadWith) to compare the index (HEAD) with the selected reference

  • Adds a Compare Working Tree with… command (gitlens.compareWorkingWith) to compare the working tree with the selected reference

  • Adds an Open Changes (difftool) command (gitlens.externalDiff) to open the changes of a file or set of files with the configured git difftool

  • Adds an Open All Changes (difftool) command (gitlens.externalDiffAll) to open all working changes with the configured git difftool

  • Adds an Open Directory Compare (difftool) command (gitlens.diffDirectoryWithHead) to compare the working tree with HEAD with the configured Git difftool

  • Adds an Open Directory Compare (difftool) with… command (gitlens.diffDirectory) to compare the working tree with the selected reference with the configured Git difftool

  • Adds an Open File command (gitlens.openWorkingFile) to open the working file for the current file revision

  • Adds an Open Revision… command (gitlens.openFileRevision) to open the selected revision for the current file

  • Adds an Open Revision from… command (gitlens.openFileRevisionFrom) to open the revision of the current file from the selected reference

  • Adds an Open Blame Prior to Change command (gitlens.openBlamePriorToChange) to open the blame of prior revision of the selected line in the current file

  • Adds a Open Changed Files command (gitlens.openChangedFiles) to open any files with working tree changes

  • Adds a Close Unchanged Files command (gitlens.closeUnchangedFiles) to close any files without working tree changes

  • Adds an Enable Debug Logging command (gitlens.enableDebugLogging) to enable debug logging to the GitLens output channel

  • Adds a Disable Debug Logging command (gitlens.disableDebugLogging) to disable debug logging to the GitLens output channel


Menus & Toolbars

GitLens provides customizable menu and toolbar contributions to put you in control over where GitLens’ commands are shown. The easiest way to configure these settings is via the GitLens interactive settings editor.

For example, if you uncheck the Add to the editor group toolbar you will see the following items removed from the toolbar:

You can also expand each group to control each area more granularly.

Have feedback about this article? Did we miss something? Let us know!
On this page