#+Title: Magithub -- Magit interfaces for GitHub
#+Author: Sean Allred

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

** Installation

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):

- `magithub-pull-request-checkout`
- `magithub-pull-request-merge`

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.

Other than that, Magithub can be installed from [[http://melpa.milkbox.net/#/magithub][MELPA]] using =M-x
list-packages= or by evaluating
#+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.

** Authentication

Magithub does not yet support running unauthenticated (and such support is
unlikely considering GitHub's heavy rate-limiting of unauthenticated
requests).  As such, you /must/ authenticate before you use Magithub.  (As of
#107, Magithub will not even attempt go online until you're properly
authenticated.)

Authentication is completely managed by =ghub=, so see its README for
instructions.

* Documentation
** Interface
| Default Key | Description                        |
|-------------+------------------------------------|
| =H `=         | Toggle Magithub-Status integration |

*** Manipulating the Cache
When point is on a Magithub-controlled section (like the status header):
| Default Key | Description                            |
|-------------+----------------------------------------|
| =g=           | Refresh this section only              |
| =C-u g=       | Like =g=, but works even in offline mode |

Everywhere:
| Default Key | Description             |
|-------------+-------------------------|
| =H g=         | Refresh all GitHub data |

=H g= should only be used as a last resort; it completely nukes the cache
across all repositories (meaning all data will have to be re-retrieved).

See also the variable documentation for =magithub-cache=.

*** Offline Mode
| Default Key | Description         |
|-------------+---------------------|
| =H O=         | 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, throw ~(setq magithub-cache t)~ in your
configuration.  See that variable's documentation for details.

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

** Content
*** Working with Repositories
**** 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=).

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

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

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

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

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

** Using a Proxy

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.

| Default Key | Description                            |
|-------------+----------------------------------------|
| =H x=         | Set a proxy for all GitHub information |

* FAQ
** How do I authenticate?
GitHub authentication is handled by =ghub= -- its README includes [[https://github.com/magit/ghub#initial-configuration][instructions
on how to authenticate]].  In the interest of not duplicating documentation
(and risking this duplication to fall out of date), I will not repeat those
instructions here.

To verify that you're authenticated, evaluate the following expression:
#+BEGIN_SRC emacs-lisp
  (ghub-get "/user")
#+END_SRC
If this returns an alist that has some familiar information (like your
login, email, bio, and location), you should be good to go!

If you're still having trouble after reading [[https://github.com/magit/ghub#initial-configuration][=ghub='s README]], feel free to
drop by [[https://gitter.im/vermiculus/magithub][Magithub's Gitter room]] and ask the question there.

** I've authenticated, but some features are still not authorized.
You might need to configure your personal access token with more
permissions.  [[https://github.com/settings/tokens][Manage these permissions on GitHub.]]  Currently, I recommend
giving your token all of the following permissions:
- =admin:org=
- =gist=
- =notifications=
- =repo=
- =user=

** What's this 'Magithub features not configured' message?
Sometimes, Magithub might complain that you haven't turned on certain
features.  These features are those pieces of functionality that are
injected into Magit's internal popups by =magithub-feature-autoinject=.  In
order to play nice with the ecosystem, Magithub doesn't turn these features
on by default (see the conversation around #42).  Since pulling
functionality out of popups is currently infeasible with standard API,
Magithub had to instead provide a way to introduce these features manually.

'Turning on a feature' only involves =magithub-feature-autoinject=.  For
example, to turn on the PR Merge feature:
#+BEGIN_SRC emacs-lisp
  (magithub-feature-autoinject 'pull-request-merge)
#+END_SRC
This inserts the feature into =magithub-features= and places it in the
appropriate popup.

To turn on all features, use ~(magithub-feature-autoinject t)~.

If for some reason you don't want to use a feature, see the documentation
for =magithub-features= for instructions on how to disable specific (or all)
messages.

** Does Magithub work for Enterprise instances?

Yes, but it's entirely tested by you folks.  I don't have access to an
Enterprise to test against, so YMMV.  (There is one obscure bug here (#115)
but you're unlikely to run into it.)

* Shameless Plugs

Magithub is made possible by [[https://github.com/vermiculus/ghub-plus][=ghub+=]] via [[https://github.com/vermiculus/apiwrap.el][=API-Wrap.el=]] over [[https://www.github.com/magit/ghub][=magit/ghub=]].

* Prior Art

- The [[https://hub.github.com][=hub=]] command-line tool also hopes to add smarts to working with GitHub
  repositories.  Magithub used to be based on this tool, so it's certainly
  an honorable mention.


# Local Variables:
# fill-column: 76
# End:
