feat(actions): add callback to async actions

- simplify async code

Fixes: #906, #766

doc/gitsigns.txt

@@ -86,11 +86,11 @@ Most actions can be repeated with `.` if you have |vim-repeat| installed.
 ==============================================================================
 FUNCTIONS                                                 *gitsigns-functions*
 
-Note functions with the {async} attribute are run asynchronously and are
-non-blocking (return immediately).
+Note functions with the {async} attribute are run asynchronously and accept
+an optional {callback} argument.
 
 
-setup({cfg})                                                *gitsigns.setup()*
+setup({cfg}, {callback?})                                   *gitsigns.setup()*
                 Setup and start Gitsigns.
 
                 Attributes: ~
@@ -100,7 +100,7 @@ setup({cfg})                                                *gitsigns.setup()*
                     {cfg} (table|nil): Configuration for Gitsigns.
                           See |gitsigns-usage| for more details.
 
-attach({bufnr}, {ctx})                                     *gitsigns.attach()*
+attach({bufnr}, {ctx}, {callback?})                        *gitsigns.attach()*
                 Attach Gitsigns to the buffer.
 
                 Attributes: ~
@@ -163,7 +163,7 @@ setloclist({nr}, {target})                             *gitsigns.setloclist()*
                              `0` for the current window (default).
                     {target} (integer|string): See |gitsigns.setqflist()|.
 
-setqflist({target}, {opts})                             *gitsigns.setqflist()*
+setqflist({target}, {opts}, {callback?})                *gitsigns.setqflist()*
                 Populate the quickfix list with hunks. Automatically opens the
                 quickfix window.
 
@@ -251,7 +251,7 @@ reset_base({global})                                   *gitsigns.reset_base()*
 
                 Alias for `change_base(nil, {global})` .
 
-change_base({base}, {global})                         *gitsigns.change_base()*
+change_base({base}, {global}, {callback?})              *gitsigns.change_base()*
                 Change the base revision to diff against. If {base} is not
                 given, then the original base is used. If {global} is given
                 and true, then change the base revision of all buffers,
@@ -286,7 +286,7 @@ change_base({base}, {global})                         *gitsigns.change_base()*
                     {base}   (string|nil): The object/revision to diff against.
                     {global} (boolean|nil): Change the base of all buffers.
 
-blame_line({opts})                                     *gitsigns.blame_line()*
+blame_line({opts}, {callback?})                        *gitsigns.blame_line()*
                 Run git blame on the current line and show the results in a
                 floating window. If already open, calling this will cause the
                 window to get focus.
@@ -335,19 +335,25 @@ preview_hunk()                                       *gitsigns.preview_hunk()*
                 window. If the preview is already open, calling this
                 will cause the window to get focus.
 
-prev_hunk({opts})                                       *gitsigns.prev_hunk()*
+prev_hunk({opts}, {callback?})                          *gitsigns.prev_hunk()*
                 Jump to the previous hunk in the current buffer. If a hunk preview
                 (popup or inline) was previously opened, it will be re-opened
                 at the previous hunk.
 
+                Attributes: ~
+                    {async}
+
                 Parameters: ~
                     See |gitsigns.next_hunk()|.
 
-next_hunk({opts})                                       *gitsigns.next_hunk()*
+next_hunk({opts}, {callback?})                          *gitsigns.next_hunk()*
                 Jump to the next hunk in the current buffer. If a hunk preview
                 (popup or inline) was previously opened, it will be re-opened
                 at the next hunk.
 
+                Attributes: ~
+                    {async}
+
                 Parameters: ~
                     {opts} (table|nil): Configuration table. Keys:
                            • {wrap}: (boolean)
@@ -393,7 +399,7 @@ undo_stage_hunk()                                 *gitsigns.undo_stage_hunk()*
 reset_buffer()                                       *gitsigns.reset_buffer()*
                 Reset the lines of all hunks in the buffer.
 
-reset_hunk({range}, {opts})                            *gitsigns.reset_hunk()*
+reset_hunk({range}, {opts}, {callback?})               *gitsigns.reset_hunk()*
                 Reset the lines of the hunk at the cursor position, or all
                 lines in the given range. If {range} is provided, all lines in
                 the given range are reset. This supports partial-hunks,
@@ -410,7 +416,7 @@ reset_hunk({range}, {opts})                            *gitsigns.reset_hunk()*
                               Stage all contiguous hunks. Only useful if 'diff_opts'
                               contains `linematch`. Defaults to `true`.
 
