moliva / git-blame.nvim

Git Blame plugin for Neovim written in Lua

git-blame.nvim

A git blame plugin for Neovim written in Lua

Installation

Using vim-plug

Plug 'f-person/git-blame.nvim'

Requirements

• Neovim >= 0.5.0
• git

The Why

There were several Vim plugins providing this functionality, but most of them were written in VimScript and didn't work well for me. coc-git also had option for showing blame info, it worked really well for me, I like it. However, recently I decided to switch to Neovim's builtin LSP instead of using CoC and having something running on Node.js just for git blame was not the best thing.

Demo

Configuration

Enabled

Enables git-blame.nvim on Neovim startup. You can toggle git blame messages on/off with the :GitBlameToggle command.

Default: 1

let g:gitblame_enabled = 0

Message template

The template for the blame message that will be shown.

Default: ' <author> • <date> • <summary>'

Available options: <author>, <committer>, <date>, <committer-date>, <summary>, <sha>

let g:gitblame_message_template = '<summary> • <date> • <author>'

Message when not committed yet

The blame message that will be shown when the current modification hasn't been committed yet.

Default: ' Not Committed Yet'

let g:gitblame_message_when_not_committed = 'Oh please, commit this !'

Date format

The format of the date fields.

Default: %c

Available options:

%r  relative date (e.g., 3 days ago)
%a  abbreviated weekday name (e.g., Wed)
%A  full weekday name (e.g., Wednesday)
%b  abbreviated month name (e.g., Sep)
%B  full month name (e.g., September)
%c  date and time (e.g., 09/16/98 23:48:10)
%d  day of the month (16) [01-31]
%H  hour, using a 24-hour clock (23) [00-23]
%I  hour, using a 12-hour clock (11) [01-12]
%M  minute (48) [00-59]
%m  month (09) [01-12]
%p  either "am" or "pm" (pm)
%S  second (10) [00-61]
%w  weekday (3) [0-6 = Sunday-Saturday]
%x  date (e.g., 09/16/98)
%X  time (e.g., 23:48:10)
%Y  full year (1998)
%y  two-digit year (98) [00-99]
%%  the character `%´

let g:gitblame_date_format = '%r'

Highlight group

The highlight group for virtual text.

Default: Comment

let g:gitblame_highlight_group = "Question"

nvim_buf_set_extmark optional parameters

nvim_buf_set_extmark is the function used for setting the virtual text. You can view an up-to-date full list of options in the Neovim documentation.

Warning: overwriting id and virt_text will break the plugin behavior.

let g:gitblame_set_extmark_options = {
    \ 'priority': 7,
    \ }

Virtual text enabled

If the blame message should be displayed as virtual text.

You may want to disable this if you display the blame message in statusline.

Default: 1

let g:gitblame_display_virtual_text = 0

Ignore by Filetype

A list of filetypes for which gitblame information will not be displayed.

Default: []

let g:gitblame_ignored_filetypes = ['lua', 'c']

Commands

Open the commit URL in browser

:GitBlameOpenCommitURL opens the commit URL of commit under the cursor. Tested to work with GitHub and GitLab.

Enable/Disable git blame messages

• :GitBlameToggle toggles git blame on/off,
• :GitBlameEnable enables git blame messages,
• :GitBlameDisable disables git blame messages.

Copy SHA hash

:GitBlameCopySHA copies the SHA hash of current line's commit into the system's clipboard.

Copy Commit URL

:GitBlameCopyCommitURL copies the commit URL of current line's commit into the system's clipboard.

Statusline integration

The plugin provides you with two functions which you can incorporate into your statusline of choice:

-- Lua
local git_blame = require('gitblame')

git_blame.is_blame_text_available() -- Returns a boolean value indicating whether blame message is available
git_blame.get_current_blame_text() --  Returns a string with blame message

Here is an example of integrating with lualine.nvim:

-- Lua
vim.g.gitblame_display_virtual_text = 0 -- Disable virtual text
local git_blame = require('gitblame')

require('lualine').setup({
    sections = {
            lualine_c = {
                { git_blame.get_current_blame_text, cond = git_blame.is_blame_text_available }
            }
    }
})

Changing the timeago-format language

The plugin uses lua-timeago for displaying commit dates in a relative time ago format. Take a look at the languages directory for a list of pre-installed languages. If you wish to use a language that's not built into lua-timeago, you can do that too; please consider opening a PR to lua-timeago if you choose to do so :)

To set a language, call the set_language method:

-- Lua
require('lua-timeago').set_language(require('lua-timeago/languages/hy'))

" Vimscript
:lua require('lua-timeago').set_language(require('lua-timeago/languages/hy'))

Thanks To

• coc-git for some parts of code.
• blamer.nvim for documentation inspiration.