Description

It shouldn't be too hard to imagine that Neovim users would like to write Lua functions to do some custom shenanigans which they want in their ideal workflow. It's always nice when plugins come with batteries included (e.g. gitsigns.blame_line()) which are preconfigured, already have nice "GUI", mappings, etc., but I find it equally (if not more) important for a plugin to provide "building blocks" which will allow users to efficiently/conveniently use plugin to make their own desired environment. In my attempt (#1030) to make such atypical behavior, I found lack of trivial blaming capabilities (among other things) really inconvenient.

Problem

Unfortunately, gitsigns.blame_line() seems to be the only Lua API available for getting the SHA of blamed line.
Issues:

• It doesn't just return blamed line as a string, but it opens a popup window which has it.
• It's asynchronous (but at least accepts "then" callback for chaining operations).

Because of these, the only way to extract blamed commit SHA via Gitsigns is the following:

-- Open popup window with commit of blamed line.
gitsigns.blame_line(
    { full = false },
    function()
        -- In order to focus opened popup window, blame_line needs to be called again.
        gitsigns.blame_line(
            {},
            function()
                -- Now that popup is focused, extract commit SHA from the start of it.
                local blamed_commit = vim.fn.getline(1):match("^(%x+)")

                -- Close the focused popup.
                vim.cmd(":quit")

                -- Rest of the code that has to be executed synchronously after blamed commit is extracted.
            end)
    end)

The above code is way too ugly and complex just for requesting something that Gitsigns:

• Already has to compute internally.
• Can return as a plain string.
• Can return synchronously and drastically simplify the user code.

Proposal

Expose simple Lua API function (e.g. get_blame_line()) which will synchronously return blamed line for opened file snapshot.
It can accept same parameters as blame_line() and return either whole string of blamed line as git would output it, or some more refined table with separated commit, author, date and line strings.

With this, ugly code from above becomes (depending on the return type):

local blamed_commit = gitsigns.get_blame_line({ full = false }):match("^(%x+)")
-- Rest of the code that has to be executed synchronously after blamed commit is extracted.

or

local blamed_commit = gitsigns.get_blame_line({ full = false }).commit
-- Rest of the code that has to be executed synchronously after blamed commit is extracted.

Rationale

• Gitsigns already has this capability implemented and much more on top of it. It just needs to refactor/expose it.
• Gitsigns may (already) cache this data, so it's bound to be better supported and more efficient than average implementation from custom user (if they don't want to use gitsigns.blame_line(), which is IMHO fully justified).