.TH "hub" "1" "18 Oct 2023" "hub version 2.14.2" "hub manual"
.nh
.ad l
.SH "NAME"
hub \- make git easier with GitHub
.SH "SYNOPSIS"
.P
\fB\fChub\fR [\-\-noop] \fICOMMAND\fP [\fIOPTIONS\fP]
.br
\fB\fChub alias\fR [\-s] [\fISHELL\fP]
.br
\fB\fChub help\fR hub\-\fICOMMAND\fP
.SH "DESCRIPTION"
.P
Hub is a tool that wraps git in order to extend it with extra functionality that
makes it better when working with GitHub.
.SH "COMMANDS"
.P
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.
.SS "Extended git commands"
.PP
hub\-am(1)
.RS 4
Replicate commits from a GitHub pull request locally.
.RE
.PP
hub\-apply(1)
.RS 4
Download a patch from GitHub and apply it locally.
.RE
.PP
hub\-checkout(1)
.RS 4
Check out the head of a pull request as a local branch.
.RE
.PP
hub\-cherry\-pick(1)
.RS 4
Cherry\-pick a commit from a fork on GitHub.
.RE
.PP
hub\-clone(1)
.RS 4
Clone a repository from GitHub.
.RE
.PP
hub\-fetch(1)
.RS 4
Add missing remotes prior to performing git fetch.
.RE
.PP
hub\-init(1)
.RS 4
Initialize a git repository and add a remote pointing to GitHub.
.RE
.PP
hub\-merge(1)
.RS 4
Merge a pull request locally with a message like the GitHub Merge Button.
.RE
.PP
hub\-push(1)
.RS 4
Push a git branch to each of the listed remotes.
.RE
.PP
hub\-remote(1)
.RS 4
Add a git remote for a GitHub repository.
.RE
.PP
hub\-submodule(1)
.RS 4
Add a git submodule for a GitHub repository.
.RE
.br
.SS "New commands provided by hub"
.PP
hub\-alias(1)
.RS 4
Show shell instructions for wrapping git.
.RE
.PP
hub\-api(1)
.RS 4
Low\-level GitHub API request interface.
.RE
.PP
hub\-browse(1)
.RS 4
Open a GitHub repository in a web browser.
.RE
.PP
hub\-ci\-status(1)
.RS 4
Display status of GitHub checks for a commit.
.RE
.PP
hub\-compare(1)
.RS 4
Open a GitHub compare page in a web browser.
.RE
.PP
hub\-create(1)
.RS 4
Create a new repository on GitHub and add a git remote for it.
.RE
.PP
hub\-delete(1)
.RS 4
Delete a repository on GitHub.
.RE
.PP
hub\-fork(1)
.RS 4
Fork the current repository on GitHub and add a git remote for it.
.RE
.PP
hub\-gist(1)
.RS 4
Create and print GitHub Gists.
.RE
.PP
hub\-pull\-request(1)
.RS 4
Create a GitHub Pull Request.
.RE
.PP
hub\-pr(1)
.RS 4
Manage GitHub Pull Requests for the current repository.
.RE
.PP
hub\-issue(1)
.RS 4
Manage GitHub Issues for the current repository.
.RE
.PP
hub\-release(1)
.RS 4
Manage GitHub Releases for the current repository.
.RE
.PP
hub\-sync(1)
.RS 4
Fetch git objects from upstream and update local branches.
.RE
.br
.SH "CONVENTIONS"
.P
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.
.P
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.
.P
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 \[la]https://help.github.com/articles/configuring\-a\-remote\-for\-a\-fork/\[ra]
.P
The default branch (usually "master") for the current repository is detected
like so:
.PP
.RS 4
.nf
git symbolic\-ref refs/remotes/origin/HEAD
.fi
.RE
.P
where \fIorigin\fP is the name of the git remote for the upstream repository.
.P
The destination where the currently checked out branch is considered to be
pushed to depends on the \fB\fCgit config push.default\fR setting. If the value is
"upstream" or "tracking", the tracking information for a branch is read like so:
.PP
.RS 4
.nf
git rev\-parse \-\-symbolic\-full\-name BRANCH@{upstream}
.fi
.RE
.P
Otherwise, hub scans git remotes to find the first one for which
\fB\fCrefs/remotes/REMOTE/BRANCH\fR 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.
.SH "CONFIGURATION"
.SS "GitHub OAuth authentication"
.P
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 \fB\fC\(ti/.config/hub\fR.
.P
To avoid being prompted, use \fB\fCGITHUB\_USER\fR and \fB\fCGITHUB\_PASSWORD\fR environment
variables.
.P
Alternatively, you may provide \fB\fCGITHUB\_TOKEN\fR, an access token with
\fBrepo\fP permissions. This will not be written to \fB\fC\(ti/.config/hub\fR.
.SS "HTTPS instead of git protocol"
.P
If you prefer the HTTPS protocol for git operations, you can configure hub to
generate all URLs with \fB\fChttps:\fR instead of \fB\fCgit:\fR or \fB\fCssh:\fR:
.PP
.RS 4
.nf
$ git config \-\-global hub.protocol https
.fi
.RE
.P
This will affect \fB\fCclone\fR, \fB\fCfork\fR, \fB\fCremote add\fR and other hub commands that
expand shorthand references to GitHub repo URLs.
.SS "GitHub Enterprise"
.P
By default, hub will only work with repositories that have remotes which
point to \fB\fCgithub.com\fR. GitHub Enterprise hosts need to be whitelisted to
configure hub to treat such remotes same as github.com:
.PP
.RS 4
.nf
$ git config \-\-global \-\-add hub.host MY.GIT.ORG
.fi
.RE
.P
The default host for commands like \fB\fCinit\fR and \fB\fCclone\fR is still \fB\fCgithub.com\fR, but
this can be affected with the \fB\fCGITHUB\_HOST\fR environment variable:
.PP
.RS 4
.nf
$ GITHUB\_HOST=my.git.org git clone myproject
.fi
.RE
.SS "Environment variables"
.PP
\fB\fCHUB\_VERBOSE\fR
.RS 4
If this environment variable is set, verbose logging will be printed to
stderr.
.RE
.PP
\fB\fCHUB\_CONFIG\fR
.RS 4
The file path where hub configuration is read from and stored. If
\fB\fCXDG\_CONFIG\_HOME\fR is present, the default is \fB\fC$XDG\_CONFIG\_HOME/hub\fR;
otherwise it\'s \fB\fC$HOME/.config/hub\fR. The configuration file is also
searched for in \fB\fCXDG\_CONFIG\_DIRS\fR per XDG Base Directory Specification.
.RE
.PP
\fB\fCHUB\_PROTOCOL\fR
.RS 4
One of "https", "ssh", or "git" as preferred protocol for git clone/push.
.RE
.PP
\fB\fCGITHUB\_HOST\fR
.RS 4
The GitHub hostname to default to instead of "github.com".
.RE
.PP
\fB\fCGITHUB\_TOKEN\fR
.RS 4
OAuth token to use for GitHub API requests.
.RE
.PP
\fB\fCGITHUB\_USER\fR
.RS 4
The GitHub username of the actor of GitHub API operations.
.RE
.PP
\fB\fCGITHUB\_PASSWORD\fR
.RS 4
The GitHub password used to exchange user credentials for an OAuth token
that gets stored in hub configuration. If not set, it may be interactively
prompted for on first run.
.RE
.PP
\fB\fCGITHUB\_REPOSITORY\fR
.RS 4
A value in "OWNER/REPO" format that specifies the repository that API
operations should be performed against. Currently only used to infer the
default value of \fB\fCGITHUB\_USER\fR for API requests.
.RE
.br
.SH "BUGS"
.P
\[la]https://github.com/github/hub/issues\[ra]
.SH "AUTHORS"
.P
\[la]https://github.com/github/hub/contributors\[ra]
.SH "SEE ALSO"
.P
git(1), git\-clone(1), git\-remote(1), git\-init(1),
\[la]https://github.com/github/hub\[ra]