Magithub – Magit interfaces for GitHub

You may also be interested in 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!

This manual is for Magithub version 0.1.5 (0.1.5-106-ge4a004c+1).

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.

Installation

_

Magithub can be installed from MELPA using M-x list-packages or by evaluating the following:

(package-install 'magithub)

Here is the basic recommended =use-package= configuration:

(use-package magithub
  :after magit
  :ensure t
  :config (magithub-feature-autoinject t))

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 Ghub’s manual for details.)

If you do use two-factor authentication, you must

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

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 Manually Creating and Storing a Token and How Ghub uses Auth-Source.

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

(require 'magithub)
(ghub-get "/user" nil :auth 'magithub)

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, open a Ghub issue or drop by Magithub’s or 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.

(use-package magithub
  :ensure t
  :config
  (magithub-feature-autoinject t)
  (setq magithub-github-hosts '("github.enterprise.domain/api/v3")))

Next, you will need to create a personal access token and add it to your ~/.authinfo file to authenticate to your domain; see Ghub’s manual for details.

machine github.enterprise.domain/api/v3 login YOUR_USERNAME^magithub password YOUR_GITHUB_TOKEN

Finally, for each github repository you with to use with GHE, you will need to add a github.host config and a DOMAIN.user config.

# where GHE_URL is the url to your v3 api endpoint, and USERNAME is your GHE username
GHE_URL=github.enterprise.domain/api/v3; git config github.host ${GHE_URL}; git config ${GHE_URL}.user $USERNAME

Introduction

_

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

M-x magithub-clone RET vermiculus/my-new-repository

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.

From here you will be prompted to add labels by selecting them from the list and adding them with RET. To skip adding labels and submit the issue without any you can enter “” in the field and then RET.

Note: your completion framework may have special functionality to enter null here (ie. in Ivy you must use =C-M-j= to accept without input).

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. Note that the branch must have a push-remote set in order to find the correct status to use.

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: O, magithub-issue-open
Key: C, magithub-issue-close
Open/close an issue.
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:

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

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

git config --global magithub.cache always

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.

‘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
```
(magithub-feature-autoinject t)
    
```
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:
```
(magithub-feature-autoinject 'commit-browse)
(magithub-feature-autoinject '(commit-browse pull-request-merge))
    
```

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

Key: H C x, magithub-settings–set-magithub.contextRemote
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

M-x apropos-command RET magithub-settings--set

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

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:

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

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:

Status:   Success

You can get a breakdown of which checks succeeded and which failed by using TAB:

Status:   Success
          Checks for ref: develop
          Success The Travis CI build passed continuous-integration/travis-ci/push

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

‘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 =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

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.

Files

magithub.org

Latest commit

History