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.
Installing hub is simple and straight-forward. However, I want to make one important note. The official site suggests aliasing
$ 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.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
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
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
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.