sawyergardner / git-gutter

Emacs port of GitGutter which is Sublime Text Plugin

git-gutter.el

Introduction

git-gutter.el is an Emacs port of the Sublime Text plugin GitGutter.

Features

• Asynchronous updating
• Live updating
• Support multiple VCS
• Support Tramp
• Work without vc-mode

Screenshot

Requirements

• Emacs 24 or higher
• Git(1.7.0 or higher)

git-gutter.el vs git-gutter-fringe.el

	git-gutter.el	git-gutter-fringe.el
Work in tty frame	OK	unsupported
Work with linum-mode	OK(experimental)	OK
Show on right side	unsupporeted	OK
configurable	more configurable	less configurable

Installation

You can install git-gutter.el from MELPA with package.el (M-x package-install git-gutter), with el-get, or with another package manager of your choice

Global Minor Mode and Minor Mode

git-gutter.el provides a global minor-mode(global-git-gutter-mode) and minor-mode(git-gutter-mode).

If you want to use git-gutter for files in git repository. You add following s-exp in your configuration file(~/.emacs.d/init.el or ~/.emacs).

(global-git-gutter-mode +1)

Other case, you want to use git-gutter for some files, you can use git-gutter-mode. Following example of enabling git-gutter for some mode.

(add-hook 'ruby-mode-hook 'git-gutter-mode)
(add-hook 'python-mode-hook 'git-gutter-mode)

Commands

git-gutter.el provides following commands. Obsoleted interfaces will be removed when 1.0 released.

git-gutter:next-hunk

Jump to next hunk

git-gutter:previous-hunk

Jump to previous hunk

git-gutter:end-of-hunk

Move to end of current hunk

git-gutter:mark-hunk

Mark current hunk.

git-gutter:set-start-revision

Set the start revision from which git-gutter performs the diffs.

You can also set the variable git-gutter:start-revision as a directory-local variable.

git-gutter:popup-hunk

Popup current diff hunk(alias git-gutter:popup-diff)

git-gutter:next-hunk and git-gutter:previous-hunk update content of buffer popuped by git-gutter:popup-diff to current hunk.

git-gutter:stage-hunk

Stage current hunk. You can use this command like git add -p. This command is supported only for git.

git-gutter:revert-hunk

Revert current hunk

git-gutter

Show changes from last commit or Update change information. Please execute this command if diff information is not be updated.

git-gutter:linum-setup

Setup for working with linum-mode.

git-gutter:update-all-windows

Update git-gutter information of buffers in all visible window.

Sample Configuration

