Name

git-hub - The Git command for GitHub

Synopsis

Here are just a few of the things you can do on GitHub with a simple command:

    git hub                             # Show the `git hub` cheat sheet
    git hub help                        # Show this awesome documentation
    git hub setup                       # Config dialog. Do this first!

    git hub user <user>                 # Get info about a user
    git hub repos <owner>               # List recent repositories
    git hub repo-new <repo>             # Create a new repository
    git hub fork <owner>/<repo>         # Fork a repository
    git hub clone <owner>/<repo>        # Clone a GitHub repository
                                        # Set/Change your repo description
    git hub repo-edit <repo> description 'Just another GitHub repo'
    git hub repo-delete <owner>/<repo>  # Delete a repository
    git hub followers <user>            # List a user's followers
    git hub star ingydotnet/git-hub     # Star this repository
    git hub watch ingydotnet/git-hub    # Watch this repository
    git hub follow ingydotnet           # Follow this author
    git hub trust ingydotnet            # Add collaborators to repo
                                        # Stalk all your followers
    git hub followers -ra | git hub user -

Description

The hub subcommand for git, allows you to perform many of the operations made available by GitHub's v3 REST API, from the git commandline command.

You can fork, create, delete and modify repositories. You can get information about users, repositories and issues. You can star, watch and follow things, and find out who else is doing the same. The API is quite extensive. With this command you can do many of your day to day GitHub actions without needing a web browser.

You can also chain commands together using the output of one as the input of another. For example you could use this technique to clone all the repos of a GitHub user or organization, with one command. See PIPE AND EACH below.

Installation

There are currently 3 ways to install git-hub. For all of them you need to get the source code from GitHub:

    git clone https://github.com/ingydotnet/git-hub /path/to/git-hub

The first installation method is preferred: source the init file. Just add a line like this one to your shell startup script:

    source /path/to/git-hub/init

That will modify your PATH and MANPATH, and also enable command completion.

The second method is to do these things by hand. This might afford you more control of your shell environment. Simply add the lib and man directories to your PATH and MANPATH:

    export PATH="/path/to/git-hub/lib:$PATH"
    export MANPATH="/path/to/git-hub/man:$MANPATH"

See below for info on how to turn on Command Completion.

The third method is a standard system install, which puts git-hub next to your other git commands, do this instead:

    make install        # Possibly with 'sudo'

This method does not account for upgrading and command completion yet.

See "Upgrading" and "Command Completion" below.

Command Options

Commandline options start with a dash and can appear in any order in the command. Long form commands that require an argument can use '=' or not:

    --count=5
    --count 5

-c <number>, count=<number>: This option is for commands that return a list of things. Specify the number of items you want the command to return. Each list command has a reasonable default value.
-a, --all: Show all elements for list commands. Also applies to a few other commands as documented.
-r, --raw: For commands the produce lists, just list the raw data. For commands that produce reports, show the raw storage keys, rather than the human friendly ones. You will need the raw keys to edit/change values.
-j, --json: For some commands, you can get the raw data in JSON.
-: This option, just a single '-', is small but very powerful. It means to read the next line from stdin, and put the content into the command at that point. See PIPE and EACH below.
=: Like the '-' command above, but reads each word from stdin.
-h: Show the brief command usage.
--help: Show the full documentation.
-q, --quiet: Show minimal output.
-v, --verbose: Show detailed output. Notably, show the raw command that is used for the GitHub API calls.
--token=<api-token>: Set or override the api-token required by the command. This value can also come from the GIT_HUB_API_TOKEN environment variable. Usually this value comes from your ~/.git-hub/config file.
-d --dryrun: Don't actually make the API call. This option turns on verbose mode.
-T: Show the API token in the verbose output. Hidden by default. This option turns on verbose mode.
-A, --use-auth: Use authentication whether or not it is needed for a certain command. This is useful if you have exceeded your hourly GitHub API rate limit, which is 60 calls unauthenticated, and 5000 calls authenticated.
-C --no-cache: There are currently known bugs in GitHub's cache headers. If the content seems stale, use this option.

