#+TITLE: Magithub -- Magit interfaces for GitHub
#+AUTHOR: Sean Allred
#+EMAIL: code@seanallred.com
#+DATE: 2017-2018
#+LANGUAGE: en

#+TEXINFO_DIR_CATEGORY: Emacs
#+TEXINFO_DIR_TITLE: Magithub: (magithub).
#+TEXINFO_DIR_DESC: Magit interfaces for GitHub
#+SUBTITLE: for version 0.1.5 (0.1.5-106-ge4a004c+1)
#+BIND: ox-texinfo+-before-export-hook ox-texinfo+-update-version-strings

#+TEXINFO_DEFFN: t
#+OPTIONS: H:4 num:4 toc:2

You may also be interested in [[https://github.com/vermiculus/magithub/tree/master/RelNotes][the most current release notes]].

Magithub provides an integrated GitHub experience through Magit's familiar
interface.  Just as Magit hopes to 'outsmart git', Magithub hopes to add
smarts to GitHub for performing common tasks.

Happy hacking!

#+TEXINFO: @noindent
This manual is for Magithub version 0.1.5 (0.1.5-106-ge4a004c+1).

#+BEGIN_QUOTE
Copyright (C) 2017-2018 Sean Allred <code@seanallred.com>

You can redistribute this document and/or modify it under the terms
of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any
later version.

This document is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.
#+END_QUOTE

* Installation
** _ :ignore:

Magithub can be installed from [[http://melpa.milkbox.net/#/magithub][MELPA]] using =M-x list-packages= or by
evaluating the following:

#+BEGIN_SRC elisp
  (package-install 'magithub)
#+END_SRC

Here is the basic recommended [[https://github.com/jwiegley/use-package][=use-package=]] configuration:

#+BEGIN_SRC elisp
  (use-package magithub
    :after magit
    :ensure t
    :config (magithub-feature-autoinject t))
#+END_SRC

If you prefer to install the package manually, this can of course be done
via the usual means.

For more information, see [[info:emacs#Packages]].

** Authentication

Given GitHub's rate-limiting policy, Magithub is unlikely to ever support
running without authenticating.  As such, you /must/ authenticate before you
use Magithub.  (As of #107, Magithub will not even attempt go online until
you're properly authenticated.)

To authenticate, you can simply start using Magithub; Ghub should walk you
through the authentication process unless you use two-factor authentication.
(Your token is stored in one of your ~auth-sources~; see [[https://magit.vc/manual/ghub/How-Ghub-uses-Auth_002dSource.html#How-Ghub-uses-Auth_002dSource][Ghub's manual]] for
details.)

If you do use two-factor authentication, you must

1. Manually create a GitHub token (from https://github.com/settings/tokens)
   for scopes `repo`, `notifications` and `user` (see variable
   ~magithub-github-token-scopes~)
2. Store it for Magithub per user in one of your ~auth-sources~
   (e.g. =~/.authinfo=).  Write a line like this:

   #+BEGIN_EXAMPLE
   machine api.github.com login YOUR_GITHUB_USERNAME^magithub password YOUR_GITHUB_TOKEN
   #+END_EXAMPLE

Beware that writing the token in plaintext in =~/.authinfo= (or elsewhere) is
not secure against attackers with access to that file.  For details and
better alternatives (like using GPG), see Ghub's manual on [[https://magit.vc/manual/ghub/Manually-Creating-and-Storing-a-Token.html#Manually-Creating-and-Storing-a-Token][Manually Creating
and Storing a Token]] and [[https://magit.vc/manual/ghub/How-Ghub-uses-Auth_002dSource.html#How-Ghub-uses-Auth_002dSource][How Ghub uses Auth-Source]].

If you want to authenticate Ghub without using Magithub, you can simply
evaluate the following:

#+BEGIN_SRC emacs-lisp
  (require 'magithub)
  (ghub-get "/user" nil :auth 'magithub)
#+END_SRC

After Ghub walks you through the authentication process during evaluation,
the ~ghub-get~ form should return familiar information (your login, email,
etc.).

If you're having trouble /authenticating/, [[https://github.com/magit/ghub/issues/new][open a Ghub issue]] or drop by
[[https://gitter.im/vermiculus/magithub][Magithub's]] or [[https://gitter.im/magit/magit][Magit's]] Gitter channel.

** Enterprise Support

For GitHub Enterprise support, you'll need to add your enterprise domain to
~magithub-github-hosts~ so that Magithub can detect when it's in a GitHub
repository.  You will also need to configure your =~/.authinfo= file
appropriately to authenticate to your domain; see Ghub's manual for details.

* Introduction
** _ :ignore:

Magithub tries to follow closely Magit's lead in general interface.  Most of
its functionality is developed to tightly integrate with its section/
framework.  See [[https://magit.vc/manual/magit/Sections.html#Sections][Magit's documentation]] for information on how to navigate
using this framework.

Magithub's functionality uses section-specific keymaps to expose
functionality.  Where it makes sense, the following keys will map to
functions that 'do the right thing':

- Key: w, magithub-browse-thing

  Open a browser to the thing at point.  For instance, when point is on
  issue 42 in your-favorite/github-repo, we'll open
  =http://github.com/your-favorite/github-repo/issue/42=.

- Key: a, magithub-add-thing

  Add something to the thing at point.  For instance, on a list of labels,
  you can add more labels.

- Key: e, magithub-edit-thing

  Edit the thing at point, such as an issue.

- Key: r, magithub-reply-thing

  Reply to the thing at point, such as a comment.

Magithub also considers the similar placeholder commands introduced by Magit
which you may already be familiar with:

- Key: k, magit-delete-thing
- Key: RET, magit-visit-thing

These concepts are intended to provide a more consistent experience
throughout Magithub within Magit by categorizing your broader interactions
with all GitHub content.  As with Magit, more commands are added as the
situation calls for it.

** Note

By default, Magithub enables itself in all repositories where =origin= points
to GitHub.

- User Option: magithub-enabled-by-default

  When non-nil, Magithub is enabled by default.  This is the fallback value
  of git variable =magithub.enabled= is not set in this repository.

- User Option: magithub-github-hosts

  A list of top-level domains that should be recognized as GitHub hosts.

** Brief Tutorial

Here's a script that will guide you through the major features of Magithub.
This is not a replacement for the documentation, but rather an example
workflow to whet your appetite.

*** Clone a repository
#+BEGIN_EXAMPLE
M-x magithub-clone RET vermiculus/my-new-repository
#+END_EXAMPLE
Cloning a repository this way gets the clone URL from GitHub and forwards
that on to ~magit-clone~.  If the repository is a fork, you're prompted to add
the parent is added under the =upstream= remote.

Fork behavior may change in the future.  It may be more appropriate to
actually/ clone the source repository and add your remote as a fork.  This
will cover the 90% case (the 10% case being active forks of unmaintained
projects).

*** Viewing project status
You are dropped into a status buffer for =vermiculus/my-new-repository=.  You
see some open issues and pull requests.  You move your cursor to an issue of
interest and =TAB= to expand it, seeing the author, when it was
created/updated, any labels, and a preview of the issue contents.

If =vermiculus/my-new-repository= used any status checks, you would see those
statuses as a header in this buffer.

*** Viewing and replying to an issue
You =RET= on the issue and are taken to a dedicated buffer for that issue.
You can now see its full contents as well as all comments.  You'd like to
leave a comment -- a suggestion for a fix or an additional use-case to
consider -- you press =r= to open a new buffer to /reply/ to this issue.  You
write your comment and =C-c C-c= to submit.  But, oh no!  You didn't turn on
=flyspell-mode= in markdown buffers, so you submitted a spelling error.  A
simple =e= on the comment will /edit/ it.  After submitting again with =C-c C-c=,
everything is well.

Right now, other activity on the issue is not inserted into this buffer.
Press =w= to open the issue in your browser.

*** Creating an issue
You notice a small issue in how some feature is implemented, so back in the
status buffer, you use =H i= to create a new issue.  (While inside the GitHub
repository, you could've used any key bound to ~magithub-issue-new~.)  The
first line is the title of the new issue; everything else is the body.  You
submit the issue with =C-c C-c=.

You come back a little while later to leave additional details -- you reply
to your own issue in a comment, but realize you should just edit your
original issue to avoid confusion.  You =k= to /kill/ / delete the comment.

*** Creating a pull request
Since you care about this project and want to help it succeed, you decide to
fix this issue yourself.  You checkout a new branch (=b c my-feature RET=) and
get to work.

Because you're so /awesome/, you're ready to push your commit to fix your
issue.  After realizing you don't have push permissions to this repository,
you create a fork using =H f=.  You push your branch to your new remote (named
after your username) and create a pull request with =H p=.  You select the
head branch as =my-feature= and the base branch as =master= (or whatever the
production/staging branch is for the project).  You fill out the pull
request template provided by the project (and inserted into your PR) and off
you go!

* Status Buffer Integration

The part of Magithub you're likely to interact with the most is
embedded right into Magit's status buffer.

- Key: H, magithub-dispatch-popup

  Access many Magithub entry-points.  See [[*Dispatch Popup]] for more details.

- Key: H C e, FIXME

  Toggle status buffer integration in this repository.

There are two integrations turned on by default:

** Project Status

Many services (such as Travis CI and CircleCI) will post statuses to
commits.  A summary of these statuses are visible in the status buffer
headers.

- Key: RET, magithub-ci-visit
- Key: w, magithub-ci-visit

  Visit the service's summary of this status.  For example, a status posted
  by Travis CI will open that build on Travis.

- Key: g, magithub-ci-refresh

  Refresh statuses from GitHub and then refresh the current buffer.

- Key: H C s, FIXME

  Enable/disable status checks in this repository.

** Open Issues and Pull Requests

These will also display in the status buffer.  There's a lot of
functionality available right from an issue section.

- Key: g, magithub-issue-refresh

  Refresh issues and pull requests from GitHub and then refresh the current
  buffer.

- Key: RET, magithub-issue-visit

  Open a new buffer to view an issue and its comments.

- Key: w, magithub-issue-browse
- Key: w, magithub-pull-browse

  Browse this issue / pull request on GitHub.

- Key: N, magithub-issue-personal-note

  Opens a buffer for offline note-taking.

- Key: L, magithub-issue-add-labels

  Add labels to the issue.

- Key: a, magithub-label-add
- Key: k, magithub-label-remove

  When point is on a label section, you can add/remove labels (provided you
  have permission to do so).

- Command: magithub-label-color-replace

  Labels are colored as they would be on GitHub.  In some themes, this
  produces an illegible or otherwise undesirable color.  This command can
  help you find a substitute for labels of this color.

- Variable: magithub-issue-details-hook

  Control which issue details display in the status buffer.  Functions
  intended for this variable use the =magithub-issue-detail-insert-*= prefix.

  Performance note: judicious use of this variable can improve your overall
  Magit experience in large buffers.

- User Option: magithub-issue-issue-filter-functions
- User Option: magithub-issue-pull-request-filter-functions

  These are lists of functions which must all return non-nil for an issue/PR
  to be displayed in the status buffer.  They all receive the issue/PR
  object as their sole argument.  For example, you might want to filter out
  issues labels =enhancement= from your list:

  #+BEGIN_SRC emacs-lisp
    (setq magithub-issue-issue-filter-functions
          (list (lambda (issue)          ; don't show enhancement requests
                  (not
                   (member "enhancement"
                           (let-alist issue
                             (ghubp-get-in-all '(name) .labels)))))))
  #+END_SRC

*** Manipulating the Cache
    When point is on a Magithub-controlled section (like the status header):
    | Default Key | Description                                |
    |-------------+--------------------------------------------|
    | =g=           | Refresh only this section's GitHub content |
    | =C-u g=       | Like =g=, but works on the whole buffer      |

*** Offline Mode
    | Default Key | Description         |
    |-------------+---------------------|
    | =H C c=       | Toggle offline mode |

    Offline mode was introduced for those times when you're on the go, but you'd
    still like to have an overview of GitHub data in your status buffer.  It's
    also useful for folks who want to explicitly control when Emacs communicates
    with GitHub -- for this purpose, you can use =C-u g= (discussed above) to pull
    data from GitHub while in offline mode.

    To start into offline mode everywhere, use
    #+BEGIN_SRC sh
    git config --global magithub.cache always
    #+END_SRC

    See the documentation for function ~magithub-settings--set-magithub.cache~
    for details on appropriate values.

*** Controlling Sections

    Sections like the issue list and the status header can be toggled with the
    interactive functions of the form =magithub-toggle-*=.  These functions have
    no default keybinding.

    Since status checks can be API-hungry and not all projects use them, you can
    disable the status header at the repository-level with =H ~=; see the Status
    Checks section for more information.

* Dispatch Popup

Much of Magithub's functionality, including configuration options, is behind
this popup.  In Magit status buffers, it's bound to =H=.

- Key: d, magithub-dashboard

  See [[*Dashboard]].

- Key: c, magithub-create

  Push a local repository up to GitHub.

- Key: H, magithub-browse

  Open the current repository in your browser.

- Key: f, magithub-fork

  Fork this repository on GitHub.  This will add your fork as a remote under
  your username.  For example, if user =octocat= forked Magit, we would see a
  new remote called =octocat= pointing to =octocat/magit=.

- Key: i, magithub-issue-new
- Key: p, magithub-pull-request-new

  Open a new buffer to create an issue or open a pull request.  See
  [[*Creating Content]].

** Configuration

Per-repository configuration is controlled via git variables reachable from
the dispatch popup via =H C=.  Use =? <key>= to get online help for each
variable in that popup.

- Key: C e, FIXME

  Turn Magithub on/off (completely).

- Key: C s, FIXME

  Turn the project status header on/off.

- Key: C c, FIXME

  Control whether Magithub is considered 'online'.  This controls the
  behavior of the the cache.  This may go away in the future.  See
  [[*Manipulating the Cache]] for more details.

- Key: C i, FIXME

  Toggle the issues section.

- Key: C p, FIXME

  Toggle the pull requests section.

- Key: C x, FIXME

  Set the 'proxy' used for this repository.  See [[*Proxies]].

** Meta

Since Magithub is so integrated with Magit, there's often confusion about
whom to ask for support (especially for users of preconfigured Emacsen like
Spacemacs and Prelude).  Hopefully, these functions can direct you to the
appropriate spot.

- Key: &, magithub--meta-new-issue

  Open the browser to create a new issue for Magithub functionality
  described in this document.

- Key: h, magithub--meta-help

  Open the browser to ask for help on Gitter, a GitHub-focused chatroom.

* 'Features'

Given that some features of Magithub are not desired by or appropriate for
every type of user, there are features that are not turned on by default.
These are features that are injected into standard Magit popups.

The list of available features is available in constant
~magithub-feature-list~.  Despite its name, this is an alist of symbols (i.e.,
'features') to functions that install the feature.  While the documentation
for each feature lives in that symbol, you would normally not otherwise
interact with it.

- Function: magithub-feature-autoinject

  This function is the expected interface to install features.  You will
  normally use
  #+BEGIN_SRC emacs-lisp
    (magithub-feature-autoinject t)
  #+END_SRC
  in your configuration to install all features, but you have the option of
  installing them one at a time using the symbols from constant
  ~magithub-feature-list~ or as a list of those symbols:
  #+BEGIN_SRC emacs-lisp
    (magithub-feature-autoinject 'commit-browse)
    (magithub-feature-autoinject '(commit-browse pull-request-merge))
  #+END_SRC

* Cloning

- Command: magithub-clone

  Clone a repository from GitHub.

- User Option: magithub-clone-default-directory

  The default destination directory to use for cloning.

- User Option: magithub-preferred-remote-method

  This option is a symbol indicating the preferred cloning method (between
  HTTPS, SSH, and the =git://= protocol).

* Dashboard

The dashboard shows you information pertaining to /you/:
- notifications
- issues and pull requests you're assigned per repository
as well as contextual information like the logged-in user and [[https://developer.github.com/v3/#rate-limiting][rate-limiting]]
information.

- Command: magithub-dashboard

  View your dashboard.

- Key: ;, magithub-dashboard-popup

  Configure your global dashboard settings.

- User Option: magithub-dashboard-show-read-notifications

  When non-nil, we'll show read notifications in the dashboard.

* Creating Content

It's great to read about what's been happening, but it's even better to
contribute your own thoughts and activity!

- Key: H i, magithub-issue-new
- Key: H p, magithub-pull-request-new

  Create issues and pull requests.  If you have push access to the
  repository, you'll have the opportunity to add labels before you submit
  the issue.

  Creating a pull request requires a HEAD branch, a BASE branch, and to know
  which remote points to your fork.

- Key: r, magithub-comment-new
- Key: r, magithub-comment-reply

  On an issue or pull request section, ~magithub-comment-new~ will allow you
  to post a comment to that issue/PR.  If point is already on a comment,
  ~magithub-comment-reply~ will quote the comment at point for you.

* Caching

Caching is a complicated topic with a long Magithub history of, well,
failure.  As of today, all data retrieved from the API is cached by
default.  Using =g= on Magithub sections will usually refresh the information
in the buffer pertaining to that section.  Otherwise, =C-u g= in any Magit
buffer will refresh all GitHub data in that buffer.

This behavior may change in the future, but for now, it's the most stable
option.  See

* Proxies

It's not uncommon to have repositories where the bug-tracker is in a
separate repository.  For these cases, you can use the idea of 'proxies'.  A
proxy is a remote (with a GitHub-associated URL) that you choose to use for
all GitHub API requests concerning the /actual/ current repository.  This is
manifest in the git variable =magithub.proxy=.

- Function: magithub-proxy-set-default

  If you consistently use a specific remote name for the bug tracker, you
  can set it globally.

All GitHub requests specific to the current repository context are routed
through ~magithub-repo~ which respects this proxy.

* Configuring

Magithub uses a standardized configuration scheme implemented using Git
variables.  This allows your Magithub configuration to use all the powerful
features of =git-config(1)= and allows tight integration into Magit's existing
repository configuration workflows.

To get the most up-to-date list of configuration options, use
#+BEGIN_SRC example
M-x apropos-command RET magithub-settings--set
#+END_SRC
to summarize them all.  If an important option is missing from this manual,
reports and pull requests are welcome!

The decision to implement these as Git variables stems from the varying size
of project repositories: it is extremely common to contribute to
exceptionally large repositories where including, say, the 'issues' section
would bring Emacs to its knees -- but it is equally common to work on
smaller repositories where such concern is negligible and the issues section
is a nice feature.

* Unfiled
** Content
*** Working with Repositories
**** DONE General
| Default Key        | Description                                    |
|--------------------+------------------------------------------------|
| =H H=                | Opens the current repository in the browser    |
| =H c=                | Creates the current local repository on GitHub |
| =M-x magithub-clone= | Clone a repository                             |

=magithub-clone= may appear to be a thin wrapper over =magit-clone=, but it's
quite a bit smarter than that.  We'll of course respect
=magithub-preferred-remote-method= when cloning the repository, but we can
also detect when the repository is a fork and can create and set an upstream
remote accordingly (similar to =M-x magithub-fork=).

**** DONE Issues
| Default Key | Description              |
|-------------+--------------------------|
| =H i=         | Create a new issue       |
| =RET=         | Open the issue in GitHub |

You can filter issues with =magithub-issue-issue-filter-functions=:
#+BEGIN_SRC emacs-lisp
  (setq magithub-issue-issue-filter-functions
        (list (lambda (issue) ; don't show enhancement requests
                (not
                 (member "enhancement"
                         (let-alist issue
                           (ghubp-get-in-all '(name) .labels)))))))
#+END_SRC
Each function in the =*-functions= list must return non-nil for the issue to
appear in the issue list.  See also the documentation for that variable.

**** DONE Forking and Pull Requests
| Default Key | Description                   |
|-------------+-------------------------------|
| =H f=         | Fork the current repository   |
| =H p=         | Submit pull requests upstream |

You can also filter pull requests with
=magithub-issue-pull-request-filter-functions=.  See the section on
issue-filtering for an example.

**** TODO Labels
| Default Key                      | Description                               |
|----------------------------------+-------------------------------------------|
| =M-x magithub-label-color-replace= | Choose a new color for the label at point |

By default, Magithub will adopt the color used by GitHub when showing
labels.  In some themes, this doesn't provide enough contrast.  Use =M-x
magithub-label-color-replace= to replace the current label's color with
another one.  (This will apply to all labels in all repositories, but will
of course not apply to all /shades/ of the original color.)

**** TODO Status Checks
| Default Key | Description                                      |
|-------------+--------------------------------------------------|
| =RET=         | Visit the status's dashboard in your browser     |
| =TAB=         | On the status header, show individual CI details |
| =H ~=         | Toggle status integration for this repository    |

When the status buffer first opens, the status header is inserted at the top
and probably looks something like this:
#+BEGIN_EXAMPLE
Status:   Success
#+END_EXAMPLE

You can get a breakdown of which checks succeeded and which failed by using
=TAB=:
#+BEGIN_EXAMPLE
Status:   Success
          Checks for ref: develop
          Success The Travis CI build passed continuous-integration/travis-ci/push
#+END_EXAMPLE

Pressing =RET= on the header will take you to the dashboard associated with
that status check.  If there's more than one status check here, you'll be
prompted to choose a check (e.g., Travis, Circle, CLA, ...).  Of course, if
you expand the header to show the individual checks, =RET= on those will take
you straight to that check.

*** TODO Your Dashboard
Check out =M-x magithub-dashboard= to view your notifications and issues
assigned to you

** TODO 'Tricks'

Most of Magithub is implemented in pure Elisp now, but there are a few
lingering goodies that haven't been ported (since their real logic is
non-trivial).  These definitions are relegated to =magithub-issue-tricks.el=.

Make sure to install [[https://hub.github.com][=hub=]] and add it to your ~exec-path~ if you intend to use
these functions.  After installation, use =hub browse= from a directory with a
GitHub repository to force the program to authenticate -- this avoids some
weirdness on the Emacs side of things.

* _ Copying
:PROPERTIES:
:COPYING:    t
:END:

#+BEGIN_QUOTE
Copyright (C) 2017-2018 Sean Allred <code@seanallred.com>

You can redistribute this document and/or modify it under the terms
of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any
later version.

This document is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.
#+END_QUOTE

* _ :ignore:

# IMPORTANT: Also update ORG_ARGS and ORG_EVAL in the Makefile.
# Local Variables:
# fill-column: 76
# eval: (require 'ox-extra nil t)
# eval: (require 'ox-texinfo+ nil t)
# eval: (and (featurep 'ox-extra) (ox-extras-activate '(ignore-headlines)))
# indent-tabs-mode: nil
# org-src-preserve-indentation: nil
# End:
