.. | ||
img | ||
config.el | ||
packages.el | ||
README.md |
git contribution layer for Spacemacs
Table of Contents
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.
- github-browse-file and git-link: quickly browse github URL in your browser.
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
Commit message edition buffer
In a commit message buffer press C-c C-c or SPC m c c to commit the changes with the entered message. Pressing C-c C-k or SPC m k will discard the commit message.
Key Binding | Description
----------------------|-------------------------------------------------------- h | go left j | go down k | go up l | go right SPC m c c | commit SPC m k | abort
Interactive rebase buffer
Key Binding | Description
----------------------|-------------------------------------------------------- c | pick e | edit f | fixup h | go left j | go down J | move line down k | go up K | move line up C-k | kill line l | go right r | reword s | squash u | undo x | execute y | insert SPC m c c | rebase SPC m k | abort
Quick guide for recurring use cases in Magit
- Amend a commit:
L l
to openlog buffer
c a
on the commit you want to amendC-c C-c
to submit the changes
- Squash last commit:
L l
to openlog buffer
E
on the second to last commit, it opens therebase buffer
j
to put point on last commits
to squash itC-c C-c
to continue to thecommit 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).
- in the
- Add upstream remote (the parent repository you have forked):
b v
to open thebranch 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 chooseupstream
or the name you gave to itP P
to push the commit toorigin
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 Y | copy current commit hash
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
Browse files
Key Binding | Description
----------------------|------------------------------------------------------------ SPC g f b | browse to file on github SPC g f c | browse to file on github/bitbucket/etc (on current line at commit) SPC g f C | only copy the generated link on the kill ring SPC g f l | browse to file on github/bitbucket/etc (on current line position) SPC g f L | only copy the generated link on the kill ring
Notes
- You can use the universal argument
SPC u
to select a remote repository. - You can use
git-link
on a region. - When the link is opened, the URL is also copied in the kill ring, you can
override this behavior by setting the variable
git-link-open-in-browser
tonil
.