You are viewing the documentation for the develop branch. The documentation for the release version is here .

Table of Contents

Version-Control layer

Table of ContentsClose

1. Description

This layers adds general configuration for Emacs VC. It should work with all VC backends such as Git, Mercurial, Bazaar, SVN, etc…

1.1. Features:

  • highlights uncommitted changes in the fringe or margin with diff-hl, git-gutter, or git-gutter+
  • adds vcs transient-state SPC g. to allow quick navigation and modification of buffer hunks.

2. Install

2.1. Layer

To use this configuration layer, add it to your ~/.spacemacs. You will need to add version-control to the existing dotspacemacs-configuration-layers list in this file.

3. Configuration

You can choose the package to facilitate the diff transient-state and show margins by setting the version-control-diff-tool variable to one of the supported packages:

'(version-control :variables
                  version-control-diff-tool 'diff-hl)

You can choose the side on which the diff appears (by default it's the right side)

'(version-control :variables
                  version-control-diff-side 'left)

To automatically enable diff margins in all buffers, set version-control-global-margin

'(version-control :variables
                  version-control-global-margin t)

3.1. Differences between margin packages

This layer contains generalized mappings for three diff margin packages: diff-hl, git-gutter, and git-gutter+.

There are some differences between packages that might have some people prefer one over the other:

Feature diff-hl git-gutter git-gutter+
Show in fringe X X X
Extended VCS support (e.g. hg, svn) X X  
Stage hunks from buffer   X X
Dired support X    

4. Key bindings

VC commands:

Key binding Description
SPC g . Version control transient-state
SPC g o Browser at remote
SPC g r Smerge mode transient-state
SPC g v = Open a hunk under the point in the diff buffer
SPC g v D Compare the entire working tree with head
SPC g v e Show diff against current head using ediff
SPC g v g Visually annotate the current file
SPC g v d Open the VC Directory buffer
SPC g v + Update the working copy
SPC g v i Register (add) into a version control system
SPC g v u Revert working copy to their repository contents
SPC g v l List the change log
SPC g v L List the change log for the current VC controlled tree
SPC g v v Do the next logical VC operation (vc-next-action)
SPC g v I Ignore file (vc-ignore)
SPC g v r Resolve conflicts in file

4.1. VC Directory buffer commands

You can hit SPC pv from the current project to open the VC Directory buffer, or use SPC g v d for specifying a root directory. Then you may mark (m key) files you are interested in, to form a fileset. Most commands described above are applicable to filesets too. To some of them are given shortcuts:

Key binding Description
= Compare selected files with head
c Open a commit message buffer
l List changes
a Annotate selected files
i Add into a version control system
r Refresh directory view
E Ignore file under cursor

Navigation and interaction commands in the VC Directory buffer:

Key binding Description
j or M-n Next file
k or M-p Previous file
gj or TAB Next directory
gk or S-TAB Previous directory
m Mark a file
u Unmark a file

4.2. Commit message editing buffer

In a commit message buffer press C-c C-c to commit the changes with the entered message. Pressing C-c C-k will discard the commit message and close this buffer.

4.3. Diff mode

Key binding Description
SPC m a Apply a hunk
SPC m d Kill the hunk at point
SPC m D Kill the current file's hunk
SPC m e Call ediff-patch-file on current buffer
SPC m f c Convert unified diffs to context diffs
SPC m f r Reverse the direction of the diffs
SPC m f u Convert context diffs to unified diffs
SPC m g Jump to the corresponding source line
SPC m j Next hunk
SPC m J Next file
SPC m k Previous hunk
SPC m K Previous file
SPC m q Close the diff window
SPC m r Revert a hunk
SPC m s Split the current hunk at point into two hunks
SPC m u Undo

A transient buffer is also defined, start it with SPC m . or , .

Key binding Description
j Next hunk
J Next file
k Previous hunk
K Previous file

4.4. Log view buffer

Key binding Description
C-j or M-n Next message
C-k or M-p Previous message
gj or J or TAB Next file
gk or K or S-TAB Previous file
f or ENTER Visit the version at point
d Display a diff between the revision at point and the next earlier revision
o Use for jumping to links
H Toggle hiding of the full message

4.5. Annotation buffer

Key binding Description
J Visit the annotation of the revision after this one
K Visit the annotation of the revision previous to this one
L visit the log of the revision at line
H Toggle whether or not the annotation is visible
a Visit the annotation of the revision identified in the current line
p Visit the annotation of the revision before the revision at line
d Display the diff between the current line's revision and the previous revision
f Show in a buffer the file revision indicated by the current line

4.6. Version Control Transient-state

Use SPC g . to enter a transient state for quickly navigating between hunks in a buffer. During that state, the following bindings are active:

Key binding Description
h Show diff of hunk
n Next hunk
N or p Previous hunk
r Revert hunk
s Stage hunk
t Toggle margin indicators
w Stage file
u Unstage file
d Repo diff popup
D Show diffs of unstaged hunks
c Commit with popup
C Commit
P Push repo with popup
f Fetch for repo with popup
F Pull repo with popup
l Show repo log
z Recenter buffer in window

4.7. Smerge Mode Transient-state


Key binding Description
SPC g r n Next conflict (possibly in another file)
SPC g r N or SPC g r p Previous conflict (possibly in another file)
SPC g r j Go to next line
SPC g r k Go to previous line

Merge Actions:

Key binding Description
SPC g r b Keep base
SPC g r m Keep mine
SPC g r a Keep all
SPC g r o Keep other
SPC g r c Keep current
SPC g r K Kill current


Key binding Description
SPC g r < Diff base and mine
SPC g r = Diff mine and other
SPC g r > Diff base and other
SPC g r r Refine
SPC g r e Ediff


Key binding Description
SPC g r C Combine current and next hunks
SPC g r u Undo
SPC g r q Quit transient state

4.8. Toggles

Key binding Description
SPC T d Toggle diff margins
SPC T C-d Toggle diff margins globally

Author: root

Created: 2022-05-24 Tue 11:52