[mini.git] Improving vertical git blame

[danielt812]

Hello! I wanted to share a recipe to improve the git blame experience when using a vertical split.

Credits:

• https://github.com/FabijanZulj/blame.nvim. I have been using this plugin since it was announced on reddit a few years ago.
• Discussion [mini.git] Better git blame #2029 by @drowning-cat , which I used as a starting point for this setup.

Explanation of some design choices:

Commit sha colors

Originally, I generated my palette by linking to existing highlight groups. After realizing I wanted the blame colors to differ more from my current colorscheme, I experimented with the colors on the front page of https://www.materialpalette.com/. However, I found that approach limiting because the number of highlight groups was fixed, and some colors didn’t provide enough contrast once the palette wrapped around the color wheel.

I ultimately decided to generate a random color palette which uses mini.colors to convert randomly generated HSL values to hex.

The palette is generated on each call. This could technically be moved outside the callback for marginal performance gains, but the overhead is negligible and keeping it local keeps the implementation simpler.

Using --porcelain output

One difference from the original discussion and the example provided in the help text is that this implementation uses the --porcelain flag (this is also how blame.nvim parses the blame data). The structured output makes it much easier to extract the blame information, simplifying setting highlights and creating keymaps that interact with the blame data.

Blame window/buffer behavior

To keep the cursor line aligned properly between the source buffer and the blame window, I chose to automatically close the blame window in certain situations using an autocmd. This acts as a workaround for plugins that modify the winbar (such as navic or dropbar), which can otherwise cause alignment issues. Wrapped lines can also break the alignment.

The blame buffer is rewritten from parsed data rather than partially hiding the raw blame output in the split window. This differs from the discussion and help text example, which display the default blame output directly. By using the --porcelain format, the blame data can be parsed and rendered into a custom layout, providing more control over formatting, highlights, and buffer keymaps that interact with the commit SHA hashes.

In my opinion, having the number column on the far left in the blame window provides a clearer mental model when glancing between the two buffers. I think it looks better (in my opinion).

Time formatting

With the help of blame.nvim source code, I included a small helper that can optionally format commit timestamps as relative time (EX: “3 days ago”).

This is entirely optional and can be removed if anyone prefers fewer lines of code or a simpler implementation.

Code

local git = require("mini.git")
local colors = require("mini.colors")

git.setup()

local blame = function() vim.cmd("vertical Git blame --porcelain -- %") end
vim.keymap.set("n", "<leader>gb", blame, { desc = "Blame" })

local group = vim.api.nvim_create_augroup("mini_git", { clear = true })

local gen_blame_palette = function(count)
  local dark = vim.o.background == "dark"
  local lightness = dark and 75 or 45
  local chroma = dark and 20 or 18
  local uv = vim.uv or vim.loop
  local offset = (uv.hrtime() % 360)
  local palette = {}
  for i = 1, count do
    -- Go to opposite side of color wheel so adjacent commits contrast more
    local hue = (offset + (i - 1) * 137.508) % 360
    palette[i] = colors.convert({ l = lightness, c = chroma, h = hue }, "hex")
  end
  return palette
end

local gen_hl_groups = function()
  vim.api.nvim_set_hl(0, "MiniGitBlameHash", { link = "Comment" })
  vim.api.nvim_set_hl(0, "MiniGitBlameUncommitted", { link = "Conceal" })
end

gen_hl_groups() -- Call this now if colorscheme was already set

vim.api.nvim_create_autocmd("ColorScheme", { pattern = "*", group = group, callback = gen_hl_groups })

local pad_right = function(str, width)
  local pad = width - vim.fn.strwidth(str)
  if pad <= 0 then return str end
  return str .. string.rep(" ", pad)
end

--- Format unix timestamp
---@param timestamp integer Unix timestamp (seconds since epoch)
---@param fmt string os.date format string (e.g. `"%Y-%m-%d"`)
---@param rel? boolean|integer true = always relative, N = relative within N days then fallback to fmt
---@return string
local format_time = function(timestamp, fmt, rel)
  if not rel then return tostring(os.date(fmt, timestamp)) end
  local diff = os.time() - timestamp
  local days = math.floor(diff / 86400)
  if type(rel) == "number" and days >= rel then return tostring(os.date(fmt, timestamp)) end
  local ago = function(n, unit) return n .. (n == 1 and " " .. unit .. " ago" or " " .. unit .. "s ago") end
  if diff < 60 then return ago(diff, "second") end
  if diff < 3600 then return ago(math.floor(diff / 60), "minute") end
  if diff < 86400 then return ago(math.floor(diff / 3600), "hour") end
  if diff < 2592000 then return ago(days, "day") end
  if diff < 31536000 then return ago(math.floor(diff / 2592000), "month") end
  return ago(math.floor(diff / 31536000), "year")
end

