E macsAir

Collecting frequent-committer miles

Ghub 2.0 and Glab 2.0 released

I am excited to announce the release of Ghub version 2.0 and Glab 2.0, consisting of 115 commits since the last Ghub feature release four months ago.

Minuscule client library for the Github API

Ghub is a library that provides basic support for using the Github REST (v3) and GraphQL (v4) APIs from Emacs packages. It abstracts access to API resources using only a handful of functions that are not resource-specific.

Ghub handles the creation, storage and use of access tokens using a setup wizard to make it easier for users to get started and to reduce the support burden imposed on package maintainers. It also comes with a comprehensive manual to address the cases when things don’t just work as expected or in case you don’t want to use the wizard.

Ghub is intentionally limited to only provide these two essential features—basic request functions and guided setup—to avoid being too opinionated, which would hinder wide adoption. It is assumed that wide adoption would make life easier for users and maintainers alike, because then all packages that talk to the Github API could be configured the same way.

Likewise Glab does the same for Gitlab, except without support for GraphQL and automatic token creation, because Gitlab itself does not support these features.

Why another client library?

Ghub is less opinionated

I originally wrote Ghub two years ago for use by Emir, the primary tool I use to maintain the Emacsmirror.

Previously I had been using and contributing to Gh, but was having issues with it that made it desirable to start from scratch. In my opinion Gh is too—ahem—opinionated. It doesn’t return raw results but instead wraps them in Eieio objects and more awkwardly it also expects objects as input in some cases. But if that were the only issue I would probably have stuck to it. (Actually Gh was my first exposure to Eieio, which I really like by now and use in other packages. So thanks for that! I just don’t think it should have been used here.)

Additionally I got a lot of random errors when using Gh and never quite figured out who was to blame—might have been my own code, Gh, url.el or Github.com. At the time I though url.el was to be blamed and that Gh in turn was making it hard to figure out what was going on, though I might have been completely wrong. (Maybe now that I am more familiar with Eieio, its use would no longer make it hard for me to debug these issues.)

Since then I have been using Ghub to maintain the Emacsmirror and made small improvements over time. And then I decided that a lot of Github functionality should be available directly from within Magit. Which not only meant that I finally had to address all the minor issues I was having with Ghub but also that I had to improve the initial configuration.

Alternative interfaces can be layered on top of Ghub

One major issue that users of the various packages that accessed the Github API have, is that these packages all have different expectations on how the necessary tokens should be made available to them. Well not all—some use Gh—but many package authors decided to role their own, much like I had done too and I suspect they did so for similar reasons.

What better way to fix that situation than to implement yet another configuration mechanism?

I hope that’s not how this plays out. Keeping Ghub rather flexible and easy to build on was a major goal and I am hoping that other, more opinionated interfaces will be built on top. I am happy that one such interface, named simply Ghub+, already exist and it should be fairly simple to port Gh to use it too. (Could Someone™ please do that?)

Ghub comes with many features that should make it appealing to use it instead of the existing libraries. Or to use a library that is built on top of it.

Ghub comes with a setup wizard that automatically pops up when the required token is not available. This wizard works even if two-factor authentication is enabled. Of course users can also create and store the token manually if they prefer. But its existence should lessen the support burden imposed on maintainers and make it easier for users.

Tokens are stored using auth-source, which is the package that Emacs provides for that sort of thing, so using it seems like a good idea. That package is rather flexible and allows storing packages unencrypted for ease of use or encrypted if you would like to protect your secrets. It supports multiple backends including some popular keychains and can be extended to support even more.

And finally, Ghub comes with a manual. When using the wizard, then things should just work, but if it doesn’t, then the documentation comes in handy. Please do consult it.

Github support in Magit and Magithub

As mentioned before Magit is going to gain a lot of Github related functionality. I haven’t progresses very far with that yet, mostly because getting Ghub ready took longer than expected.

But at least Magit’s upcoming 2.12 release will contain some seemingly small features that make a huge difference at least in my own daily work.

The new magit-checkout-pull-request and magit-branch-pull-request commands (on b y and b Y) read a pull request in the minibuffer and then create a local branch for that. That branch is properly configured, including the upstream and push-remote. This makes it a breeze to review pull requests directly in Magit. (Though for the time being you will still have to provide feedback using the web interface, but see below.) You should also checkout the new magit-merge-into and magit-merge-absorb commands (on m i and m a). After merging a branch they also delete it and if the branch was created using one of the pull-request commands mentioned above (and some other conditions are met), then they also delete the respective remote.

Meanwhile the Magithub package provides a lot of the functionality that I want to add to Magit itself (and then some). It was written and is actively maintained by Sean Allred who is also the author of Ghub+. We have been collaborating for a while now. His feedback about Ghub was very useful and I think he feels the same about my feedback about Ghub+ and Magithub.

I like Magithub’s interface and it provides a lot of useful functionality but think it has some sharp edges concerning how Github data is fetched. Because of that I haven’t integrated it into my own workflow until very recently, but many users already have and the feedback seems to be very positive. Aside from some “offline mode” and performance issues I already like it a lot too.

Going forward I intend to keep collaborating with Sean to avoid duplicating efforts. Meanwhile I recommend that you give Magithub a try too. I will probably concentrate on data fetching and caching for a while before I turn my focus to user-visible features. This work will hopefully benefit Magithub and that in turn should benefit Magit. Maybe Magithub could even be merged into Magit one day, but it is to early to tell whether that will become feasible and be desirable.

Posted on 20th March 2018