vimagit: a Magit style git buffer for Vim, and the features it still lacks

Why not fugitive, and why not gitgutter

The readme answers the obvious question directly, in a section headed by the question of why to use vimagit when there are already a plethora of git plugins for Vim.

The answer is a comparison with two specific tools. fugitive is described as a very complete plugin with a lot of functions, one the author used for years and considers a fundamental tool in his workflow, but visualizing your changes and staging them in breadth across many files is really a pain. vim-gitgutter is described as very well integrated into Vim, but without the ability to commit staged changes it stays an informational plugin.

That is a precise diagnosis of the gap. A full featured plugin whose cross-file staging is a pain, and an informational view that cannot commit. vimagit sits in the space between them, and the design goal is stated as being 100 percent inspired by Magit, the Emacs plugin.

The consequence of that inspiration is visible in the workflow. The plugin presents all your git changes in one unique buffer, folded at hunk level, and that buffer becomes the place where you stage, unstage, write the commit message and commit. There is no separate command line, no separate status window, no dialog to leave the buffer for. The plugin is 100 percent VimL with no external dependency except git itself, and it is designed to be enhanced by external plugins such as vim-gitgutter and vim-airline.

One buffer with sections, and two modes

The central idea is a single Vim buffer that mirrors the state of the repository.

The buffer has sections. Unstaged changes appear in one, staged changes in another, and when you move to commit there is a commit message section. The buffer is folded at hunk level, so the file structure stays visible and the individual hunks expand on demand.

The plugin has two modes, and the mappings behave differently depending on the mode and the cursor position. The stage mode is the default, where you stage and unstage hunks and refresh the buffer. The commit mode opens the commit message section, where you write the message and validate the commit. Commit mode has two flavours: normal, where the commit will be a new commit, and amend, where the current commit is meld with the previous one, with the previous commit message shown in the commit message section so you can adjust it if you forgot something in the last commit. The documentation also notes that you can perform all stage mode actions in commit mode.

That amend handling is the detail that shows the design has been used in anger. Amending is a common correction, and in a buffer based workflow the question is how you get the previous message in front of you without a second screen, and this plugin answers it by showing it in place.

Four keystrokes and your first commit

The TL;DR section is the shortest possible tutorial, and it is worth reading as a description of the intended interaction.

The first command is `:Magit`, which opens the magit buffer. Then `<C-n>` jumps to the next hunk, though the documentation notes you can move the cursor as you like since the cursor is on a hunk.

Staging is the `S` key. While the cursor is on an unstaged hunk, pressing `S` in Normal mode stages the hunk, and it appears in the staged changes section; the same key unstages a hunk from the staged section. The documentation lists staging at file, hunk and line level among the outstanding features, which is a level of granularity most git tooling reaches only with effort.

Committing is `CC`. Once the changes you want are staged, pressing `CC` shows the commit message section, you type your message there, then you go back to Normal mode and press `CC` again, or `:w` if you prefer, to perform the commit. The plugin also supports jumping from a hunk in the magit buffer to the file at the diff position.

What it does not do yet is equally documented. The list of work to come includes a push function that takes care of the remote repository and branch, handling of `commit fixup!` and `squash!` with a smart git log popup, stash support with add, pop, apply and drop, staging multiple hunks or files by visual selection, going through history and cherry-picking, and making the plugin more efficient for huge repositories with a lot of diffs. Each of those is tied to an issue number, and the author asks for feedback on the design of the three new commands planned for the next major release: git push with `<CP>`, git checkout with `<CH>`, and git stash with the same staging mechanism used for a commit.

Every refresh rebuilds the whole buffer

The performance section is the most candid part of the documentation, and it explains the plugin's main weakness.

For various reasons, vimagit may be slow to refresh, and a refresh happens every time you stage, unstage, commit or refresh the buffer. The reason is stated without hedging: currently, vimagit is quite dumb, every time the buffer is refreshed it dumps everything and reconstructs the entire buffer. The author adds that it could be smarter, but that there are a lot of corner cases and it is quite a big work.

The symptoms are described concretely. The plugin tends to be slow when there is a lot of diff lines, and when there are long lines.

