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]]
  - [[#magithub-configuration][Magithub 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=

You will also need to [[https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/][generate an SSH key]] and [[https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/][add it to your GitHub account]].

#+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).

** Magithub configuration
Spacemacs configures =Magithub= to be in offline mode by default and disables
displaying the GitHub project status, issues, and pull requests because loading
project data for repositories with many pull requests or issues can be
exorbitantly slow (see [[https://github.com/syl20bnr/spacemacs/issues/11176][issue #11176]]). To toggle online mode and the project
status, issues, and pull requests sections for the current repository, open in
the =magit status= buffer (~SPC g s~) and then open the Magithub settings popup
(~@ C~). To enable online mode and the project status, pull requests, and
issues sections by default, use the following shell commands:

#+BEGIN_SRC sh
  git config --global --bool magithub.online true
  git config --global --bool magithub.status.includeStatusHeader true
  git config --global --bool magithub.status.includePullRequestsSection true
  git config --global --bool magithub.status.includeIssuesSection true
#+END_SRC

Alternatively, use the following Emacs forms:

#+BEGIN_SRC emacs-lisp
  (magit-set "true" "--global" "magithub.online")
  (magit-set "true" "--global" "magithub.status.includeStatusHeader")
  (magit-set "true" "--global" "magithub.status.includePullRequestsSection")
  (magit-set "true" "--global" "magithub.status.includeIssuesSection")
#+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 (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                                      |
|-------------+--------------------------------------------------|
| ~@ C~       | open the Magithub settings popup                 |
| ~@ 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                                   |