-stage_hunk({range}, {opts})                            *gitsigns.stage_hunk()*
+stage_hunk({range}, {opts}, {callback?})               *gitsigns.stage_hunk()*
                 Stage the hunk at the cursor position, or all lines in the
                 given range. If {range} is provided, all lines in the given
                 range are staged. This supports partial-hunks, meaning if a

etc/doc_template.txt

@@ -47,8 +47,8 @@ Most actions can be repeated with `.` if you have |vim-repeat| installed.
 ==============================================================================
 FUNCTIONS                                                 *gitsigns-functions*
 
-Note functions with the {async} attribute are run asynchronously and are
-non-blocking (return immediately).
+Note functions with the {async} attribute are run asynchronously and accept
+an optional {callback} argument.
 
 
 {{FUNCTIONS}}

gen_help.lua

@@ -95,8 +95,9 @@ local function gen_config_doc_field(field, out)
 
   if v.description then
     local d --- @type string
-    if v.default_help ~= nil then
-      d = v.default_help
+    local default_help = v.default_help
+    if default_help ~= nil then
+      d = default_help
     else
       d = inspect(v.default):gsub('\n', '\n    ')
       d = ('`%s`'):format(d)
@@ -160,6 +161,11 @@ local function parse_func_header(line)
       args[#args + 1] = string.format('{%s}', k)
     end
   end
+
+  if line:match('async.create%(%d, function%(') then
+    args[#args + 1] = '{callback?}'
+  end
+
   return string.format(
     '%-40s%38s',
     string.format('%s(%s)', func, table.concat(args, ', ')),
@@ -486,6 +492,7 @@ local function main()
         if type(sub) == 'function' then
           sub = sub()
         end
+        --- @type string
         sub = sub:gsub('%%', '%%%%')
         l = l:gsub('{{' .. marker .. '}}', sub)
       end

lua/gitsigns.lua

@@ -8,13 +8,14 @@ local dprintf = log.dprintf
 local dprint = log.dprint
 
 local api = vim.api
-local uv = vim.loop
+local uv = vim.uv or vim.loop
 
 local M = {}
 
 local cwd_watcher ---@type uv.uv_fs_event_t?
 
-local update_cwd_head = async.void(function()
+--- @async
+local function update_cwd_head()
   local paths = vim.fs.find('.git', {
     limit = 1,
     upward = true,
@@ -31,7 +32,7 @@ local update_cwd_head = async.void(function()
     cwd_watcher = assert(uv.new_fs_event())
   end
 
-  local cwd = assert(vim.loop.cwd())
+  local cwd = assert(uv.cwd())
   --- @type string, string
   local gitdir, head
 
@@ -73,7 +74,7 @@ local update_cwd_head = async.void(function()
 
   local update_head = debounce_trailing(
     100,
-    async.void(function()
+    async.create(function()
       local new_head = git.get_repo_info(cwd).abbrev_head
       async.scheduler()
       vim.g.gitsigns_head = new_head
@@ -84,7 +85,7 @@ local update_cwd_head = async.void(function()
   cwd_watcher:start(
     towatch,
     {},
-    async.void(function(err)
+    async.create(function(err)
       local __FUNC__ = 'cwd_watcher_cb'
       if err then
         dprintf('Git dir update error: %s', err)
@@ -95,7 +96,7 @@ local update_cwd_head = async.void(function()
       update_head()
     end)
   )
-end)
+end
 
 local function setup_cli()
   api.nvim_create_user_command('Gitsigns', function(params)
@@ -132,7 +133,7 @@ local function setup_attach()
       -- Make sure to run each attach in its on async context in case one of the
       -- attaches is aborted.
       local attach = require('gitsigns.attach')
-      async.run(attach.attach, buf, nil, 'setup')
+      attach.attach(buf, nil, 'setup')
     end
   end
 end
@@ -141,13 +142,16 @@ end
 local function setup_cwd_head()
   async.scheduler()
   update_cwd_head()
+
+  local debounce = require('gitsigns.debounce').debounce_trailing
+  local update_cwd_head_debounced = debounce(100, async.create(update_cwd_head))
+
   -- Need to debounce in case some plugin changes the cwd too often
   -- (like vim-grepper)
   api.nvim_create_autocmd('DirChanged', {
     group = 'gitsigns',
     callback = function()
-      local debounce = require('gitsigns.debounce').debounce_trailing
-      debounce(100, update_cwd_head)
+      update_cwd_head_debounced()
     end,
   })
 end
@@ -159,7 +163,7 @@ end
 ---
 --- @param cfg table|nil Configuration for Gitsigns.
 ---     See |gitsigns-usage| for more details.
-M.setup = async.void(function(cfg)
+M.setup = async.create(1, function(cfg)
   gs_config.build(cfg)
 
   if vim.fn.executable('git') == 0 then