145 lines
6.9 KiB
Org Mode
145 lines
6.9 KiB
Org Mode
#+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]]
|
||
- [[#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 |
|
||
|
||
** 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 |
|