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

#+TITLE: GitHub layer

#+TAGS: layer|versioning

[[file:img/github.png]]

* Table of Contents                     :TOC_5_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]]
  - [[#magithub][magithub]]
  - [[#forge][forge]]
  - [[#gistel][gist.el]]
  - [[#clone-repositories][Clone repositories]]

* Description
This layers adds support for [[http://github.com][GitHub]].

** Features:
- [[https://github.com/vermiculus/magithub][magithub]]: Magit-integrated interface to [[https://hub.github.com/][hub]] command line
- [[https://github.com/magit/forge][forge]]: integration with various forges, such as GitHub and GitLab.
- [[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
** 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                                  |

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

| Key binding | Description                                               |
|-------------+-----------------------------------------------------------|
| ~b Y~       | create branch from pull-request                           |
| ~b y~       | create and check out branch from pull-request             |
| ~F f~       | fetch issues and pull-requests                            |
| ~F n~       | fetch notifications                                       |
| ~F p~       | create pull-request                                       |
| ~F i~       | create issue                                              |
| ~F F~       | list notifications                                        |
| ~F P~       | list pull-requests                                        |
| ~F I~       | list issues                                               |
| ~p y~       | pull pull-requests and issues for the current repository  |
| ~p Y~       | pull all notifications for the current repository's forge |

In a =forge-topic= buffer:

| Key binding | Description     |
|-------------+-----------------|
| ~SPC m c~   | create new post |
| ~SPC m e~   | edit post       |

In a =forge-post= buffer (assuming the major mode leader key is ~,~)

| Key binding            | Description |
|------------------------+-------------|
| ~SPC m c~ or ~SPC m ,~ | submit post |
| ~SPC m k~ or ~SPC m k~ | cancel post |

** 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                                   |