Hub: A CLI for GitHub

Tonight I want to introduce you to hub, a command-line wrapper for Git that provides useful commands for handling projects hosted on GitHub. If you use GitHub a lot, which personally I do, then there is a good chance you will find hub to be a useful tool.

Installation

Installing hub is simple and straight-forward. However, I want to make one important note. The official site suggests aliasing hub to git, i.e.

$ alias git=hub

By doing so you can use hub’s commands as if they were native to Git. I do not recommend this. Hub makes some changes to the way certain Git commands work, e.g. git checkout. Personally I think it is a better idea to not create that alias so that the behavior of hub will not conflict with future changes to Git. So without the alias you would use hub checkout instead of git checkout, and I will be using the un-aliased program in all examples throughout this article.

Finally, I strongly recommend you run this command:

$ git config --global github.user "your-username"

This will make it less tedious to run certain commands. You can also configure github.password, github.token, and github.oauth-token while you’re at it.

Using Hub to Easily Contribute to Projects

Let’s say I want to contribute to lice, a program which generates license files for software—I’ve become co-maintainer of that project actually.

The first step is to create a local clone of the project:

$ hub clone licenses/lice

This is equivalent to the following:

$ git clone https://github.com/licenses/lice

In otherwords, hub clone provides a shortcut for clone GitHub projects by allowing you to use simply user/project as the name for whatever you wish to clone.

After cloning the project and making some patches you’ll need to create a fork on your GitHub page so that you can send a pull-request. To do so:

$ hub fork

That’s it. In my case this would create a new fork at https://github.com/ejmr/lice.

Now you can push your changes to your fork, using the standard command:

$ git push your-username HEAD    # Or the branch name.

Then to create a pull-request simply run:

$ hub pull-request

Pretty easy, huh?

Using Hub to Easily Manage Projects

Let’s say three people create forks of PHP Mode to submit pull-requests. Inside my local clone of the project I can fetch their work like so:

$ hub fetch foo, bar, baz

This is the same as running:

$ git add remote foo git://github.com/foo/php-mode.git
$ git add remote bar git://github.com/bar/php-mode.git
$ git add remote baz git://github.com/baz/php-mode.git
$ git fetch --multiple foo bar baz

I can then view their changes locally. Or if I want, I can also open their changes in my browser using GitHub’s compare functionality like so:

$ hub compare foo

When I want to apply their changes I have a number of options. If their pull-request contains only a single commit then I can do this:

$ git checkout master
$ hub am https://github.com/foo/php-mode/commit/938fac

This will apply that single commit to master.

If the pull-request has multiple commits then I can first checkout the pull-request like so:

$ hub checkout https://github.com/bar/php-mode/pull/254

Then I could merge it however I feel is most appropriate. Or if I’ve already reviewed the pull-request online and am on my master branch I can merge the entire pull-request like so:

$ hub am -3 https://github.com/bar/php-mode/pull/254

Again, pretty simple, right?

Conclusion and Other Goodies

Hopefully you can see how hub can be useful for interacting with projects on GitHub. Some of its other nice features are the ability to automatically open a project’s issue page or wiki in your browser, e.g.:

$ hub browse -- issues
$ hub browse -- wiki

# Some other project or fork:
$ hub browse foo/php-mode -- commits

Want to see the list of open issues for your project?

$ hub issues

Or want to check the Travis CI status of the current commit?

$ hub ci-status

If you use GitHub as much as I do then I strongly recommend you take a look at hub. It simplifies a lot of common tasks, whether you’re contributing to an existing project or maintaining a project of your own. Overall it’s a great set of GitHub-related commands to simplify working with GitHub from the command-line.

Advertisements

Add Your Thoughts

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s