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]]
  - [[#forge][Forge]]
- [[#key-bindings][Key bindings]]
  - [[#forge-1][Forge]]
  - [[#gistel][gist.el]]
  - [[#clone-repositories][Clone repositories]]

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

** Features:
- [[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://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line][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

** Forge
The =forge= package uses =emacsql= which requires a C compiler to be available
on MS Windows, see issue [[https://github.com/skeeto/emacsql/issues/46]].

For this reason the =forge= package is not installed on MS Windows by default.
If you still want to install it (which means you do have a C compiler available
in your PATH) then use the =dotspacemacs-additional-packages= variable in your
dotfile:

#+BEGIN_SRC emacs-lisp
  (dotspacemacs-additional-packages '((forge :toggle t)))
#+END_SRC

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