3 GitHub Commandline Tools

Apr 4 2017

Sometimes it's nice to work with GitHub from the command line. This post covers three tools for working with GitHub: hub, ghi, and github-release.

Most of the time, when we work with GitHub, we use the main git client. This is great for working with source code, but what about interacting with other aspects of GitHub, like the issue queue, pull requests, or releases? There are a few tools for making this easier. I've picked the ones that are my favorites.

The General Tool: hub

The hub tool provides a bunch of utility functions for working with GitHub. It is designed to be aliased to the git command, but I typically don't do that. I like having it feel separate from Git.

Some of the commands hub provides are:

  • fork: Make a fork of an upstream repository, and then configure your fork as a repository
  • create: Take a local Git repo and create a new GitHub project for it.
  • pull-request: Create a pull request from the current branch.

I use pull-request frequently. My workflow looks something like this:

$ git checkout -b my fix    # Create a new branch
$ git commit -av            # Commit some changes
$ git push my fix           # Push my updates
$ hub pull-request          # Open a pull request with my changes

One feature of hub that I'm not wild about, but which others like, is its ability to open browser tabs for you. Commands like hub browse -- issues and hub compare v1.2.3 will take you directly to the GitHub website in your browser.

But when I'm working on the CLI, I often prefer to stay on the CLI, which is why I also like ghi.

Working With Issues, PRs, and Milestones: ghi

The ghi tool is for interacting with the GitHub issue queue, PR queue, and milestones. At its simplest, you can use ghi to list the issues for your project. From within my Git clone of a project, I can do this:

$ ghi
# Masterminds/structable open issues
  4: Tests need predictability
  3: Implement Hooks 1 ↑
  2: Hooks? 1

With many ghi operations, the same command can be used to work with issues or with pull requests. For example, ghi list -p will list pull requests.

The ghi tool provides commands to do (among other things) the following:

  • list lists issues (ghi list -s closed lists all closed issues).
  • show shows the details for an issue.
  • milestone shows a list of milestones, and provides other tools for viewing and editing milestones
  • open and close let you open and close issues from the command line. And you can edit an issue, too.
  • The label command allows you to create, delete, and manage GitHub labels.
  • You can add a comment to an issue with comment.

The ghi tool comes with lots of options, and can be very powerful. It can also be a little dangerous, since it's easy to modify issues and milestones.

Managing Releases: github-release

Frequently, I use Makefiles and CI/CD pipelines to automate building and testing my code. It's nice to be able to create GitHub releases in shell scripts and Makefiles, too. This is where github-release comes in.

The github-release tool focuses on only working with the release functionality of GitHub. For example, I can list all of the tags and releases for github.com/Masterminds/structable:

$ github-release info -u Masterminds -r structable
git tags:
- 3.1.0 (commit: https://api.github.com/repos/Masterminds/structable/commits/880b1df16ad730cd5c1400bb5a179906eaa99c9e)
- 3.0.0 (commit: https://api.github.com/repos/Masterminds/structable/commits/3d4d0f2e5da5dfaa579479b8c47e996cf4898a35)
- 2.0.0 (commit: https://api.github.com/repos/Masterminds/structable/commits/acebe8c0d2eca45de2ee6be1a71a8ca261871d6f)
- 1.0.0 (commit: https://api.github.com/repos/Masterminds/structable/commits/98d991a199a19c1e940d4beaa50adfdce9bacdc9)
error: no release(s) were found for Masterminds/structable ()

With github-release, you can perform the following actions on releases:

  • info gets release information
  • download downloads a release
  • release creates a new release
  • upload adds a downloadable file to a release
  • edit edits an existing release
  • delete removes a release

Note that for many of these, you will have to configure github-release to use your GitHub token for authentication.