<commit_before>#+TITLE: Git contribution layer for Spacemacs

[[file:img/git.png]]

* Table of Contents                                                   :TOC@4:
 - [[#description][Description]]
   - [[#features][Features:]]
 - [[#install][Install]]
   - [[#layer][Layer]]
     - [[#recommended-settings][Recommended Settings]]
   - [[#magit-status-fullscreen][Magit status fullscreen]]
   - [[#magit-auto-complete][Magit auto-complete]]
   - [[#magit-svn-plugin][Magit SVN plugin]]
   - [[#git][Git]]
   - [[#git-flow][Git-Flow]]
 - [[#working-with-git][Working with Git]]
   - [[#magit][Magit]]
   - [[#commit-message-edition-buffer][Commit message edition buffer]]
   - [[#interactive-rebase-buffer][Interactive rebase buffer]]
   - [[#quick-guide-for-recurring-use-cases-in-magit][Quick guide for recurring use cases in Magit]]
   - [[#git-flow][Git-Flow]]
   - [[#git-time-machine][Git time machine]]

* Description

This layers adds extensive support for [[http://git-scm.com/][git]].

** Features:
- git repository management the indispensable  [[http://magit.vc/][magit]] package
- [[https://github.com/jtatarik/magit-gitflow][git-flow]] add-on for magit.
- quick in buffer history browsing with [[https://github.com/pidu/git-timemachine][git-timemachine]].
- quick in buffer last commit message per line with [[https://github.com/syohex/emacs-git-messenger][git-messenger]]
- colorize buffer line by age of commit with [[https://github.com/syohex/emacs-smeargle][smeargle]]
- gitignore generator with [[https://github.com/jupl/helm-gitignore][helm-gitignore]]

New to Magit? Checkout the [[http://magit.vc/about.html][official intro]].

* Install

** Layer

To use this contribution add it to your =~/.spacemacs=

#+BEGIN_SRC emacs-lisp
(setq-default dotspacemacs-configuration-layers '(git))
#+END_SRC

*** Recommended Settings
Read the documentation for the =magit-push-always-verify= variable, then you may
wish to set it to =nil= in your =dotspacemacs/user-config= function.

#+BEGIN_SRC emacs-lisp
(defun dotspacemacs/user-config ()
  (setq magit-push-always-verify nil))
#+END_SRC

The =nag= default is to prevent surprising behavior for newcomers, but causes
the ~PP~, ~Po~, ~Pe~ (and more) push commands to nag you in the same way. Once
you understand what they do, it is better simply to give the command you intend.

** Magit status fullscreen

To display the =magit status= buffer in fullscreen set the variable
=git-magit-status-fullscreen= to =t= in your =dotspacemacs/user-init= function.

#+BEGIN_SRC emacs-lisp
  (defun dotspacemacs/user-init ()
    (setq-default git-magit-status-fullscreen t)
  )
#+END_SRC

** Magit auto-complete

Magit auto-complete feature is enabled. For this feature to work best you
have to setup your Git repository directory in your =dotspacemacs/user-config=
function, this is the folder where you keep all your git-controlled projects
(the path should end up with a ~=/~= to respect Emacs conventions):

#+BEGIN_SRC emacs-lisp
  (setq magit-repository-directories '("~/repos/"))
#+END_SRC

For more information, see [[http://magit.vc/manual/magit.html#Status-buffer][Magit-User-Manual#Status-buffer]]

** Magit SVN plugin

For convenience the magit SVN plugin can be activated directly in the Git
layer by setting the variable =git-enable-magit-svn-plugin= to =t=.

#+BEGIN_SRC emacs-lisp
  (defun dotspacemacs/user-init ()
    (setq-default git-enable-magit-svn-plugin t)
  )
#+END_SRC

** Git

Of course if your OS does not ship with git (!) you'll have to install it
on your machine. You can download it from the [[http://git-scm.com/downloads][download page]].

** Git-Flow

Git-flow is a standardized branching pattern for git repositories with the aim
of making things more manageable. While there are tools to assist with making
this easier, these do nothing you couldn't do manually.

Support requires installation of the git-flow extensions. Please reference their
[[https://github.com/petervanderdoes/gitflow/wiki][installation page]] for assistance.

* Working with Git

Git commands (start with ~g~):

| Key Binding | Description                                         |
|-------------+-----------------------------------------------------|
| ~SPC g b~   | open a =magit= blame                                |
| ~SPC g C~   | commit changes                                      |
| ~SPC g d~   | show diff against current head                      |
| ~SPC g h c~ | clear highlights                                    |
| ~SPC g h h~ | highlight regions by age of commits                 |
| ~SPC g h t~ | highlight regions by last updated time              |
| ~SPC g I~   | open =helm-gitignore=                               |
| ~SPC g l~   | open a =magit= log                                  |
| ~SPC g L~   | display the log for a file                          |
| ~SPC g s~   | open a =magit= status window                        |
| ~SPC g m~   | display the last commit message of the current line |
| ~SPC g t~   | launch the git time machine                         |

- Highlight by age of commit or last update time is provided by
 [[https://github.com/syohex/emacs-smeargle][smeargle]].
- Git time machine is provided by [[https://github.com/pidu/git-timemachine][git-timemachine]].
- Git last commit message per line is provided by [[https://github.com/syohex/emacs-git-messenger][git-messenger]].

** Magit

=Spacemacs= uses [[http://magit.vc/][magit]] to manage Git repositories.

To open a =status buffer=, type in a buffer of a Git repository: ~SPC g s~

~hjkl~ navigation is enabled in all Magit buffers according to the rules of
evilification. The default Magit keys on ~hjkl~ (if they exist) are remapped on
~HJKL~.

Here are the often used bindings inside a =status buffer=, please note that
the following key bindings are valid in Vim editing style, in Emacs editing
style you can refer directly to the magit manual:

| Key Binding      | Description                                         |
|------------------+-----------------------------------------------------|
| ~/~              | evil-search                                         |
| ~$~              | open =command output buffer=                        |
| ~c c~            | open a =commit message buffer=                      |
| ~b b~            | checkout a branch                                   |
| ~b c~            | create a branch                                     |
| ~f f~            | fetch changes                                       |
| ~F -r F~         | pull and rebase                                     |
| ~C-S-g~          | refresh                                             |
| ~h~              | go left                                             |
| ~j~              | go down                                             |
| ~C-S-j~ or ~C-n~ | goto next magit section                             |
| ~k~              | go up                                               |
| ~K~              | discard changes                                     |
| ~C-S-k~ or ~C-p~ | goto previous magit section                         |
| ~l~              | go right                                            |
| ~L l~            | open =log buffer=                                   |
| ~n~              | next search occurrence                              |
| ~N~              | previous search occurrence _or_ SVN sub-menu        |
| ~P P~            | push                                                |
| ~q~              | quit                                                |
| ~s~              | on a file or hunk in a diff: stage the file or hunk |
| ~+~              | on a hunk: increase hunk size                       |
| ~-~              | on a hunk: decrease hunk size                       |
| ~S~              | stage all                                           |
| ~TAB~            | on a file: expand/collapse diff                     |
| ~u~              | on a staged file: unstage                           |
| ~U~              | unstage all staged files                            |
| ~v~              | go to =visual state=                                |
| ~V~              | go to =visual-line state=                           |
| ~C-v~            | revert item at point                                |
| ~z z~            | stash changes                                       |

** Commit message edition 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.

| Key Binding | Description |
|-------------+-------------|
| ~h~         | go left     |
| ~j~         | go down     |
| ~k~         | go up       |
| ~l~         | go right    |

** Interactive rebase buffer<commit_msg>Document v/V discrepancy in magit<commit_after>#+TITLE: Git contribution layer for Spacemacs

[[file:img/git.png]]

* Table of Contents                                                   :TOC@4:
 - [[#description][Description]]
   - [[#features][Features:]]
 - [[#install][Install]]
   - [[#layer][Layer]]
     - [[#recommended-settings][Recommended Settings]]
   - [[#magit-status-fullscreen][Magit status fullscreen]]
   - [[#magit-auto-complete][Magit auto-complete]]
   - [[#magit-svn-plugin][Magit SVN plugin]]
   - [[#git][Git]]
   - [[#git-flow][Git-Flow]]
 - [[#working-with-git][Working with Git]]
   - [[#magit][Magit]]
   - [[#staging-lines][Staging lines]]
   - [[#commit-message-edition-buffer][Commit message edition buffer]]
   - [[#interactive-rebase-buffer][Interactive rebase buffer]]
   - [[#quick-guide-for-recurring-use-cases-in-magit][Quick guide for recurring use cases in Magit]]
   - [[#git-flow][Git-Flow]]
   - [[#git-time-machine][Git time machine]]

* Description
This layers adds extensive support for [[http://git-scm.com/][git]].

** Features:
- git repository management the indispensable  [[http://magit.vc/][magit]] package
- [[https://github.com/jtatarik/magit-gitflow][git-flow]] add-on for magit.
- quick in buffer history browsing with [[https://github.com/pidu/git-timemachine][git-timemachine]].
- quick in buffer last commit message per line with [[https://github.com/syohex/emacs-git-messenger][git-messenger]]
- colorize buffer line by age of commit with [[https://github.com/syohex/emacs-smeargle][smeargle]]
- gitignore generator with [[https://github.com/jupl/helm-gitignore][helm-gitignore]]

New to Magit? Checkout the [[http://magit.vc/about.html][official intro]].

* Install
** Layer
To use this contribution add it to your =~/.spacemacs=

#+BEGIN_SRC emacs-lisp
(setq-default dotspacemacs-configuration-layers '(git))
#+END_SRC

*** Recommended Settings
Read the documentation for the =magit-push-always-verify= variable, then you may
wish to set it to =nil= in your =dotspacemacs/user-config= function.

#+BEGIN_SRC emacs-lisp
(defun dotspacemacs/user-config ()
  (setq magit-push-always-verify nil))
#+END_SRC

The =nag= default is to prevent surprising behavior for newcomers, but causes
the ~PP~, ~Po~, ~Pe~ (and more) push commands to nag you in the same way. Once
you understand what they do, it is better simply to give the command you intend.

** Magit status fullscreen
To display the =magit status= buffer in fullscreen set the variable
=git-magit-status-fullscreen= to =t= in your =dotspacemacs/user-init= function.

#+BEGIN_SRC emacs-lisp
  (defun dotspacemacs/user-init ()
    (setq-default git-magit-status-fullscreen t)
  )
#+END_SRC

** Magit auto-complete
Magit auto-complete feature is enabled. For this feature to work best you
have to setup your Git repository directory in your =dotspacemacs/user-config=
function, this is the folder where you keep all your git-controlled projects
(the path should end up with a ~=/~= to respect Emacs conventions):

#+BEGIN_SRC emacs-lisp
  (setq magit-repository-directories '("~/repos/"))
#+END_SRC

For more information, see [[http://magit.vc/manual/magit.html#Status-buffer][Magit-User-Manual#Status-buffer]]

** Magit SVN plugin
For convenience the magit SVN plugin can be activated directly in the Git
layer by setting the variable =git-enable-magit-svn-plugin= to =t=.

#+BEGIN_SRC emacs-lisp
  (defun dotspacemacs/user-init ()
    (setq-default git-enable-magit-svn-plugin t)
  )
#+END_SRC

** Git
Of course if your OS does not ship with git (!) you'll have to install it
on your machine. You can download it from the [[http://git-scm.com/downloads][download page]].

** Git-Flow
Git-flow is a standardized branching pattern for git repositories with the aim
of making things more manageable. While there are tools to assist with making
this easier, these do nothing you couldn't do manually.

Support requires installation of the git-flow extensions. Please reference their
[[https://github.com/petervanderdoes/gitflow/wiki][installation page]] for assistance.

* Working with Git
Git commands (start with ~g~):

| Key Binding | Description                                         |
|-------------+-----------------------------------------------------|
| ~SPC g b~   | open a =magit= blame                                |
| ~SPC g C~   | commit changes                                      |
| ~SPC g d~   | show diff against current head                      |
| ~SPC g h c~ | clear highlights                                    |
| ~SPC g h h~ | highlight regions by age of commits                 |
| ~SPC g h t~ | highlight regions by last updated time              |
| ~SPC g I~   | open =helm-gitignore=                               |
| ~SPC g l~   | open a =magit= log                                  |
| ~SPC g L~   | display the log for a file                          |
| ~SPC g s~   | open a =magit= status window                        |
| ~SPC g m~   | display the last commit message of the current line |
| ~SPC g t~   | launch the git time machine                         |

- Highlight by age of commit or last update time is provided by
 [[https://github.com/syohex/emacs-smeargle][smeargle]].
- Git time machine is provided by [[https://github.com/pidu/git-timemachine][git-timemachine]].
- Git last commit message per line is provided by [[https://github.com/syohex/emacs-git-messenger][git-messenger]].

** Magit
=Spacemacs= uses [[http://magit.vc/][magit]] to manage Git repositories.

To open a =status buffer=, type in a buffer of a Git repository: ~SPC g s~

~hjkl~ navigation is enabled in all Magit buffers according to the rules of
evilification. The default Magit keys on ~hjkl~ (if they exist) are remapped on
~HJKL~.

Here are the often used bindings inside a =status buffer=, please note that
the following key bindings are valid in Vim editing style, in Emacs editing
style you can refer directly to the magit manual:

| Key Binding      | Description                                         |
|------------------+-----------------------------------------------------|
| ~/~              | evil-search                                         |
| ~$~              | open =command output buffer=                        |
| ~c c~            | open a =commit message buffer=                      |
| ~b b~            | checkout a branch                                   |
| ~b c~            | create a branch                                     |
| ~f f~            | fetch changes                                       |
| ~F -r F~         | pull and rebase                                     |
| ~C-S-g~          | refresh                                             |
| ~h~              | go left                                             |
| ~j~              | go down                                             |
| ~C-S-j~ or ~C-n~ | goto next magit section                             |
| ~k~              | go up                                               |
| ~K~              | discard changes                                     |
| ~C-S-k~ or ~C-p~ | goto previous magit section                         |
| ~l~              | go right                                            |
| ~L l~            | open =log buffer=                                   |
| ~n~              | next search occurrence                              |
| ~N~              | previous search occurrence _or_ SVN sub-menu        |
| ~P P~            | push                                                |
| ~q~              | quit                                                |
| ~s~              | on a file or hunk in a diff: stage the file or hunk |
| ~+~              | on a hunk: increase hunk size                       |
| ~-~              | on a hunk: decrease hunk size                       |
| ~S~              | stage all                                           |
| ~TAB~            | on a file: expand/collapse diff                     |
| ~u~              | on a staged file: unstage                           |
| ~U~              | unstage all staged files                            |
| ~v~              | go to =visual state=                                |
| ~V~              | go to =visual-line state=                           |
| ~C-v~            | revert item at point                                |
| ~z z~            | stash changes                                       |

** Staging lines
Magit allows you to stage specific lines by selecting them in a diff and hitting
=s= to stage. Due to inconsistencies between Vim and Emacs editing styles, if
you enter visual line state with =V=, you will stage one more line than
intended. To work around this, you can use =v= instead (since Magit only stages
whole lines, in any case).

** Commit message edition 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.

| Key Binding | Description |
|-------------+-------------|
| ~h~         | go left     |
| ~j~         | go down     |
| ~k~         | go up       |
| ~l~         | go right    |

** Interactive rebase buffer
{'fraction_non_alphanumeric': 0.12399866488651536, 'fraction_numerical': 0.00011125945705384957, 'mean_word_length': 1.6409578375201999, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 18, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 68, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2540604', 'n_tokens_mistral': 5022, 'n_tokens_neox': 4833, 'n_words': 1692}