Fugitive.vim - working with the git index
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.
I’ll be running my Core Vim Class online on Thursday, December 5th. Tickets cost $255, but you can get the earlybird discount of $230 if you buy yours before November 29th. The price includes an exclusive screencast that summarises the material from the class.
The Gstatus window
: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
||add/reset file (works in visual mode too)|
||open current file in the window below|
||run `git add --patch` for current file|
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:
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.
Comparing working copy with index version using
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.
: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:
||working copy||stage file|
||working copy||checkout file|
Vim’s built in
:diffput commands work a bit like
: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.
||working copy||stage hunk|
||working copy||checkout hunk|