--- Format parsed blame data into display lines.
--- @param data {sha: string, sha_short: string, date: string, author: string}[]
--- @param skip_consecutive boolean? Replace consecutive lines with the same sha with "┃"
--- @return string[]
local format_blame = function(data, skip_consecutive)
  local max_date = 0
  for _, entry in ipairs(data) do
    if entry.author ~= "Not Committed Yet" then max_date = math.max(max_date, #entry.date) end
  end
  local formatted, prev_sha = {}, nil
  for _, entry in ipairs(data) do
    if skip_consecutive and entry.sha == prev_sha then
      table.insert(formatted, "┃")
    elseif entry.author == "Not Committed Yet" then
      table.insert(formatted, "Not Committed Yet")
    else
      table.insert(formatted, string.format("%s %s %s", entry.sha_short, pad_right(entry.date, max_date), entry.author))
    end
    prev_sha = entry.sha
  end
  return formatted
end

local parse_porcelain = function(lines)
  local commits, parsed = {}, {}
  local i = 1
  while i <= #lines do
    local sha, _, final = lines[i]:match("^(%x+) (%d+) (%d+)")
    if not sha then break end
    if not commits[sha] then
      commits[sha] = {}
      i = i + 1
      while i <= #lines and not lines[i]:match("^\t") do
        local key, val = lines[i]:match("^(%S+)%s?(.*)")
        if key then commits[sha][key] = val end
        i = i + 1
      end
    else
      i = i + 1
      while i <= #lines and not lines[i]:match("^\t") do
        i = i + 1
      end
    end
    local c = commits[sha]
    table.insert(parsed, {
      sha = sha,
      sha_short = sha:sub(1, 7),
      author = c.author or "",
      date = c["author-time"] and format_time(c["author-time"], "%Y-%m-%d", 10) or "",
      line = tonumber(final),
    })
    i = i + 1
  end
  return parsed
end

local blame_cb = function(event)
  if event.data.git_subcommand ~= "blame" or not event.data.cmd_input.mods:match("vertical") then return end
  vim.cmd("wincmd H")
  local win_src, buf, win = event.data.win_source, event.buf, event.data.win_stdout

  -- stylua: ignore
  local settings = { number = false, relativenumber = false, winbar = "", signcolumn = "no", cursorbind = true, scrollbind = true, wrap = false }
  local saved = {}
  for key, val in pairs(settings) do
    saved[key] = vim.wo[win_src][key]
    vim.wo[win][key] = val
    vim.wo[win_src][key] = val
  end

  local blame_data = parse_porcelain(vim.api.nvim_buf_get_lines(buf, 0, -1, false))
  local formatted = format_blame(blame_data, true)
  vim.api.nvim_buf_set_lines(buf, 0, -1, false, formatted)

  -- Highlights
  local ns = vim.api.nvim_create_namespace("mini_git_blame")
  local unique_shas, sha_colors, color_idx = {}, {}, 0
  for _, data in ipairs(blame_data) do
    if not unique_shas[data.sha] and data.author ~= "Not Committed Yet" then
      unique_shas[data.sha] = true
      color_idx = color_idx + 1
    end
  end
  local palette = gen_blame_palette(color_idx)
  color_idx = 0
  for i, data in ipairs(blame_data) do
    local ln = i - 1
    if not sha_colors[data.sha] and data.author ~= "Not Committed Yet" then
      color_idx = color_idx + 1
      sha_colors[data.sha] = color_idx
      local color = palette[color_idx]
      vim.api.nvim_set_hl(0, "MiniGitBlameDate" .. color_idx, { fg = color, italic = true })
      vim.api.nvim_set_hl(0, "MiniGitBlameAuthor" .. color_idx, { fg = color })
    end
    if data.author == "Not Committed Yet" then
      vim.api.nvim_buf_set_extmark(buf, ns, ln, 0, { end_col = #formatted[i], hl_group = "MiniGitBlameUncommitted" })
    elseif formatted[i] == "┃" then
      -- stylua: ignore
      vim.api.nvim_buf_set_extmark(buf, ns, ln, 0, { end_col = #formatted[i], hl_group = "MiniGitBlameDate" .. sha_colors[data.sha] })
    else
      local ci = sha_colors[data.sha]
      local sha_end = #data.sha_short
      local date_end = sha_end + 1 + #data.date
      -- stylua: ignore start
      vim.api.nvim_buf_set_extmark(buf, ns, ln, 0, { end_col = sha_end, hl_group = "MiniGitBlameHash" })
      vim.api.nvim_buf_set_extmark(buf, ns, ln, sha_end + 1, { end_col = date_end, hl_group = "MiniGitBlameDate" .. ci })
      vim.api.nvim_buf_set_extmark(buf, ns, ln, date_end + 1, { end_row = ln, end_col = #formatted[i], hl_group = "MiniGitBlameAuthor" .. ci })
      -- stylua: ignore end
    end
  end

  -- Blame window options
  vim.wo[win].number = true
  vim.wo[win].winfixwidth = true
  vim.wo[win].winfixbuf = true
  vim.bo[buf].bufhidden = "wipe"
  vim.bo[buf].modifiable = false

  vim.api.nvim_win_set_cursor(0, { vim.fn.line(".", win_src), 0 })
  vim.cmd("syncbind")

  -- Blame window width
  local max_len = 0
  for _, line in ipairs(formatted) do
    max_len = math.max(max_len, #line)
  end
  vim.api.nvim_win_set_width(win, max_len + math.max(vim.wo[win].numberwidth, #tostring(#formatted) + 1) + 2)

  -- Buffer keymaps
  local get_entry = function() return blame_data[vim.api.nvim_win_get_cursor(win)[1]] end
  local map = function(key, fn, desc) vim.keymap.set("n", key, fn, { buffer = buf, desc = desc }) end
  local with_commit = function(fn)
    local entry = get_entry()
    if entry and entry.author ~= "Not Committed Yet" then fn(entry.sha) end
  end

  -- stylua: ignore start
  local checkout = function() with_commit(function(sha) vim.cmd("Git checkout " .. sha) end) end
  local diff     = function() with_commit(function(sha) vim.cmd("Git diff " .. sha .. "^ " .. sha) end) end
  local files    = function() with_commit(function(sha) vim.cmd("Git show --name-status --format=fuller " .. sha) end) end
  local show     = function() with_commit(function(sha) vim.cmd("Git show " .. sha) end) end
  local stat     = function() with_commit(function(sha) vim.cmd("Git show --stat --summary --format=fuller " .. sha) end) end
  local yank     = function() with_commit(function(sha) vim.fn.setreg("+", sha) vim.notify("Yanked commit " .. sha) end) end

  map("c", checkout, "Checkout commit")
  map("d", diff,     "Diff commit")
  map("f", files,    "Show files in commit")
  map("s", show,     "Show commit")
  map("t", stat,     "Show commit stats")
  map("y", yank,     "Yank sha")
  -- stylua: ignore end

  local close = function()
    if vim.api.nvim_win_is_valid(win_src) then
      -- stylua: ignore
      for opt, val in pairs(saved) do vim.wo[win_src][opt] = val end
    end
    if vim.api.nvim_win_is_valid(win) then vim.api.nvim_win_close(win, true) end
  end

  map("q", close, "Close blame")
  map("<esc>", close, "Close blame")

  -- stylua: ignore
  vim.api.nvim_create_autocmd({ "WinLeave", "BufWipeout" }, { buffer = buf, once = true, callback = close })
end

vim.api.nvim_create_autocmd("User", { pattern = "MiniGitCommandSplit", group = group, callback = blame_cb })

[echasnovski]

Thanks for sharing!

Didn't look very closely into the code (made it hidden behind the spoiler, by the way). Have a feeling it might be simplified a bit. But if it works, it works :) I like the vertical "scope" lines.

I have couple of questions about gen_blame_palette():

• Do you really like the idea to have a random offset? Having colors always be random here seems like a missed opportunity to use them to convey something useful. Like "red - more recent; green - not so recent; etc.".
• Using golden angle to generate palette is a nice touch. Although I think picking colors to simply be equidistant on the hue wheel (from 0 to 360) can be better. Might require deciding the order in which to show them (for higher contrast) or use that information to convey the age of the commit relative to other commits.

[danielt812]

Didn't look very closely into the code (made it hidden behind the spoiler, by the way)

No worries. I realized it was a fairly big code block when I posted it. I didn’t know how to make a spoiler, but I can see how you did it now.

Do you really like the idea to have a random offset? Having colors always be random here seems like a missed opportunity to use them to convey something useful. Like "red - more recent; green - not so recent; etc.".

The reason I chose random colors was familiarity. I've been using blame.nvim for a few years, and I also used its source code for guidance. It approaches color palette generation similarly, except that it uses RGB. I went with HSL because it made it easy to adjust saturation depending on whether vim.o.background is light or dark. I only use dark mode personally, but I wanted to try supporting both out of curiosity.

I always thought the random colors were useful because they let you visually group changes from the same commit. That said, your suggestion is interesting too.

Using golden angle to generate palette is a nice touch. Although I think picking colors to simply be equidistant on the hue wheel (from 0 to 360) can be better. Might require deciding the order in which to show them (for higher contrast) or use that information to convey the age of the commit relative to other commits.

I actually tried that approach at first since the implementation was more straightforward, but I didn’t like the result because it made adjacent commits harder to visually distinguish. That said, I was only using it to generate distinct colors, not with the intention of conveying useful meaning like you suggested.