(require 'git-gutter)

;; If you enable global minor mode
(global-git-gutter-mode t)

;; If you would like to use git-gutter.el and linum-mode
(git-gutter:linum-setup)

;; If you enable git-gutter-mode for some modes
(add-hook 'ruby-mode-hook 'git-gutter-mode)

(global-set-key (kbd "C-x C-g") 'git-gutter)
(global-set-key (kbd "C-x v =") 'git-gutter:popup-hunk)

;; Jump to next/previous hunk
(global-set-key (kbd "C-x p") 'git-gutter:previous-hunk)
(global-set-key (kbd "C-x n") 'git-gutter:next-hunk)

;; Stage current hunk
(global-set-key (kbd "C-x v s") 'git-gutter:stage-hunk)

;; Revert current hunk
(global-set-key (kbd "C-x v r") 'git-gutter:revert-hunk)

;; Mark current hunk
(global-set-key (kbd "C-x v SPC") #'git-gutter:mark-hunk)

Directory-local variables

Set starting revision for diffs

Using directory-local variables, you can set the start revision for diffs for any file in the current directory:

;;; .dir-locals.el
((prog-mode . ((git-gutter:start-revision . "my-branch"))))

Customize

Live updating

If you set git-gutter:update-interval seconds larger than 0, git-gutter updates diff information in real-time by idle timer.

(custom-set-variables
 '(git-gutter:update-interval 2))

You can stop timer by git-gutter:cancel-update-timer and starts by git-gutter:start-update-timer.

Look and feel

You can change the signs and those faces.

(custom-set-variables
 '(git-gutter:modified-sign "  ") ;; two space
 '(git-gutter:added-sign "++")    ;; multiple character is OK
 '(git-gutter:deleted-sign "--"))

(set-face-background 'git-gutter:modified "purple") ;; background color
(set-face-foreground 'git-gutter:added "green")
(set-face-foreground 'git-gutter:deleted "red")

You can change minor-mode name in mode-line to set git-gutter:lighter. Default is " GitGutter"

;; first character should be a space
(custom-set-variables
 '(git-gutter:lighter " GG"))

Using full width characters

Emacs has char-width function which returns character width. git-gutter.el uses it for calculating character length of the signs. But char-width does not work for some full-width characters. So you should explicitly specify window width, if you use full-width character.

(custom-set-variables
 '(git-gutter:window-width 2)
 '(git-gutter:modified-sign "☁")
 '(git-gutter:added-sign "☀")
 '(git-gutter:deleted-sign "☂"))

Backends

git-gutter.el supports following version control systems

• Git(1.7.0 or higher)
• Mercurial
• Subversion(1.8 or higher)
• Bazaar

You can set backends which git-gutter.el will be used. Default value of git-gutter:handled-backends is '(git). If you want to use git-gutter.el for other VCS, please change value of git-gutter:handled-backends as below.

;; Use for 'Git'(`git`), 'Mercurial'(`hg`), 'Bazaar'(`bzr`), and 'Subversion'(`svn`) projects
(custom-set-variables
 '(git-gutter:handled-backends '(git hg bzr svn)))

Updates hooks

diff information is updated at hooks in git-gutter:update-hooks.

(add-to-list 'git-gutter:update-hooks 'focus-in-hook)

Updates commands

diff information is updated after command in git-gutter:update-commands executed.

(add-to-list 'git-gutter:update-commands 'other-window)

Disabled modes

If you use global-git-gutter-mode, you may want some modes to disable git-gutter-mode. You can make it by setting git-gutter:disabled-modes to non-nil.

;; inactivate git-gutter-mode in asm-mode and image-mode
(custom-set-variables
 '(git-gutter:disabled-modes '(asm-mode image-mode)))

Default is nil.

Show signs at gutter by visual lines

Emacs folds long line if truncate-lines is nil. If git-gutter:visual-line is non-nil, git-gutter puts sign by visual lines.

(custom-set-variables
 '(git-gutter:visual-line t))

Default bahavior is that signs are put by logical lines. value of git-gutter:visual-line is nil.

Show Unchanged Information

git-gutter.el can view unchanged information by setting git-gutter:unchanged-sign. Like following.

(custom-set-variables
 '(git-gutter:unchanged-sign " "))
(set-face-background 'git-gutter:unchanged "yellow")

Default value of git-gutter:unchanged-sign is nil.

Show a separator column

git-gutter.el can display an additional separator character at the right of the changed signs. This is mostly useful when running emacs in a console.

(custom-set-variables
 '(git-gutter:separator-sign "|"))
(set-face-foreground 'git-gutter:separator "yellow")

Default value of git-gutter:separator-sign is nil.

Please set git-gutter:always-show-separator to non-nil, if you want to show separator always.

Hide gutter if there are no changes

Hide gutter when there are no changes if git-gutter:hide-gutter is non-nil. (Default is nil)

(custom-set-variables
 '(git-gutter:hide-gutter t))

Pass option to 'git diff' command

You can pass git diff option to set git-gutter:diff-option.

;; ignore all spaces
(custom-set-variables
 '(git-gutter:diff-option "-w"))

Don't ask whether commit/revert or not

git-gutter.el always asks you whether commit/revert or not. If you don't want, please set git-gutter:ask-p to nil.

;; Don't ask me!!
(custom-set-variables
 '(git-gutter:ask-p nil))

Log/Message Level

;; Don't need log/message.
(custom-set-variables
 '(git-gutter:verbosity 0))

Default value is 4(0 is lowest, 4 is highest).

Run hook

Run hook git-gutter-mode-on-hook when git-gutter-mode is turn on, and run hook git-gutter-mode-off-hook when git-gutter-mode is turn off.

Statistic

git-gutter.el provides some statistic API. This is useful for knowing how much code you changed etc. To display them in mode-line is also useful.

(git-gutter:buffer-hunks)

Count unstaged hunks in current buffer.

(git-gutter:all-hunks)

Count unstaged hunks in all buffers

(git-gutter:statistic)

Return statistic unstaged hunks in current buffer. Return value is dot-list. First element is total added lines, second element is total deleted lines.

See Also

GitGutter

GitGutter is Sublime Text plugin.

vim-gitgutter

Vim version of GitGutter

diff-hl

diff-hl is similar tool based on vc.

git-gutter-plus

Fork of git-gutter.el. Some features which are not provided git-gutter.el provides. However git-gutter-plus updates diff information synchronously.