README.md

vimagit

Ease your git workflow within vim.

From a very single vim buffer, you can perform main git operations in few key press. To name a few:

• Visualize all diffs in your git repository.
• Stage file, hunks or even just parts of a hunk using a single key press.
• Write or amend your commit message and commit in the same buffer.

Take a look at TL;DR to start using it immediately.

Some screencasts:

• A simple asciicast
• A commented video presenting vimagit (thank you Mike Hartington!)

This workflow is 100% inspired from magnificent emacs Magit plugin.

Outstanding features

• Preview all your git changes in one unique buffer, folded at hunk level.
• Interactively stage/unstage/discard changes with one key press.
• Stage/unstage at file/hunk/line level.
• Write the commit message in the same buffer.
• From a hunk in magit buffer, jump to the file at the diff position.
• 100% VimL plugin, no external dependency (except git of course).
• Enhanced by external plugins: vim-gitgutter vim-airline
• Stable. All features are tested in continuous integration.

More to come:

• Add a push function, taking care if needed about the remote repository and branch #24 .
• Handle commit fixup! and squash!, with a smart git log popup #23 .
• Handle stash: add, pop, apply, drop #26 .
• Stage multiple hunks or file by visually selecting them #83 .
• Go through history, cherry-pick changes.
• Make vimagit more efficient for huge repositories, with a lot of diffs.
• Something is missing? Open an issue!

Why should I use vimagit, there are already plethora git plugins for vim?

• fugitive is a very complete plugin, with a lot of functions. I use it for years, and it is a fundamental tool in my workflow. But visualize your changes and staged them in broad number of files is really a pain.
• vim-gitgutter is very well integrated into vim, but without the ability to commit stages, it stays an informational plugin.

TL;DR

This is the minimal required set of command you must know to start playing with vimagit. See Mappings for a complete description.

To simply test vimagit, modify/add/delete/rename some files in a git repository and open vim.

• :Magit
  Open magit buffer with :Magit command.
• <C-n>
  Jump to next hunk with <C-n>, or move the cursor as you like. The cursor is on a hunk.
• S
  While the cursor is on an unstaged hunk, press S in Normal mode: the hunk is now staged, and appears in "Staged changes" section (you can also unstage a hunk from "Staged section" with S).
• CC
  Once you have stage all the required changes, press CC.
  • Section "Commit message" is shown.
  • Type your commit message in this section.
  • To commit, go back in Normal mode, and press CC (or :w if you prefer).

You just created your first commit with vimagit!

Installation

This plugin follows the standard runtime path structure, and as such it can be installed with a variety of plugin managers:

• Pathogen
  git clone https://github.com/jreybert/vimagit ~/.vim/bundle/vimagit
  Remember to run :Helptags to generate help tags
• NeoBundle
  NeoBundle 'jreybert/vimagit'
• Vundle
  Plugin 'jreybert/vimagit'
• Plug
  Plug 'jreybert/vimagit'
• VAM
  call vam#ActivateAddons([ 'jreybert/vimagit' ])
• manual
  copy all of the files into your ~/.vim directory

Usage

Modes

vimagit buffer has modes. Mappings may have different behavior, depending on current mode and curosr position.

For the moment, vimagit counts only two modes.

Stage mode

This is the default mode. In this mode, you can stage and unstage hunks, refresh vimagit buffer...

Commit mode

In this mode, "Commit message" section is open, you can write your commit message and validate your commit.

Commit mode has two flavors.

Commit mode flavors

• Normal: current commit will be a new commit.
• Amend: current commit will be meld with previous commit.
  • Previous commit message is shown in "Commit message" section.
  • Use this flavor if you forgot something in the previous commit.

By the way, you can also perform all stage mode actions in commit mode.

Sections

IMPORTANT: mappings can have different meanings regarding the cursor position.

There are 5 sections:

• Info: this section display some information about the git repository, like the current branch and the HEAD commit.
• Commit message: this section appears in commit mode. It contains the message to be committed.
• Staged changes: this sections contains all staged files/hunks, ready to commit.
• Unstaged changes: this section contains all unstaged and untracked files/hunks.
• Stash list: this section contains all stahes.

Inline modifications

• It is possible to modify the content to be staged or unstaged in magit buffer, with some limitations:
  • only lines starting with a + sign can be modified
  • no line can be deleted

Visual selection

It is possible to stage part of hunk, by different ways:

• By visually selecting some lines, then staging the selection with S.
• By marking some lines "to be staged" with M, then staging these selected lines with S.
• Staging individual lines with L.

Visual selection and marked lines have some limitations for the moment:

• It only work for "staging", not for "unstaging".
• Selection/marks must be within a single hunk.
• Marks not within the hunk currently staged are lost during stage process magit buffer refresh.

Commands

magit#show_magit()

Function to open magit buffer. This buffer will handle the git repository including focused file. It is possible to handle multiple git repositories within one vim instance.

It takes 3 parameters:

• orientation (mandatory): it can be
  • 'v', curent window is split vertically, and magit is displayed in new buffer
  • 'h', curent window is split horizontally, and magit is displayed in new buffer
  • 'c', magit is displayed in current buffer
• show_all_files: define how file diffs are shown by default for this session (see g:magit_default_show_all_files)
• foldlevel: set default magit buffer foldlevel for this session (see g:magit_default_fold_level)

:Magit

Open magit buffer in a vertical split (see details).

:MagitOnly

Open magit buffer in current window (see details).

You can create a bash alias like magit="vim -c MagitOnly"

Mappings

For each mapping, user can redefine the behavior with its own mapping. Each variable is described in vimagit help like vimagit-g:magit_nameofmapping_mapping

Global mappings