spacemacs/layers/+source-control/version-control/README.org

#+TITLE: Version-Control layer

#+TAGS: layer|versioning

* Table of Contents                     :TOC_5_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#install][Install]]
  - [[#layer][Layer]]
- [[#configuration][Configuration]]
  - [[#differences-between-margin-packages][Differences between margin packages]]
- [[#key-bindings][Key bindings]]
  - [[#vc-directory-buffer-commands][VC Directory buffer commands]]
  - [[#commit-message-editing-buffer][Commit message editing buffer]]
  - [[#diff-mode][Diff mode]]
  - [[#log-view-buffer][Log view buffer]]
  - [[#annotation-buffer][Annotation buffer]]
  - [[#version-control-transient-state][Version Control Transient-state]]
  - [[#smerge-mode-transient-state][Smerge Mode Transient-state]]
  - [[#toggles][Toggles]]

* Description
This layers adds general configuration for [[http://www.gnu.org/software/emacs/manual/html_node/emacs/Version-Control.html][Emacs VC]].
It should work with all VC backends such as Git, Mercurial, Bazaar, SVN, etc...

** Features:
- highlights uncommitted changes in the fringe or margin with [[https://github.com/dgutov/diff-hl][diff-hl]], [[https://github.com/syohex/emacs-git-gutter][git-gutter]], or [[https://github.com/nonsequitur/git-gutter-plus][git-gutter+]]
- adds vcs transient-state ~SPC g.~ to allow quick navigation and modification of buffer hunks.

* Install
** 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.

* 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:
- [[https://github.com/dgutov/diff-hl][diff-hl]]
- [[https://github.com/syohex/emacs-git-gutter][git-gutter]]
- [[https://github.com/nonsequitur/git-gutter-plus][git-gutter+]] (default)

#+BEGIN_SRC emacs-lisp
  '(version-control :variables
                    version-control-diff-tool 'diff-hl)
#+END_SRC

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

#+BEGIN_SRC emacs-lisp
  '(version-control :variables
                    version-control-diff-side 'left)
#+END_SRC

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

#+BEGIN_SRC emacs-lisp
  '(version-control :variables
                    version-control-global-margin t)
#+END_SRC

** 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       |            |             |

* 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                              |

** 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      |

** 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.

** 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 |

** 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                                          |

** 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               |

** 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    |

** Smerge Mode Transient-state
Movement:

| Key binding                | Description         |
|----------------------------+---------------------|
| ~SPC g r n~                | Next hunk           |
| ~SPC g r N~ or ~SPC g r p~ | Previous hunk       |
| ~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 |

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           |

** Toggles

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