hub [--noop] COMMAND [OPTIONS]
hub alias [-s] [SHELL]
hub help hub-COMMAND
Hub is a tool that wraps git in order to extend it with extra functionality that makes it better when working with GitHub.
Available commands are split into two groups: those that are already present in git but that are extended through hub, and custom ones that hub provides.
hub-am(1)
hub-apply(1)
hub-checkout(1)
hub-cherry-pick(1)
hub-clone(1)
hub-fetch(1)
hub-init(1)
hub-merge(1)
hub-push(1)
hub-remote(1)
hub-submodule(1)
hub-alias(1)
hub-api(1)
hub-browse(1)
hub-ci-status(1)
hub-compare(1)
hub-create(1)
hub-delete(1)
hub-fork(1)
hub-pull-request(1)
hub-pr(1)
hub-issue(1)
hub-release(1)
hub-sync(1)
Most hub commands are supposed to be run in a context of an existing local git repository. Hub will automatically detect the GitHub repository that the current working directory belongs to by scanning its git remotes.
In case there are multiple git remotes that are all pointing to GitHub, hub assumes that the main one is named "upstream", "github", or "origin", in that order of preference.
When working with forks, it's recommended that the git remote for your own fork is named "origin" and that the git remote for the upstream repository is named "upstream". See https://help.github.com/articles/configuring-a-remote-for-a-fork/
The default branch (usually "master") for the current repository is detected like so:
git symbolic-ref refs/remotes/origin/HEAD
where origin is the name of the git remote for the upstream repository.
The destination where the currently checked out branch is considered to be pushed to depends on the git config push.default setting. If the value is "upstream" or "tracking", the tracking information for a branch is read like so:
git rev-parse --symbolic-full-name BRANCH@{upstream}
Otherwise, hub scans git remotes to find the first one for which refs/remotes/REMOTE/BRANCH
exists. The "origin", "github", and "upstream" remotes are searched last because hub assumes that it's more likely that the current branch is pushed to your fork rather than to the canonical repo.
GitHub OAuth authentication Hub will prompt for GitHub username & password the first time it needs to access the API and exchange it for an OAuth token, which it saves in ~/.config/hub.
To avoid being prompted, use GITHUB_USER and GITHUB_PASSWORD environment variables.
Alternatively, you may provide GITHUB_TOKEN, an access token with repo permissions. This will not be written to ~/.config/hub.
If you prefer the HTTPS protocol for git operations, you can configure hub to generate all URLs with https: instead of git: or ssh::
$ git config --global hub.protocol https
This will affect clone, fork, remote add and other hub commands that expand shorthand references to GitHub repo URLs.
By default, hub will only work with repositories that have remotes which point to github.com. GitHub Enterprise hosts need to be whitelisted to configure hub to treat such remotes same as github.com:
$ git config --global --add hub.host MY.GIT.ORG
The default host for commands like init and clone is still github.com, but this can be affected with the GITHUB_HOST environment variable:
$ GITHUB_HOST=my.git.org git clone myproject
Environment variables
HUB_VERBOSE
Enable verbose output from hub commands.
HUB_CONFIG
The file path where hub configuration is read from and stored. If XDG_CONFIG_HOME is present, the default is $XDG_CONFIG_HOME/hub; otherwise it's $HOME/.config/hub. The configuration file is also searched for in XDG_CONFIG_DIRS per XDG Base Directory Specification.
HUB_PROTOCOL
Use one of "https|ssh|git" as preferred protocol for git clone/push.
GITHUB_TOKEN
OAuth token to use for GitHub API requests.
BUGS
https://github.com/github/hub/issues
AUTHORS https://github.com/github/hub/contributors
SEE ALSO git(1), git-clone(1), git-remote(1), git-init(1), https://github.com/github/hub