spacemacs/contrib/git/README.md

git contribution layer for Spacemacs

Table of Contents

• git contribution layer for Spacemacs
  • Description
  • Install
  • Working with Git
    • Magit
    • Quick guide for recurring use cases in Magit
    • Git gutter bitmaps
  • Github support
    • magit-gh-pulls
    • gist.el
    • github-browse-file

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

This layer also provides support for Github with:

• magit-gh-pulls: handy magit add-on to manage Github pull requests.
• gist.el: full-featured mode to browse and post Githug gists.

Install

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

(setq-default dotspacemacs-configuration-layers '(git)
  "List of contribution to load."
)

To enable the Github support set the variable git-enable-github-support to t in your dotspacemacs/init function.

(defun dotspacemacs/init ()
  (setq-default git-enable-github-support t)
)

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

<SPC> 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-j</kbd | goto next magit section k | go up K | discard changes C-k</kbd | goto previous magit section l | go right L l | open log buffer n | next search occurrence C-n</kbd | goto next magit section N | previous search occurrence P P | push C-p</kbd | goto previous magit section 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 | 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:

Symbol	Description
	new line
	at least one line has been deleted
	modified line

Github support

magit-gh-pulls

In a magit status buffer (SPC g s):

Key Binding     |                 Description

--------------------|------------------------------------------------------------ # g g | get a list of all PRs in the current repository # g f | fetch the commits associated to the current PR # g b | create a branch for the current PR # g m | merge the PR with current branch

Note that magit-gh-pulls will try to fast-forward the PRs whenever it is possible.

gist.el

Key Binding       |                 Description

----------------------|------------------------------------------------------------ SPC g g b | create a public gist with the buffer content SPC g g B | create a private gist with the buffer content SPC g g l | open the gist list buffer SPC g g r | create a public gist with the region content SPC g g R | create a private gist with the region content

In the gist list buffer:

Key Binding              |                 Description

-----------------------------|------------------------------------------------------------ / | evil search + | add buffer to gist - | remove file for gist b or o | open current gist in browser f | fetch current gist g | refresh the list h | go left j | go down k | go up K | kill current gist l | go right n | next search occurrence N | next previous occurrence v | visual state V | visual-line state y | print URL and copy it

github-browse-file

Key Binding       |                 Description

----------------------|------------------------------------------------------------ SPC g f b | browse to file on github