Intro to Hub: Improve Your GitHub Workflow with the CLI Tool

First thing's first, let's install hub.

You can install hub on most operating systems using the popular package managers. Across all repositories, the package name is "hub". See the example commands below.

Installation commands

Authentication

Before doing anything meaningful, you'll need to authenticate with GitHub. You will be prompted to authenticate the first time you run a command, so there actually isn't an action item for this step.

When you run a command, you'll be prompted for your GitHub username and password (and 2FA token, if applicable). Hub does not save these credentials, they simply exchange them for an oauth token, which is stored in ~/.config/hub.

To avoid being prompted you can also define environment variables setting your username and password: GITHUB_USER and GITHUB_PASSWORD. Or, if you're motivated, you can generate a token yourself and define a GITHUB_TOKEN environment variable.

Defining the protocol

The default protocol for git operations is ssh, but if you prefer https you can set it like this:

$ git config --global hub.protocol https

Like I mentioned in the introduction, hub wraps git. So many of the hub commands are just wrappers for git commands. If you want, you can use hub pretty much exclusively for most of your day-to-day work. I won't go into much detail on existing git commands in this step, but I will provide a few examples.

Of course, for any of these you can use either hub or git. So use whichever you prefer. In the remaining steps I'll cover hub-specific functionality.

One of the biggest time savers for me is the ability to open a pull request from the command-line. Without hub there is an odd workflow where you commit and push from the command-line, then switch to your browser to open a pull request and build releases. Hub allows us to manage the entire process in one place.

To open a PR, use the pull-request subcommand.

Basic usage

The easiest way to open a pull request is to use the command with no arguments.

$ hub pull-request

This will open your default text editor and give you the opportunity to add a title and description. Keep in mind

Here is where the title goes.

Anything below the title will be used as the description. **Markdown supported!**
# ------------------------ >8 ------------------------
# Do not modify or remove the line above.
# Everything below it will be ignored.

Requesting a pull to Howchoo:master from Howchoo:random-feature-branch

Write a message for this pull request. The first block
of text is the title and the rest is the description.

Upon saving the file, you'll see your confirmation with a link to the pull request.

$ hub pull-request
https://github.com/Howchoo/repo-name/pull/316

Advanced usage

There are a few command-line arguments that allow for more interesting usage.

Pass the message as an argument

Use -m to specify a message.

$ hub pull-request -m "This is the title"

If you specify multiple messages, they will be concatenated with a newline in between. So the first message will be used as the title, and any further messages will be used as the description.

$ hub pull-request -m "This is the title" -m "**First line of the description**"

Pass the message from a file

You can also read the message of a file with the -F argument.

$ hub pull-request -F message.txt

Similarly you can the file from standard input using -.

$ cat message.txt | hub pull-request -F -

More details

For more details you can type:

$ hub pull-request --help

You can also manage existing pull requests using hub.

List pull requests

To list pull requests use hub pr list.

$ hub pr list
    #323  Title for a pull request
    #302  Title for an older pull request

This will list only open PRs, but you can also specify any of the following states: "open", "closed", "merged", or "all".

Checkout a pull request

Suppose you want to check out an open PR to test or review. To do so, you can use hub pr checkout PR-NUMBER.

$ hub pr checkout 302

Show a pull request

As you'll see more later, some hub commands are shortcuts for opening GitHub URLs. One convenient shortcut is to open a pull request page from the command-line.

$ hub pr show 302

More details

For more details you can type:

$ hub pr --help

If your organization uses GitHub releases, this is another very powerful command. My teams use releases to trigger builds, so this command is a big timesaver.

List releases

To list releases simply type hub release.

$ hub release

Show release details

To see the release details, use hub release show TAG.

$ hub release show 1.0.31
1.0.31

## Changes

* Add new page

Create a release

Release creation is powerful. The most simple use case is to create a release from a specified tag. If the tag does not exist already, it will tag the current commit and push it.

$ hub release create 0.0.1

This process is similar to creating a pull request. With no arguments a text editor will open where you can specify the release title and description. And like pull requests, you can also pass in -F or -m to specify the message.

Delete a release

You can also delete releases using hub release delete TAG.

$ hub release delete 0.0.1

More details

There are a few more subcommands and arguments to check out. For more details you can type:

$ hub release --help

We've covered both pull requests and releases, and issues can be created and managed in a similar way.

List issues

$ hub issue
    #312  Issue name   label
    #307  Another issue name   label
    ...

Create an issue

Issue creation is the same as pull request and release creation. We can easily create issues with hub issue create.

$ hub issue create

Show an issue

$ hub issue show 312

As with other show subcommands, this will open a browser tab and take us to the page for this issue.

More details

There are a few more subcommands and arguments to check out. For more details you can type:

$ hub issue --help

There are more commands than I discussed in this guide, but hopefully at this point you've got what you need to get started. Learning the commands I laid out should be a good starting point for including hub into your tool set.