288 lines
14 KiB
Org Mode
288 lines
14 KiB
Org Mode
#+TITLE: Git contribution layer for Spacemacs
|
||
|
||
[[file:img/git.png]]
|
||
|
||
* Table of Contents :TOC_4_gh:noexport:
|
||
- [[#descriptions][Descriptions]]
|
||
- [[#features][Features:]]
|
||
- [[#install][Install]]
|
||
- [[#layer][Layer]]
|
||
- [[#magit-status-fullscreen][Magit status fullscreen]]
|
||
- [[#magit-auto-complete][Magit auto-complete]]
|
||
- [[#magit-svn-plugin][Magit SVN plugin]]
|
||
- [[#global-git-commit-mode][Global git commit mode]]
|
||
- [[#git][Git]]
|
||
- [[#git-flow][Git-Flow]]
|
||
- [[#org-integration][Org integration]]
|
||
- [[#working-with-git][Working with Git]]
|
||
- [[#magit][Magit]]
|
||
- [[#staging-lines][Staging lines]]
|
||
- [[#commit-message-editing-buffer][Commit message editing 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-1][Git-Flow]]
|
||
- [[#git-time-machine][Git time machine]]
|
||
- [[#git-links-to-web-services][Git links to web services]]
|
||
- [[#repository-list][Repository list]]
|
||
|
||
* Descriptions
|
||
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]]
|
||
- org integration with magit via [[https://github.com/magit/orgit][orgit]]
|
||
|
||
New to Magit? Checkout the [[https://magit.vc/about/][official intro]].
|
||
|
||
* Install
|
||
** Layer
|
||
To use this configuration layer, add it to your =~/.spacemacs=. You will need to
|
||
add =git= to the existing =dotspacemacs-configuration-layers= list in this
|
||
file.
|
||
|
||
** 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
|
||
|
||
** Global git commit mode
|
||
Spacemacs can be used as the =$EDITOR= (or =$GIT_EDITOR=) for editing git
|
||
commits messages. To enable this you have to add the following line to your
|
||
=dotspacemacs/user-config=:
|
||
|
||
#+begin_src emacs-lisp
|
||
(global-git-commit-mode 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.
|
||
|
||
** Org integration
|
||
|
||
See the commentary section of the package [[https://github.com/magit/orgit/blob/master/orgit.el#L28][here]].
|
||
|
||
* Working with Git
|
||
Git commands (start with ~g~):
|
||
|
||
| Key Binding | Description |
|
||
|-------------+-----------------------------------------------------|
|
||
| ~SPC g b~ | open a =magit= blame |
|
||
| ~SPC g f f~ | view a file at a specific branch or commit |
|
||
| ~SPC g f h~ | show file commits history |
|
||
| ~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~ | initialize a new git repository |
|
||
| ~SPC g I~ | open =helm-gitignore= |
|
||
| ~SPC g L~ | open magit-repolist |
|
||
| ~SPC g s~ | open a =magit= status window |
|
||
| ~SPC g S~ | stage current file |
|
||
| ~SPC g m~ | magit dispatch popup |
|
||
| ~SPC g M~ | display the last commit message of the current line |
|
||
| ~SPC g t~ | launch the git time machine |
|
||
| ~SPC g U~ | unstage current file |
|
||
|
||
- 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~.
|
||
The central key binding hub of Magit is available on ~SPC g m~.
|
||
|
||
Spacemacs uses [[https://github.com/justbur/evil-magit][evil-magit]] for key bindings in magit buffers (unless your editing
|
||
style is set to emacs, in which case you get the default magit bindings), which
|
||
are the standard magit key bindings with some minimal changes to make them
|
||
comfortable for evil users.
|
||
|
||
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 |
|
||
| ~f f~ | fetch changes |
|
||
| ~F (r) u~ | pull tracked branch and rebase |
|
||
| ~gr~ | refresh |
|
||
| ~j~ | goto next magit section |
|
||
| ~C-j~ | next visual line |
|
||
| ~k~ | goto previous magit section |
|
||
| ~C-k~ | previous visual line |
|
||
| ~l l~ | open =log buffer= |
|
||
| ~n~ | next search occurrence |
|
||
| ~N~ | previous search occurrence |
|
||
| ~o~ | revert item at point |
|
||
| ~P u~ | push to tracked branch |
|
||
| ~P m~ | push to matching branch (e.g., upstream/develop to origin/develop) |
|
||
| ~q~ | quit |
|
||
| ~s~ | on a file or hunk in a diff: stage the file or hunk |
|
||
| ~x~ | discard changes |
|
||
| ~+~ | 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 or V~ | select multiple lines |
|
||
| ~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 editing buffer
|
||
In a commit message buffer press ~,c~ (if =dotspacemacs-major-mode-leader-key= is ~,~)
|
||
or ~C-c C-c~ to commit the changes with the entered message. Pressing ~,a~ or ~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
|
||
|
||
| Key Binding | Description |
|
||
|-------------+----------------|
|
||
| ~c~ or ~p~ | pick |
|
||
| ~e~ | edit |
|
||
| ~f~ | fixup |
|
||
| ~j~ | go down |
|
||
| ~M-j~ | move line down |
|
||
| ~k~ | go up |
|
||
| ~M-k~ | move line up |
|
||
| ~d~ or ~x~ | kill line |
|
||
| ~r~ | reword |
|
||
| ~s~ | squash |
|
||
| ~u~ | undo |
|
||
| ~y~ | insert |
|
||
| ~!~ | execute |
|
||
|
||
** 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~ or ~C-c C-c~ to submit the changes
|
||
- Squash last commit:
|
||
- ~l l~ to open =log buffer=
|
||
- ~r e~ on the second to last commit, it opens the =rebase buffer=
|
||
- ~j~ to put point on last commit
|
||
- ~s~ to squash it
|
||
- ~,c~ or ~C-c C-c~ to continue to the =commit message buffer=
|
||
- ~,c~ or ~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):
|
||
- ~M~ to open the =remote popup=
|
||
- ~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-Flow
|
||
[[https://github.com/jtatarik/magit-gitflow][magit-gitflow]] provides git-flow commands in its own magit menu.
|
||
|
||
| Key Binding | Description |
|
||
|-------------+-------------------------|
|
||
| ~%~ | open magit-gitflow menu |
|
||
|
||
** Git time machine
|
||
[[https://github.com/pidu/git-timemachine][git-timemachine]] allows to quickly browse the commits of the current buffer.
|
||
|
||
| Key Binding | Description |
|
||
|-------------+----------------------------------------------------|
|
||
| ~SPC g t~ | start git timemachine and initiate transient-state |
|
||
| ~c~ | show current commit |
|
||
| ~n~ | show next commit |
|
||
| ~N~ | show previous commit |
|
||
| ~p~ | show previous commit |
|
||
| ~q~ | leave transient-state and git timemachine |
|
||
| ~Y~ | copy current commit hash |
|
||
|
||
** Git links to web services
|
||
These key bindings allow to quickly construct URLs pointing to a given commit
|
||
or lines in a file hosted on Git web services like GitHub, GitLab, Bitbucket...
|
||
|
||
| Key Binding | Description |
|
||
|-------------+------------------------------------------------------------------------|
|
||
| ~SPC g l c~ | on a commit hash, browse to the current file at this commit |
|
||
| ~SPC g l C~ | on a commit hash, create link to the file at this commit and copy it |
|
||
| ~SPC g l l~ | on a region, browse to file at current lines position |
|
||
| ~SPC g l L~ | on a region, create a link to the file highlighting the selected lines |
|
||
|
||
*Notes:*
|
||
- You can use the universal argument ~SPC u~ to select a remote repository.
|
||
- 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= to
|
||
=nil=.
|
||
|
||
** Repository list
|
||
|
||
This feature will show a list of git directories. The feature needs slight
|
||
configuration within your `.spacemacs` config. In the `dotspacemacs/user-config()`
|
||
stanza insert the following with the directories of your choice:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(setq magit-repository-directories
|
||
'("~/Development"))
|
||
#+END_SRC
|
||
|
||
| Key Binding | Description |
|
||
|-------------+-----------------------------------------------------|
|
||
| ~SPC g L~ | start git repo list |
|
||
| ~RET~ | show the git status window for the selected project |
|
||
| ~gr~ | refresh the project list |
|