git-hub(1)

NAME

git-hub - Do GitHub operations from the git command

SYNOPSIS

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

git hub                             # Show the git hub cheat sheet
git help hub                        # Show this awesome documentation
git hub config login <your-login>   # Do this first!
git hub user <user>                 # Get info about a user
git hub repos <owner>               # List recent repositories
git hub create <repo>               # Create a new repository
git hub fork <owner>/<repo>         # Fork a repository
git hub repo-edit <repo> description Just another GitHub repo
git hub delete <owner>/<repo>       # Delete a repository
git hub followers <user>            # List a user’s followers
git hub star ingydotnet/git-hub     # Star a repository
git hub follow ingydotnet           # Follow a user
git hub trust ingydotnet            # 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 fork, create, delete and modify repositories. You can get information about repositories and users. 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.

INSTALLATION

Just run (possibly with sudo):

make install

This will install git-hub next to your other git commands. It will also install the git-hub manpage so you can run theses commands for help:

man git-hub
git help hub

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 endpoints of the GitHub v3 API require a Personal API Access Token. You can list your current tokens with this command:

git hub token-list

If you don’t have any tokens or want a new one for the git-hub command, run these commands:

git hub token-create "git-hub command token"
git hub scope-add <token-id> user repo
git hub scope-list <token-id>

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 scope-list, 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 1

Another option is to set the GIT_HUB_USE_AUTH environment variable:

export GIT_HUB_USE_AUTH=1

OPTIONS

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

-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.
--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.
-h
--help: Show the brief command usage.
-q
--quiet: Show minimal output.
-v
--verbose: Show detailed output. Notably, show the raw command that is used for the GitHub API calls.
-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.

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.
-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.

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 ~/.githubconfig 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 scope-list command will tell you all of these, and what they mean.

COMMANDS

config [<config-key> [<config-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 3 keys are currently supported: login, api-token and use-auth.

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

token-list

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-create [<description-string>]

Create a new API token for your 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. Use the --raw option to just print the new token id.

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 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. 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.

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. Use the --raw option to show the actual API keys.

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

Set specific meta-data fields of a user 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. Use the --raw option to show the actual API keys.

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`.

members <org>

List the members of an organization.

teams <org>

List the teams in an organization.

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. Use the --raw option to show the actual API keys.

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-create [<org>/]<repo>

Create a new GitHub repository. Alias: create.

repo-delete <owner>/<repo>

Delete a GitHub repository.

forks [<owner>/<repo>]

List the forks of a repository.

fork <owner>/<repo> [<org>]

Fork a repository to your account or to an organization.

stars [<owner>/<repo>]

Show what users have starred a repository.

star [<owner>/<repo>]

Add your star to a repository.

unstar [<owner>/<repo>]

Add your star to a repository.

starred [<user>]

List repositories that a user has starred.

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.

followers [<user>]

List the people who are followers of a user.

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.

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 create foo
$ git hub repo foo --raw
$ 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 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 an <owner> or a <repo>, then they will be pulled from the remote url. Otherwise, if you don’t specify an <user> it will use the one (presumably yours) that you set with the git hub config login ... 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.

ioerror/git-hub