spacemacs/layers/+source-control/github/README.org

#+TITLE: Github contribution layer for Spacemacs
#+HTML_HEAD_EXTRA: <link rel="stylesheet" type="text/css" href="../../../css/readtheorg.css" />

[[file:img/github.png]]

* Table of Contents                                         :TOC_4_org:noexport:
 - [[Description][Description]]
   - [[Features:][Features:]]
 - [[Install][Install]]
   - [[Layer][Layer]]
 - [[Key Bindings][Key Bindings]]
   - [[magit-gh-pulls][magit-gh-pulls]]
   - [[gist.el][gist.el]]
   - [[Clone repositories][Clone repositories]]
   - [[Browse files][Browse files]]

* Description

This layers adds support for [[http://github.com][Github]].

** Features:
- [[https://github.com/sigma/magit-gh-pulls][magit-gh-pulls]]: handy =magit= add-on to manage Github pull requests.
- [[https://github.com/defunkt/gist.el][gist.el]]: full-featured mode to browse and post Github gists.
- [[https://github.com/osener/github-browse-file][github-browse-file]] and [[https://github.com/sshaw/git-link][git-link]]: quickly browse github URL in your
  browser.
- [[https://github.com/dgtized/github-clone.el][Github clone]] allows for easy cloning and forking of repositories.

* Install

** Layer

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

#+BEGIN_SRC emacs-lisp
(setq-default dotspacemacs-configuration-layers '(github))
#+END_SRC

* Key Bindings

** magit-gh-pulls

In a =magit status= buffer (~SPC g s~):

| Key Binding | Description                                     |
|-------------+-------------------------------------------------|
| ~# c~       | create a pull request                           |
| ~# g~       | get a list of all PRs in the current repository |
| ~# f~       | fetch the commits associated to the current PR  |
| ~# b~       | create a branch for the current PR              |
| ~# 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        |

** Clone repositories

| Key Binding   | Description                          |
|---------------+--------------------------------------|
| ~SPC g h C-c~ | clone and optionally fork repository |

** Browse files

| Key Binding | Description                                                        |
|-------------+--------------------------------------------------------------------|
| ~SPC g h c~ | browse to file on github/bitbucket/etc (on current line at commit) |
| ~SPC g h C~ | only copy the generated link on the kill ring                      |
| ~SPC g h l~ | browse to file on github/bitbucket/etc (on current line position)  |
| ~SPC g h L~ | only copy the generated link on the kill ring                      |
| ~SPC g h o~ | browse to file on github                                           |

*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= to
  =nil=.