motiejus/dotfiles

commit d6edaf7a4de03a17266bc83bb0cfe2af16c3de91 (tree)
parent af5ba43aa393c63981a71e97338baec434e77a83
Author: Tim Pope <code@tpope.net>
Date:   Sat, 24 Jul 2021 08:35:09 -0400

Document autocommands

Diffstat:
M
doc/fugitive.txt
 | 
39
+++++++++++++++++++++++++++++++++++++++
M
plugin/fugitive.vim
 | 
8
+++++---

2 files changed, 44 insertions(+), 3 deletions(-)
diff --git a/doc/fugitive.txt b/doc/fugitive.txt
@@ -601,6 +601,37 @@ a statusline, this one matches the default when 'ruler' is set:
 >
         set statusline=%<%f\ %h%m%r%{FugitiveStatusline()}%=%-14.(%l,%c%V%)\ %P
 <
+AUTOCOMMANDS                                    *fugitive-autocommands*
+
+A handful of |User| |autocommands| are provided to allow extending and
+overriding Fugitive behaviors.  Example usage:
+>
+        autocmd User FugitiveBlob call s:BlobOverrides()
+<
+                                                *User_FugitiveIndex*
+FugitiveIndex           After loading the |fugitive-summary| buffer.
+
+                                                *User_FugitiveTag*
+FugitiveTag             After loading a tag object.
+
+                                                *User_FugitiveCommit*
+FugitiveCommit          After loading a commit object.
+
+                                                *User_FugitiveTree*
+FugitiveTree            After loading a tree (directory) object.
+
+                                                *User_FugitiveBlob*
+FugitiveBlob            After loading a blob (file) object.  This includes
+                        both committed blobs which are read only, and staged
+                        blobs which can be edited and written.  Check
+                        &modifiable to distinguish between the two.
+
+                                                *User_FugitiveChanged*
+FugitiveChanged         After any event which can potentially change the
+                        repository, for example, any invocation of |:Git|.
+                        Originally intended for expiring caches, but can have
+                        other uses.
+
 API                                             *fugitive-api*
 
 Officially supported functions are documented inline in plugin/fugitive.vim.
@@ -636,6 +667,14 @@ version.
 *:Gtabsplit!*   Superseded by :tab Git --paginate.
 *:Gpedit!*      Superseded by :Git! --paginate.
 
+                                                *User_Fugitive*
+Fugitive used to support `:autocmd User Fugitive` to run an autocommand after
+loading any buffer belonging to a Git repository, but this is being phased
+out.  Instead, one can leverage regular autocommand events like |BufNewFile|
+and |BufReadPost|, and check !empty(FugitiveGitDir()) to confirm Fugitive has
+found a repository.  See also |fugitive-autocommands| for other, more
+selective events.
+
 ABOUT                                           *fugitive-about*
 
 Grab the latest version or report a bug on GitHub:
diff --git a/plugin/fugitive.vim b/plugin/fugitive.vim
@@ -99,9 +99,11 @@ function! FugitiveParse(...) abort
 endfunction
 
 " FugitiveResult() returns an object encapsulating the result of the most
-" recend :Git command.  Will be empty if no result is available.  Pass in the
-" name of a temp buffer to get the result object for that command instead.
-" Contains the following keys:
+" recent :Git command.  Will be empty if no result is available.  During a
+" User FugitiveChanged event, this is guaranteed to correspond to the :Git
+" command that triggered the event, or be empty if :Git was not the trigger.
+" Pass in the name of a temp buffer to get the result object for that command
+" instead.  Contains the following keys:
 "
 " * "args": List of command arguments, starting with the subcommand.  Will be
 "   empty for usages like :Git --help.