Subscribe for free with iTunes, Twitter, or RSS (Ogg or Quicktime).

Vimcasts

Fugitive.vim - working with the git index

#32

The fugitive plugin provides an interactive status window, where you can easily stage and review your changes for the next commit. The :Gdiff command visualizes the changes made to a file, by comparing the working copy with the index. In this episode, we’ll learn how to stage hunks of changes to the index without using the git add --patch command.

This is the second of a five part series on fugitive.vim. In the next episode, we’ll learn how to resolve a git merge conflict by performing a 3-way vimdiff.

Download

OGG 18.3 MB

Quicktime 24.6 MB

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

Further reading