refactor(git): introduce Revision class, normalize naming, slim docs

lua/git/editor.lua

@@ -4,11 +4,6 @@ local M = {}
 
 local SENTINEL = "__NVIM_GIT_EDIT__"
 
--- Per-invocation: each `sh -c` body picks a flag file via `$$`,
--- prints sentinel + flag-path + abs-path on stderr, then polls the
--- flag until Neovim writes it. `rebase -i` fires the editor many
--- times (todo + each reword). Each call is a fresh shell with a
--- fresh `$$`, so flags don't collide.
 local SCRIPT = string.format(
     [=[set -eu
 flag="${TMPDIR:-/tmp}/nvim-git-editor-$$.done"
@@ -22,7 +17,6 @@ done
     SENTINEL
 )
 
----POSIX shell single-quote escape: foo'bar -> 'foo'\''bar'.
 ---@param s string
 ---@return string
 local function shq(s)
@@ -31,11 +25,6 @@ end
 
 local GIT_EDITOR = "sh -c " .. shq(SCRIPT) .. " --"
 
----Build a stderr callback that strips our sentinel lines, accumulates
----the rest, and dispatches `on_open(abs, done)` for each sentinel seen.
----The `finalize(result)` helper drains any trailing partial line into
----`result.stderr` so the caller can treat `result` like a plain
----`vim.system` result.
 ---@param on_open fun(file_path: string, done: fun())
 ---@return fun(err: string?, data: string?), fun(result: vim.SystemCompleted)
 local function build_stderr_handler(on_open)
@@ -97,17 +86,6 @@ local function build_stderr_handler(on_open)
     return on_stderr, finalize
 end
 
----Run a git command with an editor proxy active. When git invokes the
----editor, `on_open` fires with the absolute file path git wants edited
----plus a `done` callback. The caller opens the file in a buffer and
----invokes `done()` once the user is finished (typically from a
----`BufWipeout` autocmd). For commands that fire the editor more than
----once in a single git invocation (`git rebase -i`, with one call for
----the todo and one per `reword`), `on_open` is invoked once per
----editor handoff.
----
----`on_exit` is called on the main loop with a `vim.SystemCompleted`-
----shaped result. `result.stderr` has our protocol sentinels stripped.
 ---@param cmd string[]
 ---@param opts? { cwd?: string, env?: table<string,string> }
 ---@param on_open fun(file_path: string, done: fun())