Debug Options

There are a number of debug options that will give you lots of extra information (albeit in a less pretty format).

-O: Show the API reponse output. Always in JSON format. JSON is pretty-printed.
-H: Show the API response headers.
-J: Show the API response JSON, in decoded form.
-R: Repeat the last command, using the previous API server response. Useful for development and debugging. (Beware, only caches the most recent API call, so not really good for commands that make multiple calls).
-x: Turn on Bash -x debugging. This will show every bash command executed in the program. This is extremely useful to track down nasty bugs.

Arguments

The git hub command gets its input values from these sources (in this order):

Commandline arguments (see specific command, below).
Environment variables of the form GIT_HUB_VARIABLE_NAME.
The ./.git/config file. (The repo you are issuing commands from)
The ~/.git-hub/config file.

Most of the commands described below have arguments. This section defines each of the argument types. Note that argument values that are strings containing whitespace need to be quoted.

Argument variable names are always indicated by angle brackets, like: <variable>. Arguments listed in square brackets are optional and arguments followed by ... indicate that more than one is allowed.

<user>: A GitHub user name. Sometimes an organization name can be used instead. If this argument is optional, it defaults to the GitHub owner of the repo you are currently in. If you are not in a GitHub repo, it defaults to your login. Override: GIT_HUB_USER_NAME environment variable.
<owner>: A GitHub user or organization that owns the repository being specified. This value defaults much like the <user> argument (above). Override: GIT_HUB_OWNER_NAME environment variable.
<org>: A GitHub organization name. Override: GIT_HUB_ORG_NAME environment variable.
<repo>: A GitHub repository name. If this argument is optional, it defaults to the GitHub repo name of the repo you are currently in. Override: GIT_HUB_REPO_NAME environment variable.
<owner>/<repo>: Many commands need both an owner and repo separated by a slash. If the owner is you (your GitHub login) you can omit it (but you still need the leading slash). Like /myrepo, instead of me/myrepo. If this argument is optional, it defaults the the owner and repo of the GitHub repo you are in.
<key-value-pair>: Two strings separated by whitespace. Values with embedded whitespace should be quoted. The documentation of each command that needs these pairs, will list the valid keys.
<api-token-id>: The integer number id of a token (not the 40 hex-character value).
<scope-name>: One of the GitHub scopes that you can apply to a token. The git hub scopes command will tell you all of these, and what they mean.

Commands

These are the commands you can use to perform most of your daily GitHub interactions from the command line. They are installed by default.

help

Show this manpage.

version

Print version info for git-hub.

info

Show detailed version and environment info about your git-hub installation. This can be useful for figuring out things about how git-hub is operating in a given situation. Also good for reporting bugs / issues in git-hub.

setup

Before you can use the commands described below, you need to perform some setup/configuration steps.

This "wizard" style dialog, will walk you through the configuration process quickly and painlessly, with lots of explanation. You should run this command right away. You can also re-run it, and it will allow you to change your config, while defaulting to your existing settings.

If you would rather do the steps by hand, see "#Configuration- Commands" below.

upgrade

Upgrade the git-hub installation to the latest version. Note: you need to be running 'git-hub' from the source repo, and be on the master branch for this to work.

user [<user>]

Show basic information about a specific user. User defaults to the owner of the current repo, or your login if you are not inside a repo directory. The --raw and --json options show the data in different formats than normal output.

user-get <user> <data-key>

Get a specific data value for a particular user.

user-edit <key-value-pair>...

Set specific fields of your user info to new values. You list the parameters as key/value pairs.

You can edit the following user keys: name, email, blog, location, company, bio.

orgs [<user>]

List the organizations that a user is a member of.

org <org>

Show basic information about a GitHub organization. The --raw and --json options show the data in different formats than normal output.

org-repos <org>

