Fugitive.vim - working with the git index

The Gstatus window

The :Gstatus command opens a status window. The contents closely resemble the output from running git status in the shell, but fugitive makes the window interactive. You can jump directly between files with ctrl-n and ctrl-p.

command	affect
`-`	add/reset file (works in visual mode too)
`<Enter>`	open current file in the window below
`p`	run `git add –patch` for current file
`C`	invoke `:Gcommit`

Working with the git index

The git index is where you put changes that you want to be included in the next commit. If you are used to working with the command line git client, you might think of the index as an abstract concept. But with fugitive, you can actually read the index version of a file into a buffer by running:

:Gedit :path/to/file

If you run :Gedit with no arguments from a working tree file, it will open the index version of that file. You can always open the index version of the current file by running any one of the following:

:Gedit
:Gedit :0
:Gedit :%

It helps to understand the lifecycle of the index file between two commits. To begin with, the contents of the index and working copy files will be exactly the same as the most recent commit. As you make changes to your working copy, its contents begin to diverge from those of the index file. Staging a file updates the contents of the index file to match those of the working copy. When you commit your work, it is the contents of the index file that are saved with that commit object.

Index Lifecycle

Comparing working copy with index version using `:Gdiff`

When you run:

:Gdiff

on a work tree file without any arguments, fugitive performs a vimdiff against the index version of the file. This opens a vertical split window, with the index file on the left and the working copy on the right. The files always appear in that order, so you can commit that to memory.

Wholesale reconciliation

The :Gread and :Gwrite commands can either add a file to the index or reset the file, depending on where they are called from. The following table and diagrams summarize the possibilities:

command	active window	affect
`:Gwrite`	working copy	stage file
`:Gread`	working copy	checkout file
`:Gwrite`	index	checkout file
`:Gread`	index	stage file

Gread Gwrite Matrix

Piecemeal reconciliation

Vim’s built in :diffget and :diffput commands work a bit like :Gread and :Gwrite, except that they are more granular. Whereas :Gread will completely overwrite the current buffer with the contents of the other buffer, :diffget will only pull in a patch at a time.

command	active window	affect
`:diffput`	working copy	stage hunk
`:diffget`	working copy	checkout hunk
`:diffput`	index	checkout hunk
`:diffget`	index	stage hunk

Diffget Diffput Matrix

VimCasts.org