271 lines
13 KiB
Org Mode
271 lines
13 KiB
Org Mode
#+TITLE: Git contribution layer for Spacemacs
|
|
#+HTML_HEAD_EXTRA: <link rel="stylesheet" type="text/css" href="../../../css/readtheorg.css" />
|
|
|
|
|
|
[[file:img/git.png]]
|
|
|
|
* Table of Contents :TOC_4_org:noexport:
|
|
- [[Description][Description]]
|
|
- [[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][Git-Flow]]
|
|
- [[Git time machine][Git time machine]]
|
|
|
|
* Description
|
|
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 [[http://magit.vc/about.html][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 A~ | show cherry-pick prompt |
|
|
| ~SPC g b~ | open a =magit= blame |
|
|
| ~SPC g B~ | quit =magit= blame |
|
|
| ~SPC g c~ | commit changes |
|
|
| ~SPC g C~ | checkout branches |
|
|
| ~SPC g d~ | show diff prompt |
|
|
| ~SPC g D~ | show diff against current head |
|
|
| ~SPC g e~ | show ediff comparison |
|
|
| ~SPC g E~ | show ediff against current head |
|
|
| ~SPC g f~ | show fetch prompt |
|
|
| ~SPC g F~ | show pull prompt |
|
|
| ~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~ | git init a given directory |
|
|
| ~SPC g I~ | open =helm-gitignore= |
|
|
| ~SPC g l~ | open a =magit= log |
|
|
| ~SPC g L~ | display the log for a file |
|
|
| ~SPC g r~ | show rebase prompt |
|
|
| ~SPC g P~ | show push prompt |
|
|
| ~SPC g s~ | open a =magit= status window |
|
|
| ~SPC g S~ | stage current file |
|
|
| ~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~
|
|
|
|
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 |
|
|
| ~gj~ | move line down |
|
|
| ~k~ | go up |
|
|
| ~gk~ | 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 |
|
|
|
|
# LocalWords: unpulled
|