Show all the repos for an organization, both public and private.

org-members <org>

List members of an organization.

org-get <org> <data-key>

Get a specific data value for a particular organization.

org-edit <org> <key-value-pairs>...

Set specific meta-data fields of an organization to new values. You list the parameters as key/value pairs.

You can edit the following organization keys: name, email, billing_email, blog, location, company.

teams <org>

List the teams in an organization.

team <team_id>

Get information about a team.

team-members <team_id>

List members of a team.

team-repos <team_id>

List repos of a team.

team-repo-add <team_id> <repo>

Add repo to a team. Repo name must not include org name.

team-new <org> <name> <perm>

Add a new team (name) to an organization. The 'perm' arg must be pull, push or admin.

team-delete <team_id>

Delete a team.

members <org>|<team_id>

List the members of an organization or team. If numeric argument, show team members, else organization members.

member-get <team_id> <user>

Show whether a user is a member of a specified team.

member-add <team_id> <user>

Add a user to a team.

member-remove <team_id> <user>

Remove a user from a team.

followers [<user>]

List the people who are followers of a user.

follows <user> [<target-user>]

Check if <user> follows <target-user>. The default target user is you.

following [<user>]

List the people that a user is following.

follow <user>...

Follow one or more users.

unfollow <user>...

Stop following one or more users.

clone ([<owner>/]<repo> [<directory>])...

Clone a GitHub repo. Always uses --recursive so you get submodules too. You can specifiy a list of repos. If you specify a directory for a repo, it should be an absolute path name or else begin with '.' or '..' so that it can be distinguished from another repo name.

repos [<user>]

List the repos for a user or organization. List is returned in order of recent activity.

repo [<repo>]

Show basic information about a specific repository. The --raw and --json options show the data in different formats than normal output.

repo-get <owner>/<repo> <data-key>

Get a specific data value for a particular repository.

repo-edit [<owner>/]<repo> <key-value-pair>...

Set specific meta-data fields of a repository to new values. You list the parameters as key/value pairs.

You can edit the following repo keys: description, homepage.

repo-new [<org>/]<repo>

Create a new GitHub repository.

repo-init [<directory>]

This command is useful for setting up new repos. Just mkdir a new dir, cd into it and issue the command. It will 'git init', make the GitHub repo and add it as the origin remote. It will only do the things that have not yet been done.

repo-delete <owner>/<repo>

Delete a GitHub repository.

forks [<owner>/<repo>]

List the forks of a repository.

fork <owner>/<repo> [--org=<org>] [--remote=<name>]

Fork a repository to your account or to an organization. Optionally, you can specify the name of a remote to add, pointing to your fork.

stars [<owner>/<repo>]

Show what users have starred a repository.

star [<owner>/<repo>]

Add your star to a repository.

unstar [<owner>/<repo>]

Remove your star from a repository.

starred [<user>]

List repositories that a user has starred.

watch [<owner>/<repo>]

Start watching a repo.

unwatch [<owner>/<repo>]

Stop watching a repo.

watching [<user>]

Show which repos a user is watching.

watchers [<owner>/<repo>]

Show the users who are watching a repo.

collabs [<owner>/<repo>]

List current collaborators for a repository.

trust [<owner>/<repo>] <user>...

Add one or more collaborators to a repository.

untrust [<owner>/<repo>] <user>...

Remove one or more collaborators from a repository.

issues [<owner>/<repo>] [--all]

List the open issues for a repo. Use the --all flag to see both open and closed issues.

issue [<owner>/<repo>] <issue-id-number>

Show info (including any comments) for a specific issue. If no issue number is given, this command will call issue-new instead.

issue-new [<owner>/<repo>]

Create a new issue for a repository.

issue-edit [<owner>/<repo>] <issue-id-number>

Add a comment. Change values of 'title', 'state', 'assignee' and 'milestone'. Changing state to 'closed' will close the issue.

comment [<owner>/<repo>] <issue-id-number>

