feat: issue GitsignsUpdate event when appropriate (#641)

Co-authored-by: Lewis Russell <me@lewisr.dev>

doc/gitsigns.txt

@@ -975,5 +975,19 @@ Since text objects are defined via keymaps, these are exposed and configurable
 via the config, see |gitsigns-config-keymaps|. The lua implementation is
 exposed through |gitsigns.select_hunk()|.
 
+==============================================================================
+EVENT                                                         *gitsigns-event*
+
+Every time Gitsigns updates its knowledge about hunks, it issues a custom
+|User| event named `GitSignsUpdate`. You can use it via usual autocommands,
+like so: >
+
+    vim.api.nvim_create_autocmd('User', {
+      pattern = 'GitSignsUpdate',
+      callback = function()
+        print(os.time() .. ' Gitsigns made an update')
+      end
+    })
+
 ------------------------------------------------------------------------------
 vim:tw=78:ts=8:ft=help:norl:

lua/gitsigns/manager.lua

@@ -10,6 +10,8 @@ local Signs = require('gitsigns.signs')
 
 local Status = require("gitsigns.status")
 
+local nvim = require('gitsigns.nvim')
+
 local debounce_trailing = require('gitsigns.debounce').debounce_trailing
 local throttle_by_id = require('gitsigns.debounce').throttle_by_id
 local gs_debug = require("gitsigns.debug")
@@ -267,6 +269,11 @@ M.update = throttle_by_id(function(bufnr, bcache)
 
       show_deleted(bufnr)
       bcache.force_next_update = false
+
+      nvim.doautocmd('User', {
+         pattern = 'GitSignsUpdate',
+         modeline = false,
+      })
    end
    local summary = gs_hunks.get_summary(bcache.hunks)
    summary.head = git_obj.repo.abbrev_head

lua/gitsigns/nvim.lua

@@ -3,6 +3,7 @@ local api = vim.api
 local lookups = {
    autocmd = "autocmds",
    augroup = "autocmds",
+   doautocmd = "autocmds",
    highlight = "highlights",
    command = "command",
 }
@@ -14,6 +15,7 @@ local NvimModule = {}
 
 
 
+
 return setmetatable(NvimModule, {
    __index = function(t, k)
       local modname = lookups[k]

lua/gitsigns/nvim/autocmds.lua

@@ -12,4 +12,8 @@ function M.augroup(name, opts)
    vim.api.nvim_create_augroup(name, opts or {})
 end
 
+function M.doautocmd(event, opts)
+   vim.api.nvim_exec_autocmds(event, opts or {})
+end
+
 return M

lua/gitsigns/nvim/autocmds_compat.lua

@@ -34,4 +34,15 @@ function M.augroup(name, opts)
    cmd("augroup END")
 end
 
+function M.doautocmd(event, opts)
+   opts = opts or {}
+
+   cmd(table.concat({
+      "doautocmd",
+      not opts.modeline and "<nomodeline>" or "",
+      flatten(event),
+      flatten(opts.pattern),
+   }, " "))
+end
+
 return M

teal/gitsigns/manager.tl

@@ -10,6 +10,8 @@ local Signs             = require('gitsigns.signs')
 
 local Status            = require("gitsigns.status")
 
+local nvim = require('gitsigns.nvim')
+
 local debounce_trailing = require('gitsigns.debounce').debounce_trailing
 local throttle_by_id    = require('gitsigns.debounce').throttle_by_id
 local gs_debug          = require("gitsigns.debug")
@@ -267,6 +269,11 @@ M.update = throttle_by_id(function(bufnr: integer, bcache: CacheEntry)
 
     show_deleted(bufnr)
     bcache.force_next_update = false
+
+    nvim.doautocmd('User', {
+      pattern = 'GitSignsUpdate',
+      modeline = false,
+    })
   end
   local summary = gs_hunks.get_summary(bcache.hunks)
   summary.head = git_obj.repo.abbrev_head

teal/gitsigns/nvim.tl

@@ -3,6 +3,7 @@ local api = vim.api
 local lookups: {string:string} = {
   autocmd = "autocmds",
   augroup = "autocmds",
+  doautocmd = "autocmds",
   highlight = "highlights",
   command = "command",
 }
@@ -10,6 +11,7 @@ local lookups: {string:string} = {
 local record NvimModule
   augroup: function(string, api.AugroupOpts)
   autocmd: function(string|{string}, api.AutoCmdOpts)
+  doautocmd: function(string|{string}, api.ExecAutoCmdOpts)
   highlight: function(string, {string:any})
   command: function(name: string, fn: function(api.UserCmdParams), opts: api.UserCmdOpts)
 end

teal/gitsigns/nvim/autocmds.tl

@@ -12,4 +12,8 @@ function M.augroup(name: string, opts: vim.api.AugroupOpts)
   vim.api.nvim_create_augroup(name, opts or {})
 end
 
+function M.doautocmd(event: string|{string}, opts: vim.api.ExecAutoCmdOpts)
+  vim.api.nvim_exec_autocmds(event, opts or {})
+end
+
 return M

teal/gitsigns/nvim/autocmds_compat.tl

@@ -34,4 +34,15 @@ function M.augroup(name: string, opts: vim.api.AugroupOpts)
   cmd "augroup END"
 end
 
+function M.doautocmd(event: string|{string}, opts: vim.api.ExecAutoCmdOpts)
+  opts = opts or {}
+
+  cmd(table.concat({
+    "doautocmd",
+    not opts.modeline and "<nomodeline>" or "",
+    flatten(event),
+    flatten(opts.pattern)
+  }, " "))
+end
+
 return M

types/types.d.tl

@@ -149,6 +149,16 @@ local record api
   nvim_err_writeln: function(string)
   nvim_eval: function(string): any
   nvim_exec: function(string, boolean): string
+
+  record ExecAutoCmdOpts
+    group: string|integer
+    pattern: string|{string}
+    buffer: integer
+    modeline: boolean
+    data: any
+  end
+
+  nvim_exec_autocmds: function(string|{string}, ExecAutoCmdOpts): any
   nvim_exec_lua: function(string, any): any
   nvim_feedkeys: function(string, string, boolean)
   nvim_get_api_info: function(): any