# git contribution layer for Spacemacs
![logo](git.png)
**Table of Contents**
- [git contribution layer for Spacemacs](#git-contribution-layer-for-spacemacs)
- [Description](#description)
- [Install](#install)
- [Working with Git](#working-with-git)
- [Magit](#magit)
- [Quick guide for recurring use cases in Magit](#quick-guide-for-recurring-use-cases-in-magit)
- [Git gutter bitmaps](#git-gutter-bitmaps)
## Description
This layers adds extensive support for [git][].
Features:
- git repository management the indispensable [magit][] package
- [git-flow][] add-on for magit.
- quick in buffer history browsing with [git-timemachine][]
- quick in buffer last commit message per line with [git-messenger][]
- colorize buffer line by age of commit with [smeargle][]
- git gutter in fringe with [git-gutter][]
## Install
To use this contribution add it to your `~/.spacemacs`
```elisp
(setq-default dotspacemacs-configuration-layers '(git)
"List of contribution to load."
)
```
Of course if your OS does not ship with git (!) you'll have to install it
on your machine, [download page][].
## Working with Git
Git commands (start with `g`):
Key Binding | Description
---------------------------|------------------------------------------------------------
SPC g c c | highlight regions by age of commits
SPC g c C | clear highlights
SPC g c t | highlight regions by last updated time
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
[smeargle][].
- Git time machine is provided by [git-timemachine][].
- Git last commit message per line is provided by
[git-messenger][]
### Magit
`Spacemacs` uses [magit][] to manage Git repositories.
To open a `status buffer`, type in a buffer of a Git repository:
g s
`hjkl` navigation is enabled in all Magit buffers. The default Magit keys
on `hjkl` are remapped on `HJKL`.
Here are the often used bindings inside a `status buffer`:
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
b v | open the `branch manager buffer`
f f | fetch changes
F -r F | pull and rebase
h | go left
j | go down
C-jk | go up
K | discard changes
C-kl | go right
L l | open `log buffer`
n | next search occurrence
C-nN | previous search occurrence
P P | push
C-pq | 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 | `visual state`
V | `visual-line state`
C-v | revert item at point
z z | stash changes
In a commit message buffer press `C-c C-c` to commit the changes with the
entered message. `C-c C-k` will discard the commit message.
**Note:** Sometimes you will be asked about reverting the commit buffer,
you can answer `y` with no issue.
### Quick guide for recurring use cases in Magit
- Amend a commit:
- `L l` to open `log buffer`
- `c a` on the commit you want to amend
- `C-c C-c` to submit the changes
- Squash last commit:
- `L l` to open `log buffer`
- `E` on the second to last commit, it opens the `rebase buffer`
- `j` to put point on last commit
- `i` to pass in `insert state`
- `s` to squash it
- `C-c C-c` to continue to the `commit message buffer`
- `C-c C-c` again when you have finished to edit the commit message
- Force push a squashed commit:
- in the `status buffer` you should see the new commit unpushed and the
old commit unpulled
- `P -f P` for force a push (**beware** usually it is not recommended to
rewrite the history of a public repository, but if you are *sure* that you
are the only one to work on a repository it is ok - i.e. in your fork).
- Add upstream remote (the parent repository you have forked):
- `b v` to open the `branch manager buffer`
- `a` to add a remote, type the name (i.e. `upstream`) and the URL
- Pull changes from upstream (the parent repository you have forked) and push:
- `F -r C-u F` and choose `upstream` or the name you gave to it
- `P P` to push the commit to `origin`
### Git gutter bitmaps
`Spacemacs` has custom fringe bitmaps for
[git-gutter-fringe][git-gutter]:
Symbol | Description
:-------------------------------:|-----------------
![git-new](git-new-line.png) | new line
![git-del](git-del-line.png) | at least one line has been deleted
![git-mod](git-mod-line.png) | modified line
[git]: http://git-scm.com/
[download page]: http://git-scm.com/downloads
[git-gutter]: https://github.com/syohex/emacs-git-gutter-fringe
[magit]: http://magit.github.io/
[git-flow]: https://github.com/jtatarik/magit-gitflow
[smeargle]: https://github.com/syohex/emacs-smeargle
[git-timemachine]: https://github.com/pidu/git-timemachine
[git-messenger]: https://github.com/syohex/emacs-git-messenger