124 lines (79 sloc) 3.25 KB
hub(1) -- make git easier with GitHub
=====================================
## SYNOPSIS
`hub` [`--noop`] <COMMAND> [<OPTIONS>]
`hub alias` [`-s`] [<SHELL>]
`hub help` hub-<COMMAND>
## DESCRIPTION
Hub is a tool that wraps git in order to extend it with extra functionality that
makes it better when working with GitHub.
## COMMANDS
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.
### Extended git commands
* hub-am(1):
Replicate commits from a GitHub pull request locally.
* hub-apply(1):
Download a patch from GitHub and apply it locally.
* hub-checkout(1):
Check out the head of a pull request as a local branch.
* hub-cherry-pick(1):
Cherry-pick a commit from a fork on GitHub.
* hub-clone(1):
Clone a repository from GitHub.
* hub-fetch(1):
Add missing remotes prior to performing git fetch.
* hub-init(1):
Initialize a git repository and create it on GitHub.
* hub-merge(1):
Merge a pull request with a message like the GitHub Merge Button.
* hub-push(1):
Push a git branch to each of the listed remotes.
* hub-remote(1):
Add a git remote for a GitHub repository.
* hub-submodule(1):
Add a git submodule for a GitHub repository.
### New commands provided by hub
* hub-alias(1):
Show shell instructions for wrapping git.
* hub-browse(1):
Open a GitHub repository in a web browser.
* hub-ci-status(1):
Display GitHub Status information for a commit.
* hub-compare(1):
Open a GitHub compare page in a web browser.
* hub-create(1):
Create a new repository on GitHub and add a git remote for it.
* hub-fork(1):
Fork the current project on GitHub and add a git remote for it.
* hub-pull-request(1):
Create a GitHub pull request.
## CONFIGURATION
### 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`.
### HTTPS instead of git protocol
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.
### GitHub Enterprise
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
## 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>