plugin/magit.vim: raise autocmd events at some magit moments (fix #70)

plug gitgutter refresh to this event
also, make it possible to disable gitgutter auto refresh with g:magit_refresh_gitgutter

add relative help to autocmd events and gitgutter disable variable

README.md

@@ -218,6 +218,47 @@ Following mappings are set locally, for magit buffer only, in normal mode.
 ##### h
  * Toggle help showing in magit buffer
 
+#### Autocommand events
+
+Magit will raise some events at some point. User can plug some specific
+commands to these events (see [example](autocommand_example).
+
+##### VimagitBufferInit
+
+This event is raised when the magit buffer is initialized (i.e. each time
+[magit#show_magit()](magitshow_magit) is called.
+
+#### VimagitRefresh
+
+This event is raised every time the magit buffer is refreshed, event if no
+file is updated.
+
+#### VimagitUpdateFile
+
+This event is raised each time a file status is updated in magit buffer
+(typically when a file or a hunk is staged or unstaged). The variable
+`g:magit_last_updated_buffer` is set to the last updated file, with its
+absolute path.
+
+*Note:* `g:magit_last_updated_buffer` will be updated and VimagitUpdateFile event will
+be raised only if the buffer is currently opened in vim.
+
+#### Autocmd example
+
+The following example calls the vim-gitgutter refresh function on a specific
+buffer each time vimagit update the git status of this file.
+
+```
+  autocmd User VimagitUpdateFile
+    \ if ( exists("*gitgutter#process_buffer") ) |
+    \ 	call gitgutter#process_buffer(bufnr(g:magit_last_updated_buffer), 0) |
+    \ endif
+```
+
+The following example is already embeded in vimagit plugin (see
+[g:magit_refresh_gitgutter](gmagit_refresh_gitgutter)), then you shouldn't add this particular
+example to your vimrc.
+
 ### Options
 
 User can define in its prefered |vimrc| some options.
@@ -274,6 +315,14 @@ When set to 1, discard an untracked file will indeed delete this file.
 Default value is 0.
 > let g:magit_discard_untracked_do_delete=[01]
 
+#### g:magit_refresh_gitgutter
+
+When set to 1, and if vim-gitgutter plugin is installed, gitgutter signs will
+be updated each time magit update the git status of a file (i.e. when a file
+or a hunk is staged/unstaged).
+Default value is 1.
+> let g:magit_refresh_gitgutter=[01]
+
 ## Installation
 
 The plugin hierarchy tree respects the vim plugin standard. It is compatible

doc/vimagit.txt

@@ -257,6 +257,45 @@ Following mappings are set locally, for magit buffer only, in normal mode.
                                     *vimagit-g:magit_toggle_help_mapping*
   h         Toggle help showing in magit buffer
 
+AUTOCMD                                                        *vimagit-autocmd*
+
+Magit will raise some events at some point. User can plug some specific
+commands to these events (see |vimagit-autocmd_example|).
+
+VimagitBufferInit                                    *vimagit-VimagitBufferInit*
+
+This event is raised when the magit buffer is initialized (i.e. each time
+|magit#show_magit()| is called.
+
+VimagitRefresh                                          *vimagit-VimagitRefresh*
+
+This event is raised every time the magit buffer is refreshed, event if no
+file is updated.
+
+VimagitUpdateFile                                    *vimagit-VimagitUpdateFile*
+
+This event is raised each time a file status is updated in magit buffer
+(typically when a file or a hunk is staged or unstaged). The variable
+|g:magit_last_updated_buffer| is set to the last updated file, with its
+absolute path.
+
+Note: |g:magit_last_updated_buffer| will be updated and VimagitUpdateFile event will
+be raised only if the buffer is currently opened in vim.
+
+Autocmd example                                        *vimagit-autocmd_example*
+---------------
+
+The following example calls the vim-gitgutter refresh function on a specific
+buffer each time vimagit update the git status of this file.
+>
+  autocmd User VimagitUpdateFile
+    \ if ( exists("*gitgutter#process_buffer") ) |
+    \ 	call gitgutter#process_buffer(bufnr(g:magit_last_updated_buffer), 0) |
+    \ endif
+<
+The following example is already embeded in vimagit plugin (see
+|vimagit-g:magit_refresh_gitgutter|), then you shouldn't add this particular
+example to your vimrc.
 
 ===============================================================================
 5. OPTIONS                                                     *vimagit-options*
@@ -308,6 +347,13 @@ When set to 1, discard an untracked file will indeed delete this file.
 Default value is 0.
 let g:magit_discard_untracked_do_delete=[01]
 
+                                             *vimagit-g:magit_refresh_gitgutter*
+When set to 1, and if vim-gitgutter plugin is installed, gitgutter signs will
+be updated each time magit update the git status of a file (i.e. when a file
+or a hunk is staged/unstaged).
+Default value is 1.
+let g:magit_refresh_gitgutter=[01]
+
 ===============================================================================
 6. FAQ                                                             *vimagit-FAQ*
 

plugin/magit.vim

@@ -47,9 +47,17 @@ let g:magit_default_fold_level     = get(g:, 'magit_default_fold_level',
 let g:magit_default_sections       = get(g:, 'magit_default_sections',          ['info', 'global_help', 'commit', 'staged', 'unstaged'])
 let g:magit_discard_untracked_do_delete = get(g:, 'magit_discard_untracked_do_delete',        0)
 
+let g:magit_refresh_gitgutter      = get(g:, 'magit_refresh_gitgutter',         1)
 let g:magit_warning_max_lines      = get(g:, 'magit_warning_max_lines',         10000)
 
 execute "nnoremap <silent> " . g:magit_show_magit_mapping . " :call magit#show_magit('v')<cr>"
+
+if ( g:magit_refresh_gitgutter == 1 )
+	autocmd User VimagitUpdateFile
+			\ if ( exists("*gitgutter#process_buffer") ) |
+			\ 	call gitgutter#process_buffer(bufnr(g:magit_last_updated_buffer), 0) |
+			\ endif
+endif
 " }}}
 
 " {{{ Internal functions
@@ -498,6 +506,8 @@ function! magit#open_close_folding(...)
 	call magit#update_buffer()
 endfunction
 
+let g:magit_last_updated_buffer = ''
+
 " s:mg_display_functions: Dict wrapping all display related functions
 " This Dict should be accessed through g:magit_default_sections
 let s:mg_display_functions = {
@@ -515,8 +525,9 @@ let s:mg_display_functions = {
 " 3. delete buffer
 " 4. fills with unstage stuff
 " 5. restore window state
-" param[in] updated file (optional): if set and if gitgutter is installed,
-"           update gitgutter signs in this buffer
+" param[in] updated file (optional): this filename is updated to absolute
+" path, set in g:magit_last_updated_buffer and the User autocmd
+" VimagitUpdateFile event is raised
 function! magit#update_buffer(...)
 	let buffer_name=bufname("%")
 	if ( buffer_name !~ 'magit://.*' )
@@ -562,13 +573,21 @@ function! magit#update_buffer(...)
 
 	set filetype=magit
 
+	let g:magit_last_updated_buffer = ''
 	if ( a:0 == 1 )
-		if ( bufexists(a:1) != 0 )
-			if ( exists("*gitgutter#process_buffer") )
-				call gitgutter#process_buffer(a:1, 0)
+		let abs_filename = magit#git#top_dir() . a:1
+		if ( bufexists(abs_filename) )
+			let g:magit_last_updated_buffer = abs_filename
+			if exists('#User#VimagitUpdateFile')
+				doautocmd User VimagitUpdateFile
+			endif
 		endif
 	endif
+
+	if exists('#User#VimagitRefresh')
+		doautocmd User VimagitRefresh
 	endif
+
 endfunction
 
 " magit#toggle_help: toggle inline help showing in magit buffer
@@ -701,6 +720,10 @@ function! magit#show_magit(display, ...)
 		execute "nnoremap <buffer> <silent> " . mapping . " :call magit#open_close_folding_wrapper('" . mapping . "', 0)<cr>"
 	endfor
 
+	if exists('#User#VimagitBufferInit')
+		doautocmd User VimagitBufferInit
+	endif
+
 	call magit#update_buffer()
 	execute "normal! gg"
 endfunction