git-hub(1)

NAME

git-hub - Access GitHub v3 API from git

SYNOPSIS

git hub config login <your-github-login-id>  # Do this first!
git hub user-info <user-name>       # Get info about a user
git hub repo-list <user-name>       # List recent repositories
git hub repo-create <repo-name>     # Create a new repository
git hub repo-edit --repo=<repo-name> description Just another GitHub repo
git hub repo-delete <repo-name>     # Delete a repository
git hub collab-add <user-names>     # Add collaborators to repo

DESCRIPTION

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

You can create delete and modify repositories. You can get information about repositories and users. The API is quite extensive. With this command you can do many of your day to day GitHub actions without needing a web browser.

INSTALLATION

Just run:

make install

That will install git-hub next to your other git commands. You will likely need sudo permissions to install this.

To install the documentation, run:

make install-doc

Doc installation requires the asciidoc toolchain. When the doc is installed, you can view it using one of these commands:

man git-hub
git help hub

To install everything, run:

make install-all

CONFIGURATION

Before using the git hub command, you will need to set a couple configuration options. Run these commands:

git hub config login <your-github-login-id>
git hub config api-token <your-github-api-token>

Note	If you don’t know what your API token is, see the next section.

These values will be stored in ~/.githubconfig, like this:

[github]
        login = <your-github-id>
        api-token = <your-github-api-token>

You can edit this file by hand or use the git hub config command.

AUTHENTICATION

Many end points of the GitHub v3 API require a Personal API Access Token. You can generate these tokens by visiting this page, or from the commandline with the token-list and token-create git hub subcommands.

Many of your git hub commands will require a token. You can specify the token 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.

Note that auth tokens have scopes. Various 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 scope-list, scope-add and scope-remove git hub subcommands.

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 1

Another option is to set the GIT_HUB_USE_AUTH environment variable:

export GIT_HUB_USE_AUTH=1

OPTIONS

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

Commandline arguments (see specific command, below).
Commandline options (outlined in this section).
Environment variables of the form GIT_HUB_VARIABLE_NAME.
The ./.git/config file. (The repo you are issuing commands from)
The ~/.githubconfig file.

When your current directory is a git repo, and the origin remote contains github.com, any commands that need a user-name and/or repo-name will use the values found in that remote, by default.

Note	Many commands need either a user-name, a repo-name or both. To refer to another user’s repo, you can often use the combined form of `user-name/repo-name` as a command argument.

Commandline options start with a dash and can appear in any order in the command.

--user=<user-name>: Set or override the user-name required by the command. This value can also come from the GIT_HUB_USER_NAME environment variable, or the config file of the git repo for your current working directory.
--repo=<repo-name>: Set or override the repo-name required by the command. This value can also come from the GIT_HUB_REPO_NAME environment variable, or the config file of the git repo for your current working directory.
--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 ~/.githubconfig file.
-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.
-q
--quiet: Show minimal output.
-v
--verbose: Show detailed output.
-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.

DEV OPTIONS

There are a number of dev options that will give you lots of extra information (albeit in a less readable form).

-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.
-x: Turn on Bash -x debugging. This will show every bash command executed in the program.
-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).

COMMANDS

config [<key> [<value>]]: With no args, this command will print the contents of ~/.githubconfig. 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. Only 2 keys are currently supported: login and api-token.

config-unset <key> Unset a config key. Removes the key from the ~/.githubconfig file.

token-list: List all the API tokens for your GitHub login id. You will need to enter the password for you GitHub login id.
token-create [<description-string>]: Create a new API token for your GitHub login id. You will need to enter the password for you GitHub login id. Note: Creating a new token will not automatically add it to your ~/.githubconfig file; you need to do that yourself with the git hub config api-token <token-value> command.
token-delete <api-token-id>: Delete one of your API tokens for your GitHub login id. You will need to enter the password for you GitHub login id. Note: You need to delete tokens by id (listed by the token-list command), not by token value.
scope-list <api-token-id>: List the scopes assigned to your API token, and also list all the possible scope values that you can assign. You will need to enter the password for you GitHub login id.
scope-add <api-token-id> <scope-name>…: Add one or more scopes to your API token. You will need to enter the password for you GitHub login id.
scope-remove <api-token-id> <scope-name>…: Remove one or more scopes from your API token. You will need to enter the password for you GitHub login id.
user-info [<user-name>]: This command will 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.

user-update <key-value-pair>… [--user=<user-name>] Set specific fields to new values. You list the parameters as key/value pairs.

repo-list [<user-name>]: List the repos for a user. List is returned in order of recent activity.
repo-info [<repo-name>]: This command will show basic information about a specific repository.
repo-create <repo-name>: Create a new GitHub repository.
repo-edit [<user>/<repo>] <key-value-pair>…: Set specific fields to new values. You list the parameters as key/value pairs.
repo-delete <repo-name>: Delete a GitHub repository.
collab-list [<user-name>/<repo-name>]: List current collaborators for a repository.
collab-add [<user-name>/<repo-name>] <collab-name>…: Add one or more collaborators to a repository.
collab-remove [<user-name>/<repo-name>] <collab-name>…: Remove one or more collaborators from a repository.

ALIASES

Some of the common commands have shorter aliases.

user: Alias for user-info.
repos: Alias for repo-list.
repo: Alias for repo-info.

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 repo-create foo
$ git hub repo-info foo
$ 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-info

Note that on the last two commands you don’t need to set the <repo-name> because it can be gleaned from the remote. Also on the repo-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 repo:

$ # This command will list *your* repos:
$ git repos
$ # Clone someone else's repo:
$ git clone git@github.com:tomas/skull.git
$ # cd into it:
$ cd skull
$ # This command will show tomas' recent repos:
$ git repos
$ # This command will show info about tomas/skull:
$ git repo

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

AUTHOR

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

STATUS

This command is still in early development. Only the basic commands have been supported, but the plan is to support as much of the API as possible. Patches / Pull Requests welcome.

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

This command is attempting to follow the guidelines for git command development, so that it may one day be a standard command for git.

Find ingy on irc.freenode.net if you have questions or ideas.

defermat/git-hub