A Git command line interface to GitHub
Although probably the most outstanding feature (and the one that motivated the
creation of this tool) is the
pull rebase command, which is the rebasing
version of the GitHub Merge (TM) button. This enables an easy workflow that
doesn't involve thousands of merges which makes the repository history
Another unique feature is the ability to transform an issue into a pull request by attaching commits to it (this is something offered by the GitHub API but not by the web interface).
Here are some usage examples, for more information about all the supported
command an options, please refer to the man page using
git hub --help or
looking at the online version (this is for the latest development snapshot
One time global setup to get the credentials
$ git hub setup --global --user octocat GitHub password (will not be stored):
You can revoke this credentials at any time in the GitHub Applications Settings page.
Clone (and fork) a project
$ git hub clone -t sociomantic-tsunami/git-hub Forking sociomantic-tsunami/git-hub to octocat/git-hub Cloning email@example.com:sociomantic-tsunami/git-hub.git to git-hub Fetching from fork (firstname.lastname@example.org:octocat/git-hub.git)
The fork will happen only if you haven't fork the project before, of course. And
we are using the triangular workflow option (
--triangular), so we
can pull from the parent repo but push to our fork by default.
Using a pre-existing cloned repository
$ git config hub.upstream sociomantic-tsunami/git-hub
This sets the master GitHub project. It's where we query for issues and pull requests and where we create new pull requests, etc.
This is only necessary if you didn't clone your repository using
clone and is a one time only setup step.
$ git hub issue list  pull: Use the tracking branch as default base branch (leandro-lucarella-sociomantic) https://github.com/sociomantic-tsunami/git-hub/issues/3  bash-completion: Complete with IDs only when is appropriate according to command line arguments (leandro-lucarella-sociomantic) https://github.com/sociomantic-tsunami/git-hub/issues/1
Update an issue
$ git hub issue update --label important --label question \ -m 'New Title' --assign octocat --open --milestone v0.5 1  New Title (leandro-lucarella-sociomantic) https://github.com/sociomantic-tsunami/git-hub/issues/1
Create a new pull request
$ git hub pull new -b experimental -c mypull Pushing master to mypull in myfork  Some pull request (octocat) https://github.com/sociomantic-tsunami/git-hub/pull/4
This creates a pull request against the upstream branch
HEAD, but creating a new topic branch called
mypull to store
the actual pull request (assuming our
HEAD is in the branch
Attach code to an existing issue
$ git hub pull attach -b experimental -c mypull 1 Pushing master to mypull in myfork  Some issue (octocat) https://github.com/sociomantic-tsunami/git-hub/pull/1
Same as before, but this time attach the commits to issue 2 (effectively converting the issue into a pull request).
Rebase a pull request
$ git hub pull rebase 4 Fetching mypull from email@example.com:octocat/git-hub.git Rebasing to master in firstname.lastname@example.org:sociomantic-tsunami/git-hub.git Pushing results to master in email@example.com:sociomantic-tsunami/git-hub.git  Some pull request (octocat) https://github.com/sociomantic-tsunami/git-hub/pull/4
If the rebase fails, you can use
git hub pull rebase --continue as you would
do with a normal rebase.
- Python 2.7 (3.x can be used too but you have to run the
2to3tool to the script first)
- Git >= 1.7.7 (if you use Ubuntu you can easily get the latest Git version using the Git stable PPA)
- Docutils (>= 0.8, although it might work with older versions too, only needed to build the man page)
- FPM (>= 1.0.1, although it might work with older versions too, only needed to build the Debian package)
Only the man page and bash completion script need to be built. Type
to build them.
Otherwise you can type
make install to install the tool, man page, bash
completion and VIM ftdetect plugin (by default in
/usr/local, but you
can pick a different location by passing the
prefix variable to
make install prefix=/usr). To pick a location for the
completion scripts (by default in
/etc), use the
If Docutils is installed using
pip the environment variable
should be set to
To enjoy the bash completion you need to re-login (or re-load the
To have syntax highlight in VIM when editing git-hub messages, you need to
activate the ftdetect plugin by copying or symbolic-linking it to
mkdir -p ~/.vim/ftdetect ln -s $(prefix)/share/vim/addons/githubmsg.vim ~/.vim/ftdetect/ # or if you are copying from the sources: # ln -s ftdetect.vim ~/.vim/ftdetect/githubmsg.vim
We explored other alternatives before starting this project, but none of these tools do (or are targeted) at what we needed. But here are the ones we found, in case they are a better fit for you:
- hub: Is the official tool, but it completely replaces the Git command, adding special syntax for official git commands. This is definitely something we didn't want. We don't want to mess with Git.
- ghi: This only handle issues. Not what we needed.
- git-spindle: This tool was
discovered after we started and published this project. It covers similar
ground, but doesn't offer rebase capabilities (this, of course, could have
been implemented as an extension). Sadly, it also extends the Git command-line
hubcommand, which can introduce a lot of confusion to users. We might try to merge our code into that project eventually, if there is interest.
- gh: A command line tool based on NodeJS. It does offer the rebase capabilities we sought after, but the project was created after this project was started.
If you want to contact us, either because you are a user and have questions, or because you want to contribute to the project, you can subscribe to the mailing list.
Subscription happens automatically (after confirmation) the first time you write to: firstname.lastname@example.org (this first e-mail will be dropped).
You can always visit the mailing list archives to check if your questions were already answered in the past :)