spacemacs/contrib/git/README.md

git contribution layer for Spacemacs

Table of Contents

• git contribution layer for Spacemacs
  • Description
  • Install
    • Layer
    • Github support
    • Magit status fullscreen
    • Magit auto-complete
    • Magit SVN plugin
    • Git gutter
    • Git
  • Working with Git
    • Magit
    • Quick guide for recurring use cases in Magit
    • Git time machine
    • Git gutter
  • 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.

New to Magit? Checkout the official intro.

Install

Layer

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

(setq-default dotspacemacs-configuration-layers '(git))

Github support

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

Magit status fullscreen

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

(defun dotspacemacs/init ()
  (setq-default git-magit-status-fullscreen t)
)

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

(setq magit-repo-dirs '("~/repos/"))

For more information, see Magit-User-Manual#Status

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.

(defun dotspacemacs/init ()
  (setq-default git-enable-magit-svn-plugin t)
)

Git gutter

In graphical environment Spacemacs will display git-gutter icons in the fringe by default.

It is possible to disable the usage of the fringe by setting the variable git-gutter-use-fringe to nil in the dotspacemacs/init function:

(defun dotspacemacs/init ()
  (setq-default git-gutter-use-fringe nil)
)

Git

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 b | open a magit blame SPC g C | commit changes 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 l | open a magit log 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 (if they exist) 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 or SVN sub-menu 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
  • 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 time machine

git-timemachine allows to quickly browse the commits of the current buffer.

Key Binding     |                 Description

--------------------|------------------------------------------------------------ SPC g t | start git timemachine and initiate micro-state c | show current commit n | show next commit N | show previous commit p | show previous commit q | leave micro-state and git timemachine

Git gutter

With git-gutter it is possible to navigate between hunks, stage them and revert them.

Git gutter hunks commands start with gh:

Key Binding       |                 Description

----------------------|------------------------------------------------------------ SPC g h n | next hunk in buffer SPC g h N | previous hunk in buffer SPC g h r | revert current hunk SPC g h s | stage current hunk

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