blame.nvim is a fugitive.vim style git blame visualizer for Neovim.

Window:

Virtual:

Same commits are highlighted in the same color

{
  "FabijanZulj/blame.nvim",
  config = function()
    require("blame").setup()
  end
}

setup() must be called

The following commands are used:

• BlameToggle [view] - Toggle the blame with provided view. If no view is provided it opens the default (window) view

There are two built-in views:

• window - fugitive style window to the left of the current window
• virtual - blame shown in a virtual text floated to the right

Default config:

{
    date_format = "%d.%m.%Y",
    virtual_style = "right",
    views = {
        window = window_view,
        virtual = virtual_view,
        default = window_view,
    },
    merge_consecutive = false,
    max_summary_width = 30,
    colors = nil,
    commit_detail_view = "vsplit",
    format_fn = formats.commit_date_author_fn,
    mappings = {
        commit_info = "i",
        stack_push = "<TAB>",
        stack_pop = "<BS>",
        show_commit = "<CR>",
        close = { "<esc>", "q" },
    }
}

These are the fields you can configure by passing them to the require('blame').setup({}) function:

• date_format - string - Pattern for the date
• virtual_style - "right_align" or "float" - Float moves the virtual text close to the content of the file.
• views - views that can be used when toggling blame
• merge_consecutive - boolean - Merge consecutive blames that are from the same commit
• max_summary_width - If date_message is used, cut the summary if it excedes this number of characters
• colors - list of RGB strings to use instead of randomly generated RGBs for highlights
• commit_detail_view - string - "tab"|"split"|"vsplit"|"current" - Open commit details in a new tab, split, vsplit or current buffer
• format_fn - format function that is used for processing of porcelain lines. See below for details ( built-in: ("blame.formats.default_formats").date_message and ("blame.formats.default_formats").commit_date_author_fn )
• mappings - custom mappings for various actions, you can pass in single or multiple mappings for an action.

You can see the state of the file prior to selected commit using stack_push(default: <TAB>) and stack_pop (default: <BS>) mappings. In the pop-up on the right the stack is shown and you can go back and forward through the history of the file.

To see the full commit info pop-up press the commit_info(default: 'i') mapping on the specific commit line. (press i again to move into the popup window, or move cursor to close the popup)

Details

To see the full commit data press the show_commit(default <CR>) mapping on the commit line

Details

You can provide custom format functions that get executed for every blame line and are shown in a view. By default highlight is created for each commit hash so it can be used in hl field.

Signature of the function:

FormatFn fun(line_porcelain: Porcelain, config:Config, idx:integer):LineWithHl

where LineWithHl is:

---@class LineWithHl
---@field idx integer
---@field values {textValue: string, hl: string}[]
---@field format string

And Porcelain being:

---@class Porcelain
---@field author string
---@field author_email string
---@field author_time number
---@field author_tz string
---@field committer string
---@field committer_mail string
---@field committer_time number
---@field committer_tz string
---@field filename string
---@field hash string
---@field previous string
---@field summary string
---@field content string

Built in format functions are:

("blame.formats.default_formats").date_message

• {commit date} {summary}

("blame.formats.default_formats").commit_date_author_fn

• {commit hash} {commit date} {author}

Your function must return a list of values ({textValue: string, hl: string}). Those text fragments will be formatted with provided format field and highlighted with the HiglightGroup given in hl

for more info check the implementations for 'date_message' or 'commit_date_author_fn'

It is also possible to implement your custom view. To implement a custom view you need to implement this interface:

---@class BlameView
---@field new fun(self, config: Config) : BlameView
---@field open fun(self, lines: Porcelain[])
---@field is_open fun(): boolean
---@field close fun(cleanup: boolean)

And add it to the config field table views See 'blame.views.window_view' and 'blame.views.virtual_view' for examples

These user events are emitted

• BlameViewOpened
• BlameViewClosed

So you can do something like this: there are some conflicts with some winbar plugins, in this case barbecue is toggled

vim.api.nvim_create_autocmd("User", {
    pattern = "BlameViewOpened",
    callback = function(event)
        local blame_type = event.data
        if blame_type == "window" then
            require("barbecue.ui").toggle(false)
        end
    end,
})

vim.api.nvim_create_autocmd("User", {
    pattern = "BlameViewClosed",
    callback = function(event)
        local blame_type = event.data
        if blame_type == "window" then
            require("barbecue.ui").toggle(true)
        end
    end,
})