Learn Vim at your own pace with my self-study Core Vim Course.

Learn more

Learn Vim at your own pace with my self-study Core Vim Course.

Fugitive.vim - working with the git index


Run time:

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.


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 :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:


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


Level-up your Vim


Boost your productivity with a Vim training class. Join a public class, or book a private session for your team.

Drew hosted a private Vim session for the shopify team that was one of the best workshops I have ever attended.

John Duff, Director of Engineering at Shopify


Make yourself a faster and more efficient developer with the help of these publications, including Practical Vim (Pragmatic Bookshelf 2012), which has over 50 five-star reviews on Amazon.

After reading it, I've switched to vim as my default editor on a daily basis with no regrets. ★★★★★

Javier Collado

Learn to use Vim efficiently in your Ruby projects

In association with thoughtbot, one of the most well respected Rails consultancies in the world, I've produced a series of screencasts on how to make navigating your Ruby projects with Vim ultra-efficient. Along the way, you’ll also learn how to make Ruby blocks a first-class text object in Vim. This lets you edit Ruby code at a higher level of abstraction. Available to buy from thoughtbot..