Add a comment to an issue. You can also use issue-edit to just add a comment.

issue-close [<owner>/<repo>] <issue-id-number>

Close an issue. You can also use issue-edit to close an issue.

issue-resolve [<owner>/<repo>] <issue-id-number>

Add a comment to an issue and then close it.

pr-list [<owner>/<repo>]

List the pull requests for a repo.

pr-new [<issue-id-number>] [<options>]

Create a new pull request for a repository based on the current branch. If an issue ID number is given, this command will attach the pull request to the issue instead of creating a new one.

If the default remote is a fork, the pull request will target the default branch of the parent repository. Otherwise the pull request will target the default branch of the default remote itself. Use --remote, --branch, -- parent, and --base options to change the default source remote, source branch, target remote and target branch (respectively).

pr-diff [<owner>/<repo>] <issue-id-number>

Show the diff for a pull request.

pr-fetch [<owner>/<repo>] <issue-id-number>

Fetches a pull request to a local review/$number branch

pr-merge [<owner>/<repo>] <issue-id-number>

Merge and close a pull request.

pr-queue [<user>] [--count=#] [--all]

Show a user's Pull Request queue, for all repos. Shows the open PRs for any repo that has them. The --count option tells how many repos to check. The --all option says to show closed as well as open PRs.

Note: this command makes more API calls than most other commands and thus runs slower. You might want to tee the output to a file, if you need to get back to this data a lot.

notify-list [--all]

List your recent unread user notifications. To list your read notifications as well, use the --all option.

keys [<user>]

List public SSH keys for a user.

keys-add <title> <key>

Add a public ssh key for your user.

cache-clear

Clear your API response cache.

open [<owner>/<repo>] [<file-path>]

Open a browser window to a repo or a file in a repo.

url [<owner>/<repo>] [<file-path> [<line-number>]]

Print the URL of a repo or a file in a repo.

git-hub-travis

Enable and/or disable travis-ci testing from the command line.

Plugin Commands

You get tons of useful commands by default, and they are all listed and documented in the next section below. But git-hub also supports third party plugin commands.

This section is about the "plugin" commands that currently come with git-hub.

irc-enable <room> [<server>]: This command must be run inside a cloned repo. It enables GitHub activities for a repo to be reported to an IRC channel.
irc-enable: This command must be run inside a cloned repo. It disables the GitHub IRC webhook for a repo.
irc-url: Show the GitHub URL for setting webhooks on the current repo.

Configuration Commands

These commands are for editing your git-hub config file and managing your GitHub authentication tokens.

config [<config-key> [<config-value>]]: With no args, this command will print the contents of ~/.git-hub/config. With With one argument (a key), print the current value of the config key. With two arguments (key value), set the value of the config key. 4 keys are currently supported: login, api-token, use-auth, and json-lib.
config-unset <config-key>: Unset a config key. Removes the key from the ~/.git-hub/config file.
tokens: List all the API tokens for your GitHub account. Use the --raw option to print the token IDs and descriptions, but not the actual token values.
token-new [<description-string>]: Create a new API token for your GitHub login id. Note: Creating a new token will not automatically add it to your ~/.git-hub/config file; you need to do that yourself with the git hub config api-token <token-value> command. Use the --raw option to just print the new token id.
token-get <api-token-id> <data-key>: Get a specific data value for a particular token.
token-delete <api-token-id>: Delete one of your API tokens for your GitHub login id. Note: You need to delete tokens by id (listed by the tokens command), not by token value.
scopes <api-token-id>: List the scopes assigned to your API token, and also list all the possible scope values that you can assign. Use the --raw option to just list the scopes.
scope-add <api-token-id> <scope-name>...: Add one or more scopes to your API token. You can use the --all option to add all possible scopes at once.
scope-remove <api-token-id> <scope-name>...: Remove one or more scopes from your API token. You can use the --all option to remove all possible scopes at once.

Upgrading git-hub

If you used the PATH method of installation, just run this to upgrade git-hub:

    git hub upgrade

Or (same thing):

    cd /path/to/git-hub
    git pull

If you used make install method, then run this again (after git pull):

    make install        # Possibly with 'sudo'

Command Completion

The git hub command supports <TAB>-based command completion. If you don't use the init script (see Installation, above), you'll need to enable this manually to use it.

In Bash

If your Bash setup does not already provide command completion for Git, you'll need to enable that first:

    source <Git completion script>

On your system, the Git completion script might be found at any of the following locations (or somewhere else that we don't know about):

/etc/bash_completion.d/git
/usr/share/bash-completion/git
/usr/share/bash-completion/completions/git
/opt/local/share/bash-completion/completions/git
/usr/local/etc/bash_completion.d/git
~/.homebrew/etc/bash_completion.d/git

In case you can't find any of these, this repository contains a copy of the Git completion script:

    source /path/to/git-hub/share/git-completion.bash

Once Git completion is enabled (whether you needed to do that manually or not), you can turn on git-hub completion with a command like this:

    source /path/to/git-hub/share/completion.bash

In zsh

In the Z shell (zsh), you can manually enable git-hub completion by adding the following line to your ~/.zshrc, before the compinit function is called:

    fpath=('/path/to/git-hub/share/zsh-completion' $fpath)

Plugins

The git-hub command supports plugins. All you need to do to install a plugin, is to clone the plugin repo into the plugin/ subdirectory of the git-hub repository. There are example plugins already installed. If you do a system-style install, then just make install the plugins too.

Faster

The git-hub command is written in pure Bash, including a complete JSON parser written in Bash. Unfortunately, this parser is a bit slow. It is really slow for large API payloads.

To make the git-hub command perform much faster, just run this command:

    git hub config json-lib json-perl.bash

That will enable a Perl replacement, which requires Perl (of course) and the JSON.pm Perl module. If the JSON::XS Perl module is also installed, it will be even faster.

Pipe and Each

You can pipe the output of one git hub into another and multiply your power. The command being piped into should use the EACH option which is a single dash ('-'). It will cause the command to be run once for each line of input, inserting the line into the command, in place of the '-'. If you use a '=' it will do the same thing except for each "word" of input.

This command:

    git hub followers --raw

will list lines containing only user ids. You can pipe it into commands needing a user id, like:

    git hub followers --raw | git hub user - --json

Thus printing the JSON user info for each follower. Same as:

    for _ in `git hub followers --raw`; do
      git hub user $_ --json
    done

For '=' you can do things like:

    echo alice bob chelsea | git hub trust =

to trust a list of users in one go.

Token Authentication and Scopes

Many endpoints of the GitHub v3 API require a Personal API Access Token. You can list your current tokens with this command:

    git hub tokens

If you don't have any tokens or want a new one for the git-hub command, run these commands (the git hub setup command automates this):

    git hub token-new "my git-hub command token"
    git hub scope-add <token-id> user repo
    git hub scopes <token-id>
    git hub config api-token <token-value>

You can also see all your tokens on the web at this page.

You can specify your API token to git hub on the commandline with -- token=... or in the GIT_HUB_API_TOKEN environment variable, but the easiest thing to do is just set it in the git-hub config.

Certain token scopes are required for various GitHub API operations. Make sure your token has the scopes turned on for the things you want to do. See the scopes, scope-add and scope-remove git hub subcommands.

NOTE: All the git hub commands dealing with tokens and scopes require you to enter your GitHub password. If you need to issue a bunch of these commands and you don't want to retype your password each time, you can put your password in the GIT_HUB_PASSWORD environment variable.

Rate Limits

GitHub limits unauthenticated API calls to 60 per hour, and authenticated API calls to 5000 per hour. For this reason you may wish to use authentication even for calls that don't need it. You can use the -A/--use-auth option to make sure a command uses authentication. You can also set the config file to always use authentication, with this command:

    git hub config use-auth true

Another option is to set the GIT_HUB_USE_AUTH environment variable:

    export GIT_HUB_USE_AUTH=true

ETAG Caching

GitHub provides ETag headers in the API responses, and git-hub uses them to cache responses, by default. When you use this feature, your rate-limit usage is not affected for cached responses.

GitHub has had caching bugs in their API in the past. If you suspect the cache is stale, you may want to try these options:

Use the -C (--no-cache) flag on a request to bypass the cache.
Set GIT_HUB_NO_CACHE=true to bypass the cache.
Run git hub config no-cache true to never use the cache.
Run git hub cache-clear to erase all the cached values.

Examples

The following sections show lots of interesting ways to use git hub. Let your imagination be your guide.

Example 1. Create a new repo and GitHub origin

Do everything from the command line:

    $ mkdir foo
    $ cd foo
    $ echo 'The new foo' > README
    $ git init
    $ git add README
    $ git commit -m 'First commit'
    $ git hub new foo
    $ git hub repo foo      # Get repo info including the remote address
    $ git remote add origin <new-remote-address>
    $ git push origin master
    $ git hub repo-edit \
        description  'The new foo' \
        homepage     http://example.com
    $ git hub repo

Note that on the last two commands you don't need to set the <repo> because it can be gleaned from the remote. Also on the edit command notice how you can specify multiple key/value pairs.

Example 2. Commands from within a repo

Assume your current working directory is not a GitHub repo:

    $ # List *your* repos:
    $ git hub repos
    $ # Clone someone else's repo:
    $ git hub clone ingydotnet/git-hub
    $ # cd into it:
    $ cd git-hub
    $ # Get info about ingydotnet:
    $ git hub user
    $ # Show ingydotnet's recent repos:
    $ git hub repos
    $ # Show info about ingydotnet/git-hub:
    $ git hub repo
    $ # Fork the git-hub repo:
    $ git hub fork
    $ # Follow ingydotnet:
    $ git hub follow
    $ # See who ingydotnet is following:
    $ git hub following
    $ # Star the ingydotnet/git-hub repo:
    $ git hub star
    $ # etc...

The git hub command tries to be environmentally aware. If you are in a GitHub cloned repo directory, and you don't specify <user> or <owner> or <repo> for a command that needs them, then they will be pulled from the remote url. Otherwise, if you don't specify a <user> it will use the one (presumably yours) that you set with the git hub config login ... command.

Example 3. Building Complex Commands

The git hub command can be used to output raw data, which can be fed into other commands; even other git hub commands. This lets you do some powerful automation with very little code. The --raw (-r) flag will make the output of many commands be usable as data, and the - (EACH) option makes commands read data from stdin.

Get information about all your followers:

    for user in $(git hub followers <your-login> -r); do
      git hub user $user
    done

Or more simply by using PIPE and EACH:

    git hub followers -r | git hub user -

Follow all your followers:

    git hub followers -r | git hub follow -

Find out if the people you are following, are following you!

    git hub following -r | git hub follows -

View all the open issues on a repository at once:

    git hub issues -r | git hub issue -

Clone all the repos in an organization:

    git hub repos <org> -r | git hub clone -

Star the latest 5 repos from all the people you are following that have more than 50 repos:

    git hub following <your-login> -r |
      git hub user-get - public_repos |
      perl -nle 'print if $_ > 50' |
      git hub repos - -rc5 |
      git hub star -

Author

Written by Ingy döt Net <ingy@ingy.net>

Status

This command is over a year old. It does a ton of stuff well, but still has a lot to do to be complete.

The plan is to support as much of the API as possible. Patches / Pull Requests welcome. See the file notes/todo in the git-hub repo for upcoming changes.

Try make test. There are tests in place but testing is not yet extensive. Expect more testing soon. Also please include tests-in-kind for any patches you submit.

Find 'ingy' on #git-commands in irc.freenode.net if you have questions or ideas.