A git blame plugin for Neovim written in Lua
- Installation
- Requirements
- The Why
- Demo
- Configuration
- Commands
- Statusline integration
- Changing the timeago-format language
- Thanks To
- Contributors <3
- Support
Using vim-plug
Plug 'f-person/git-blame.nvim'- Neovim >= 0.5.0
- git
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.
You can use setup to configure the plugin in Lua. This is the recommended way
if you're using Lua for your configs. Read the documentation below to learn
more about specific options (NOTE: options in the setup function don't
have the gitblame_ prefix).
NOTE: you don't have to call
setupif you don't want to customize the default behavior.
require('gitblame').setup {
--Note how the `gitblame_` prefix is omitted in `setup`
enabled = false,
}return {
"f-person/git-blame.nvim",
-- load the plugin at startup
event = "VeryLazy",
-- Because of the keys part, you will be lazy loading this plugin.
-- The plugin wil only load once one of the keys is used.
-- If you want to load the plugin at startup, add something like event = "VeryLazy",
-- or lazy = false. One of both options will work.
opts = {
-- your configuration comes here
-- for example
enabled = true, -- if you want to enable the plugin
message_template = " <summary> • <date> • <author> • <<sha>>", -- template for the blame message, check the Message template section for more options
date_format = "%m-%d-%Y %H:%M:%S", -- template for the date, check Date format section for more options
virtual_text_column = 1, -- virtual text start column, check Start virtual text at column section for more options
},
}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 = 0The 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>'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'The blame message that will be shown when the current modification hasn't been committed yet.
Supports the same template options as g:gitblame_message_template.
Default: ' Not Committed Yet'
let g:gitblame_message_when_not_committed = 'Oh please, commit this !'The highlight group for virtual text.
Default: Comment
let g:gitblame_highlight_group = "Question"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,
\ }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 = 0A list of filetypes for which gitblame information will not be displayed.
Default: []
let g:gitblame_ignored_filetypes = ['lua', 'c']The delay in milliseconds after which the blame info will be displayed.
Note that this doesn't affect the performance of the plugin.
Default: 250
let g:gitblame_delay = 1000 " 1 secondHave the blame message start at a given column instead of EOL. If the current line is longer than the specified column value the blame message will default to being displayed at EOL.
Default: v:null
let g:gitblame_virtual_text_column = 80If you are experiencing poor performance (e.g. in particularly large projects) you can use CursorHold and CursorHoldI instead of the default CursorMoved and CursorMovedI autocommands to limit the frequency of events being run.
g:gitblame_schedule_event is used for scheduling events. See CursorMoved and CursorHold.
Default: CursorMoved
options: CursorMoved|CursorHold
g:gitblame_clear_event is used for clearing virtual text. See CursorMovedI and CursorHoldI.
Default: CursorMovedI
options: CursorMovedI|CursorHoldI
By default the commands GitBlameOpenFileURL and GitBlameCopyFileURL open the current file at latest branch commit. If you would like to open these files at the latest blame commit (in other words, the commit marked by the blame), set this to true. For ranges, the blame selected will be the most recent blame from the range.
Default: false
vim.g.gitblame_use_blame_commit_file_urls = trueBy default the :GitBlameCopySHA, :GitBlameCopyFileURL and :GitBlameCopyCommitURL commands use the + register. Set this value if you would like to use a different register (such as *).
Default: +
let g:gitblame_clipboard_register = "*":GitBlameOpenCommitURL opens the commit URL of commit under the cursor.
Tested to work with GitHub and GitLab.
:GitBlameToggletoggles git blame on/off,:GitBlameEnableenables git blame messages,:GitBlameDisabledisables git blame messages.
:GitBlameCopySHA copies the SHA hash of current line's commit into
the system's clipboard.
:GitBlameCopyCommitURL copies the commit URL of current line's commit into
the system clipboard.
:GitBlameOpenFileURL opens the file in the default browser.
The URL is scoped to the latest commit on the current branch and
has a mark of the current line. (same is true for GitBlameCopyFileURL)
:GitBlameCopyFileURL copies the file URL into the system clipboard.
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 messageHere 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 }
}
}
})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'))- coc-git for some parts of code.
- blamer.nvim for documentation inspiration.
Special kudos to Sam Bossley for maintaining the plugin! <3
Made with contrib.rocks.
If you enjoy the plugin and want to support what I do
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent