Version-Control layer

Table of ContentsClose

1. Description
- 1.1. Features:
2. Install
- 2.1. Layer
3. Configuration
- 3.1. Differences between margin packages
4. Key bindings

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

Movement:

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 u`	Keep upper
`SPC g r b`	Keep base
`SPC g r l`	Keep lower
`SPC g r a`	Keep all
`SPC g r c`	Keep current
`SPC g r K`	Kill current

Diff:

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

Other:

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