setup This command performs an initial setup to connect to GitHub. It basically asks for a username and
a GitHub Personal Access Token (PAT), which is needed to perform most actions.
The token will be stored it in the Git configuration variable hub.oauthtoken for future use. If
you don't have one, you can createit (check GitHubdocs if you need more help). Make sure your
PAT has at least repo and user scope.
The username is also stored for future use in the hub.username variable. If the base URL is
specified, it is stored in hub.baseurl too.
By default configuration is stored in the repository's .git/config file (using gitconfig). If you
want your configuration to be global to your user or system-wide, use the --global or --system
option respectively. These options are passed straight to gitconfig.
-uUSERNAME,--username=USERNAME
GitHub's username (login name), will be stored in the configuration variable hub.username.
If an e-mail is provided, then a username matching that e-mail will be searched and used
instead, if found (for this to work the e-mail must be part of the public profile).
-oTOKEN,--oauthtoken=TOKEN
GitHub's Personal Access Token (PAT), will be stored in the configuration variable
hub.username. If an e-mail is provided, then a username matching that e-mail will be
searched and used instead, if found (for this to work the e-mail must be part of the public
profile).
-bURL,--baseurl=URL
GitHub's base URL to use to access the API. Set this when your GitHub API is in another
location other than the default (Enterprise servers usually use https://host/api/v3).
--global
Store settings in the global configuration (see --global option in gitconfig(1) for
details).
--system
Store settings in the system configuration (see --system option in gitconfig(1) for
details).
cloneREPO[DEST]
This command is used to clone REPO, a GitHub repository, to a DEST directory (defaults to the name
of the project being cloned). If the repository is specified in <owner>/<project> form, the REPO
will be used as upstream and a personal fork will be looked up. If none is found, a new fork will
be created. In both cases, the fork will be cloned instead of the upstream repository. The REPO
can be specified as a regular clone URL too (http, ssh, git), in that case the URL will be
inspected and the hub.urltype will be set as appropriate.
If only <project> is specified as REPO, then the configuration hub.username is used as <owner>,
and the parent repository is looked up at GitHub to determine the real upstream repository.
The upstream repository is cloned as --upstreamremote (or hub.upstreamremote, upstream by
default), the remote for the fork is added as --forkremote (or hub.forkremote, fork by default)
and the fork is set as the git remote.pushdefault (so pushing will hit the fork by default),
unless --no-triangular is used (please see the option for more details).
After cloning and fetching, the git configuration variables hub.upstream, hub.upstreamremote and
hub.forkremote are set in the new cloned repo (see CONFIGURATION).
-UNAME,--upstreamremote=NAME
Use NAME as the upstream remote repository name instead of the default 'upstream').
-FNAME,--forkremote=NAME
Use NAME as the fork remote repository name instead of the default 'fork').
-t,--triangular
Use Git's triangularworkflow configuration (this is the default). This option clones from
the parent/upstream repository, and adds the fork as a remote repository. Then sets the
remote.pushdefault Git option and hub.forkremote git-hub option to the just cloned
repository.
The effect of this having the upstream repository used by default when you pull but using
your fork when you push, which is typically what you want when using GitHub's pull
requests.
Git version 1.8.3 or newer is needed to use this option (and 1.8.4 or newer is recommended
due to some issues in 1.8.3 related to this).
To change the default you can set the option hub.triangular. See CONFIGURATION for details.
--no-triangular
Don't use Git's triangularworkflow configuration (this is only available for backwards
compatibility but is not recommended). This option clones from the forked repository
instead of cloning the upstream/parent repo, so both pulls and pushes will be done with the
fork by default.
This option could be also used to clone a GitHub repository without forking it, but some
functionality of the tool will be lost.
GITCLONEOPTIONS
Any standard gitclone option can be passed. Not all of them might make sense when cloning
a GitHub repo to be used with this tool though.
This command will run the hub.hookscript on some events, please have a look at HOOKSCRIPT for
more details.
issue This command is used to manage GitHub issues through a set of subcommands.
list Show a list of open issues.
-c,--closed
Show closed issues instead.
-C,--created-by-me
Show only issues created by me
-A,--assigned-to-me
Show only issues assigned to me
showISSUE[ISSUE...]
Show issues identified by ISSUE.
new Create a new issue.
The content of the template files ISSUE_TEMPLATE or ISSUE_TEMPLATE.md will be added to the
issue message if any of those template files is found in the top-level directory of the
project, the .github directory or the .git directory. The order for template files lookups
matters and it follows the order as described above for template file names and
directories. And only the content of the first template found will be added.
-mMSG,--message=MSG
Issue title (and description). The first line is used as the issue title and any
text after an empty line is used as the optional body. If this option is not used,
the default GIT_EDITOR is opened to write one.
-lLABEL,--label=LABEL
Attach LABEL to the issue (can be specified multiple times to set multiple labels).
-aUSER,--assign=USER
Assign a user to the issue. USER must be a valid GitHub login name.
-MID,--milestone=ID
Assign the milestone identified by the number ID to the issue.
--no-template
Do not add the template content to the message.
updateISSUE
Similar to new but update an existing issue identified by ISSUE.
A convenient shortcut to close an issue is provided by the close subcommand.
-mMSG,--message=MSG
New issue title (and description). The first line is used as the issue title and any
text after an empty line is used as the optional body.
-tTITLE,--title=TITLE
New issue title.
-e,--edit-message
Open the default GIT_EDITOR to edit the current title (and description) of the
issue.
-o,--open
Reopen the issue.
-c,--close
Close the issue.
-lLABEL,--label=LABEL
If one or more labels are specified, they will replace the current issue labels.
Otherwise the labels are unchanged. If one of the labels is empty, the labels will
be cleared (so you can use -l'' to clear the labels of an issue.
-aUSER,--assign=USER
Assign a user to the issue. USER must be a valid GitHub login name.
-MID,--milestone=ID
Assign the milestone identified by the number ID to the issue.
commentISSUE
Add a new comment to an existing issue identified by ISSUE.
-mMSG,--message=MSG
Comment to be added to the issue. If this option is not used, the default GIT_EDITOR
is opened to write the comment.
closeISSUE
Alias for update--close. (+ comment if --message or --edit-message is specified). Closes
issue identified by ISSUE.
-mMSG,--message=MSG
Add a comment to the issue before closing it.
-e,--edit-message
Open the default GIT_EDITOR to write a comment to be added to the issue before
closing it.
pull This command is used to manage GitHub pull requests. Since pull requests in GitHub are also
issues, most of the subcommands are repeated from the issue command for convenience. Only the list
and new commands are really different, and attach and rebase are added.
list Show a list of open pull requests.
--closed
Show closed pull requests instead.
showPULL[PULL...]
Alias for issueshow.
checkoutPULL...
Checkout the remote branch (head) of the pull request. This command first fetches the head
reference from the pull request and then calls the standard gitcheckout command and any
extra argument will be passed to gitcheckout as-is, after the reference that was just
fetched. Remember this creates a detached checkout by default, use -b if you want to
create a new branch based on the pull request. Please take a look at gitcheckout help for
more details.
new[HEAD]
Create a new pull request. If HEAD is specified, it will be used as the branch (or git ref)
where your changes are implemented. Otherwise the current branch is used. If the branch
used as head is not pushed to your fork remote, a push will be automatically done before
creating the pull request.
The repository to issue the pull request from is taken from the hub.forkrepo configuration,
which defaults to hub.username/<hub.upstreamprojectpart>.
The content of the template files PULL_REQUEST_TEMPLATE or PULL_REQUEST_TEMPLATE.md will be
added to the pull request message if any of those template files is found in the top-level
directory of the project, the .github directory or the .git directory. The order for
template files lookups matters and it follows the order as described above for template
file names and directories. And only the content of the first template found will be added.
-mMSG,--message=MSG
Pull request title (and description). The first line is used as the pull request
title and any text after an empty line is used as the optional body. If this option
is not used, the default GIT_EDITOR is opened. If the HEAD branch have a proper
description (see gitbranch--edit-description), that description will be used as
the default message in the editor and if not, the message of the last commit will be
used instead.
-lLABEL,--label=LABEL
Attach LABEL to the pull request (can be specified multiple times to set multiple
labels).
-aUSER,--assign=USER
Assign a user to the pull request. USER must be a valid GitHub login name.
-MID,--milestone=ID
Assign the milestone identified by the number ID to the pull request.
-bBASE,--base=BASE
Branch (or git ref) you want your changes pulled into. By default the tracking
branch (branch.<ref>.merge configuration variable) is used or the configuration
hub.pullbase if not tracking a remote branch. If none is present an error will be
displayed.
-cNAME,--create-branch=NAME
Create a new remote branch with (with name NAME) as the real head for the pull
request instead of using the HEAD name passed as HEAD. This is useful to create a
pull request for a hot-fix you committed to your regular HEAD without creating a
branch first.
-f,--force-push
Force the push operations. Use with care!
-d,--draft
Create a draft pull request. Draft pull requests cannot be merged, and code owners
are not automatically requested to review draft pull requests.
attachISSUE[HEAD]
Convert the issue identified by ISSUE to a pull request by attaching commits to it. The
branch (or git ref) where your changes are implemented can be optionally specified with
HEAD (otherwise the current branch is used). This subcommand is very similar to the new
subcommand, please refer to it for more details.
Please note you can only attach commits to issues if you have commit access to the
repository or if you are assigned to the issue.
-mMSG,--message=MSG
Add a comment to the issue/new pull request.
-e,--edit-message
Open the default GIT_EDITOR to write a comment to be added to the issue/new pull
request. The default message is taken from the --message option if present,
otherwise the branch description or the first commit message is used as with the new
subcommand.
-bBASE,--base=BASE
Same as pullnew, please see the details there.
-cNAME,--create-branch=NAME
Create a new remote branch with (with name NAME) as the real head for the pull
request instead of using the HEAD name passed as HEAD. This is useful to create a
pull request for a hot-fix you committed to your regular HEAD without creating a
branch first.
-f,--force-push
Force the push operations. Use with care!
rebasePULL
Close a pull request identified by PULL by rebasing its base branch (specified in the pull
request) instead of merging as GitHub's MergeButton™ would do.
If the operation is successful, a comment will be posted informing the new HEAD commit of
the branch that has been rebased and the pull request will be closed.
The type of URL used to fetch and push can be specified through the hub.pullurltype
configuration variable (see CONFIGURATION for more details). Your working copy should stay
the same ideally, if everything went OK.
The operations performed by this subcommand are roughly these:
1. git stash
2. git fetch pullhead
3. git checkout -b tmp FETCH_HEAD
4. git pull --rebase pullbase
5. git push pullbase
6. git checkout oldhead
7. git branch -D tmp
8. git stash pop
If hub.forcerebase is set to "true" (the default), --force will be passed to rebase (not to
be confused with this command option --force-push which will force the push), otherwise (if
is "false") a regular rebase is performed. When the rebase is forced, all the commits in
the pull request are re-committed, so the Committer and CommitterDate metadata is updated
in the commits, showing the person that performed the rebase and the time of the rebase
instead of the original values, so providing more useful information. As a side effect, the
hashes of the commits will change.
If conflicts are found, the command is interrupted, similarly to how gitrebase would do.
The user should either --abort the rebasing, --skip the conflicting commit or resolve the
conflict and --continue. When using one of these actions, you have to omit the PULL
argument.
-mMSG,--message=MSG
Use this message for the comment instead of the default. Specify an empty message
(-m'') to completely omit the comment.
-e,--edit-message
Open the default GIT_EDITOR to write the comment.
--force-push
Force the push operations. Use with care!
-p,--pause
Pause the rebase just before the results are pushed and the issue is merged. To
resume the pull request rebasing (push the changes upstream and close the issue),
just use the --continue action. This is particularly useful for testing.
-u,--stash-include-untracked
Passes the --include-untracked option to stash. If used all untracked files are also
stashed and then cleaned up with git clean, leaving the working directory in a very
clean state, which avoid conflicts when checking out the pull request to rebase.
-a,--stash-all
Passes the --all option to stash. Is like --stash-include-untracked but the ignored
files are stashed and cleaned in addition to the untracked files, which completely
removes the possibility of conflicts when checking out the pull request to rebase.
-D,--delete-branch
Delete the pull request branch if the rebase was successful. This is similar to
press the "Delete Branch" Button (TM) in the web interface after merging.
Actions:
--continue
Continue an ongoing rebase.
--abort
Abort an ongoing rebase.
--skip Skip current patch in an ongoing rebase and continue.
updatePULL
Alias for issueupdate.
commentPULL
Alias for issuecomment.
closePULL
Alias for issueclose.
Install Now
Emojis
PNG Icons