The mitigation offered is a single setting, the default fold level:

let g:magit_default_fold_level = 0

With the fold level at 0, diff content is not printed in the buffer, so the buffer shows only the files containing diffs, and you move the cursor to the filename and press `<Enter>` to see the diff relative to that file. The author also notes that vimagit may in the near future adapt the fold level automatically based on the number of diff lines, though that is a plan rather than a shipped feature.

The trade here is honest. A full buffer rebuild is simple and easy to reason about, and it is what makes the plugin pure VimL with no dependencies, but on a large diff the cost is real. Setting the fold level to 0 is a one line change that trades detail for speed, and for most working sessions the file list is what you need anyway.

Installation across the plugin manager generation

The installation section lists the plugin managers that were current when the project was written, which is itself a signal about the project's age.

With Pathogen, the plugin is cloned into the standard runtime path, and you are reminded to run `:Helptags` to generate the help tags. NeoBundle, Vundle, Plug and VAM each have their own one line declaration, and the manual option is to copy all of the files into your `~/.vim` directory.

call vam#ActivateAddons([ 'jreybert/vimagit' ])

What is missing from that list is telling. There is no lazy.nvim, no packer, no pckr entry, which means the plugin has not been updated for the current generation of Vim plugin managers, and the repository's CI is Travis CI, with the build status badge pointing at travis-ci.org.

The repository layout is the classic Vim plugin structure, with `plugin/`, `autoload/`, `syntax/`, `doc/`, `common/` and `test/` directories, plus a `Changelog`, a `CONTRIBUTING.md` and a Travis configuration. The `autoload/` directory is where a Vim plugin of this size puts most of its logic, and the presence of a `test/` directory is what backs the claim that all features are tested in continuous integration.

One naming detail is worth flagging for anyone who also uses Magit or another plugin with a similar prefix: the configuration variable documented for the fold level is `g:magit_default_fold_level`, so the plugin uses the `magit_` prefix for its options rather than a `vimagit_` one.

Where vimagit is the wrong tool

Two things decide this, and both are about the project's state rather than its design.

The first is the release history. The tags are 1.7.3 from 2018-11-29, 1.7.2 from 2017-08-08 and 1.7.1 from 2017-02-27. The last push to the repository was on 2026-07-30, so the source is being touched, but there has been no release since 2018. The project is not archived, and the readme carries a section titled Release 1.8 that describes the planned push, checkout and stash commands, but the 1.8 release described there has not happened. For a plugin that touches the index and writes commits, that gap is the first thing to weigh, because a plugin that parses git output and manipulates the index needs to keep up with git itself.

The second is the missing feature set, and it is not a small one. No push, no branch checkout, no stash, no history browsing, no cherry-pick. For a user who only commits locally and pushes from a terminal, that is tolerable. For a user whose whole workflow is inside the buffer, it means the plugin covers the diff and commit and nothing beyond them.

The performance ceiling is the third point, and it is structural rather than a bug. Rebuilding the whole buffer on every stage, unstage and commit means the plugin will always be slowest exactly where the work is hardest, on a big diff. The fold level setting works around it, but it is a workaround.

Finally, a licensing note. The licence field in the repository metadata is not stated, so the terms are not visible from the badge, and the repository root does not list a LICENSE file among its entries. For a plugin that runs arbitrary Vim script in your editor and manipulates your git index, reading the licence file and the code is worth doing before installing it.

Editorial conclusion

vimagit fits a Vim user who works on large diffs and wants to stage piece by piece without dropping to a terminal, and who is comfortable with a plugin whose feature set is deliberately small. It does not fit a user who needs push, branch checkout or stash, since those are listed as planned work rather than shipped features, and it is a poor fit for anyone who needs a maintained release stream, because the newest tag is 1.7.3 from 2018. Before you install it, read the changelog and the open issues for push, checkout and stash, and set `g:magit_default_fold_level = 0` if you work in repositories with large diffs, because the refresh path rebuilds the entire buffer.

Frequently asked questions

Official sources

1. Issues
2. jreybert/vimagit on GitHub
3. README
4. Releases