A Git command line interface to GitHub

Description

git hub is a simple command line interface to GitHub, enabling most usefulGitHub tasks (like creating and listing pull request or issues) to be accesseddirectly through the Git command line.

Although probably the most outstanding feature (and the one that motivated thecreation of this tool) is the pull rebase command, which is the rebasingversion of the GitHub Merge (TM) button. This enables an easy workflow thatdoesn't involve thousands of merges which makes the repository historyunreadable.

Another unique feature is the ability to transform an issue into a pullrequest by attaching commits to it (this is something offered by the GitHubAPI but not by the web interface).

Usage

Here are some usage examples, for more information about all the supportedcommand an options, please refer to the man page using git hub --help orlooking at the online version (this is for the latest development snapshotthough).

One time global setup to get the credentials

To use this tool you most likely will need a GitHub PAT (personal access token).If you don't have one you regularly use, you can create a new one (checkGitHub docs if you need more help).

Make sure your PAT has at least repo and user scope.

Then you can use git hub setup to save it.

$ git hub setup --global --user octocat

You need to use a GitHub Personal Access Token to do almost anything useful.
To create one you can go to: https://github.com/settings/tokens/new.
More help at: https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token.

GitHub token: ******
Saved git config hub.username
Saved git config hub.oauthtoken

You can revoke this credentials at any time in the GitHub Applications Settingspage.

Clone (and fork) a project

$ git hub clone -t sociomantic-tsunami/git-hub
Forking sociomantic-tsunami/git-hub to octocat/git-hub
Cloning git@github.com:sociomantic-tsunami/git-hub.git to git-hub
Fetching from fork (git@github.com:octocat/git-hub.git)

The fork will happen only if you haven't fork the project before, of course. Andwe are using the triangular workflow option (-t / --triangular), so wecan 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 pullrequests and where we create new pull requests, etc.

This is only necessary if you didn't clone your repository using git hubclone and is a one time only setup step.

List issues

$ git hub issue list
[3] pull: Use the tracking branch as default base branch (leandro-lucarella-sociomantic)
    https://github.com/sociomantic-tsunami/git-hub/issues/3
[1] 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
[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
[4] Some pull request (octocat)
    https://github.com/sociomantic-tsunami/git-hub/pull/4

This creates a pull request against the upstream branch experimental usingthe current HEAD, but creating a new topic branch called mypull to storethe actual pull request (assuming our HEAD is in the branch master).

Attach code to an existing issue

$ git hub pull attach -b experimental -c mypull 1
Pushing master to mypull in myfork
[1] Some issue (octocat)
    https://github.com/sociomantic-tsunami/git-hub/pull/1

Same as before, but this time attach the commits to issue 2 (effectivelyconverting the issue into a pull request).

Rebase a pull request

$ git hub pull rebase 4
Fetching mypull from git@github.com:octocat/git-hub.git
Rebasing to master in git@github.com:sociomantic-tsunami/git-hub.git
Pushing results to master in git@github.com:sociomantic-tsunami/git-hub.git
[4] 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 woulddo with a normal rebase.

Download

You can get this tool from the GitHub project. If you want to graba release, please remember to visit the Release section.

Installation

Dependencies

• Python 3.x
• Git >= 1.7.7 (if you use Ubuntu you can easily get the latest Git versionusing the Git stable PPA)
• Docutils (>= 0.8, although it might work with older versions too, only neededto build the man page)
• FPM (>= 1.0.1, although it might work with older versions too, only needed tobuild the Debian package)

Building

Only the man page and bash completion script need to be built. Type maketo build them.

Alternatively, you can build a Debian/Ubuntu package. Use make deb forthat.

Installing

If you built the Debian/Ubuntu package, you can just install the package(dpkg -i ../git-hub_VER_all.deb).

Otherwise you can type make install to install the tool, man page, bashcompletion and VIM ftdetect plugin (by default in /usr/local, but youcan pick a different location by passing the prefix variable to make(for example make install prefix=/usr). To pick a location for thecompletion scripts (by default in /etc), use the sysconfdir variable.

If Docutils is installed using pip the environment variable RST2MANshould be set to rst2man.py.

The installation locations might be too specific for Debian/Ubuntu though.Please report any failed installation attempts.

To enjoy the bash completion you need to re-login (or re-load the/etc/bash_completion script).

To have syntax highlight in VIM when editing git-hub messages, you need toactivate the ftdetect plugin by copying or symbolic-linking it to~/.vim/ftdetect/githubmsg.vim:

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

Similar Projects

We explored other alternatives before starting this project, but none ofthese tools do (or are targeted) at what we needed. But here are the ones wefound, in case they are a better fit for you:

• hub: Is the official tool, but it completelyreplaces the Git command, adding special syntax for official git commands.
• gh: Another official tool, that tries to bringall the GitHub UI features but with a CLI interface. It works side-by-sidewith git.
• ghi: This only handle issues. Itseems a bit abandoned (at the time of writing it was last updated in October2016).
• git-spindle: This tool wasdiscovered after we started and published this project. It covers similarground, but doesn't offer rebase capabilities (this, of course, could havebeen implemented as an extension). Sadly, it also extends the Git command-lineadding the hub command, which can introduce a lot of confusion to users.We might try to merge our code into that project eventually, if there isinterest.

Contact

If you want to contact us, either because you are a user and have questions, orbecause you want to contribute to the project, you can subscribe to the mailinglist.

Subscription happens automatically (after confirmation) the first time you writeto: git.hub@librelist.com (this first e-mail will be dropped).

You can always visit the mailing list archives to check if your questionswere already answered in the past :)

You can also use GMANE to get a better list archive (both threaded andblog-like interfaces available) or to read the list using NNTP.

If you want to report a bug, just create an issue please (if you use thistool I'm sure you already have a GitHub account ;).