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

#+TITLE: GitHub layer

[[file:img/github.png]]

* Table of Contents                                         :TOC_4_gh:noexport:
 - [[#description][Description]]
   - [[#features][Features:]]
 - [[#install][Install]]
   - [[#layer][Layer]]
   - [[#git-configuration][Git configuration]]
   - [[#hub-configuration][Hub configuration]]
 - [[#key-bindings][Key Bindings]]
   - [[#magit-gh-pulls][magit-gh-pulls]]
   - [[#magithub][magithub]]
   - [[#gistel][gist.el]]
   - [[#clone-repositories][Clone repositories]]

* 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/vermiculus/magithub][magithub]]: magit integrated interface to [[https://hub.github.com/][hub]] command line
- [[https://github.com/defunkt/gist.el][gist.el]]: full-featured mode to browse and post GitHub gists.
- [[https://github.com/sshaw/git-link][git-link]]: quickly generate URLs for commits or files.
- [[https://github.com/dgtized/github-clone.el][github-clone]] allows for easy cloning and forking of repositories.

* Install
** Layer
To use this configuration layer, add it to your =~/.spacemacs=. You will need to
add =github= to the existing =dotspacemacs-configuration-layers= list in this
file.

** Git configuration
You will need to generate a [[https://github.com/settings/tokens][personal access token]] on GitHub. This token should
have the =gist= and =repo= permissions. Once this token is created, it needs to
be added to your =~/.gitconfig=

#+BEGIN_SRC sh
  git config --global github.oauth-token <token>
#+END_SRC

** Hub configuration
For now, =Magithub= requires the =hub= utility to work -- before trying to use
Magithub, follow the installation instructions at hub.github.com. To force hub
to authenticate, you can use hub browse in a terminal (inside a GitHub repo).

* 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 (or reload) all PRs in the current repository |
| ~# f~       | fetch the commits associated with the current PR at point   |
| ~# b~       | create a branch for the current PR at point                 |
| ~# m~       | merge the PR with current branch at point                   |
| ~# d~       | show a diff of the current pull request at point            |
| ~# o~       | open PR at point in browser                                 |

Note that =magit-gh-pulls= will try to fast-forward the PRs whenever it is
possible.

** magithub

| Key Binding | Description                                      |
|-------------+--------------------------------------------------|
| ~@ H~       | opens the current repository in the browser      |
| ~@ c~       | pushes a brand-new local repository up to GitHub |
| ~@ f~       | create a fork of an existing repository          |
| ~@ p~       | submit pull request upstream                     |
| ~@ i~       | create an issue                                  |

** 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 /~ | search for a repository to clone it                      |
| ~SPC g h c c~ | clone and optionally fork repository                     |
| ~SPC g h c r~ | add a remote that is an existing fork of selected remote |
| ~SPC g h c f~ | fork remote in current user namespace                    |
| ~SPC g h c u~ | add upstream as remote                                   |