Enable attach() to work with any buffer given the necessary context data

[sindrets]

Could we extend the gitsigns.attach() function to allow for attaching to any arbitrary buffer given the necessary git context data? This would allow plugins to utilize gitsigns to attach to any buffer that represents a real git object.

The motivation for this is that - from time to time - users ask about the possibility to show inline diffs in diffview.nvim. I figured that using gitsigns with toggle_linehl and toggle_deleted is perfect for this. Except that currently I can only do this with the current, working tree version of a file (and fugitive buffers).

Instead of giving gitsigns the capability to parse diffview URI's, I figured it would be a lot more extensible to extend the attach() function such that callers can optionally give it information about:

• What file the buffer represents.
• The top-level of it's parent git repository.
• The path to the git dir.
• The revision it belongs to (i.e. a commit SHA).
• The base revision it should be diffed against.

Imagined API

---@param bufnr integer # Buffer number
---@param ctx GitContext
function gitsigns.attach(bufnr, ctx) --[[ ... ]] end

---@class GitContext
---@field toplevel string # Path to the top-level of the repository
---@field gitdir string # Path to the git dir
---@field file string # Path to the file represented by the buffer
---@field commit string # Git revision the file belongs to
---@field base string # Git revision the file should be diffed against

-- Works the same as before when only given a bufnr
gitsigns.attach(12)

-- When given, gitsigns will try to attach to the buffer using the context
-- data, instead of deriving this from the buffer name / path.
gitsigns.attach(12, {
  toplevel = "/path/to/toplevel",
  gitdir = "/path/to/toplevel/.git",
  file = "path/to/file.txt",
  commit = "d076301",
  base = "a4e2275",
})

Is this something you'd be willing to include? If so, I can work on a PR.

[lewis6991]

It's an interesting idea. I'd review a PR.