.\" Man page generated from reStructuredText. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "GIT-HUB" 1 "2022-01-30" "devel" "Git Manual" .SH NAME git-hub \- Git command line interface to GitHub .SH SYNOPSIS .sp git hub [global options] [options] [arguments] .SH DESCRIPTION .sp \fIgit hub\fP is a simple command line interface to github, enabling most useful GitHub tasks (like creating and listing pull request or issues) to be accessed directly through the git command line. .sp To use this command you\(aqll probably need to make an initial configuration to get authorization from GitHub. To do this you can use the \fIsetup\fP command. See the \fI\%CONFIGURATION\fP section for more configuration options. .SH GLOBAL OPTIONS .INDENT 0.0 .TP .B \-h, \-\-help Show this help and exit. .TP .B \-\-version Show program\(aqs version number and exit. .TP .B \-v, \-\-verbose Be more verbose (can be specified multiple times to get extra verbosity) .TP .B \-s, \-\-silent Be less verbose (can be specified multiple times to get less verbosity) .UNINDENT .SH COMMANDS .INDENT 0.0 .TP .B \fIsetup\fP 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. .sp The token will be stored it in the Git configuration variable \fIhub.oauthtoken\fP for future use. If you don\(aqt have one, you can \fI\%create it\fP (check \fI\%GitHub docs\fP if you need more help). Make sure your PAT has at least \fBrepo\fP and \fBuser\fP scope. .sp The username is also stored for future use in the \fIhub.username\fP variable. If the base URL is specified, it is stored in \fIhub.baseurl\fP too. .sp By default configuration is stored in the repository\(aqs \fB\&.git/config\fP file (using \fBgit config\fP). If you want your configuration to be global to your user or system\-wide, use the \fB\-\-global\fP or \fB\-\-system\fP option respectively. These options are passed straight to \fBgit config\fP\&. .INDENT 7.0 .TP .B \-u USERNAME, \-\-username=USERNAME GitHub\(aqs username (login name), will be stored in the configuration variable \fIhub.username\fP\&. 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). .TP .B \-o TOKEN, \-\-oauthtoken=TOKEN GitHub\(aqs Personal Access Token (PAT), will be stored in the configuration variable \fIhub.username\fP\&. 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). .TP .B \-b URL, \-\-baseurl=URL GitHub\(aqs 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 \fI\%https://host/api/v3\fP). .TP .B \-\-global Store settings in the global configuration (see \-\-global option in \fIgit config(1)\fP for details). .TP .B \-\-system Store settings in the system configuration (see \-\-system option in \fIgit config(1)\fP for details). .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \fIclone\fP REPO [DEST] This command is used to clone \fBREPO\fP, a GitHub repository, to a \fBDEST\fP directory (defaults to the name of the project being cloned). If the repository is specified in \fI/\fP form, the \fBREPO\fP 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 \fBREPO\fP can be specified as a regular \fIclone\fP URL too (http, ssh, git), in that case the URL will be inspected and the \fIhub.urltype\fP will be set as appropriate. .sp If only \fI\fP is specified as \fBREPO\fP, then the configuration \fIhub.username\fP is used as \fI\fP, and the parent repository is looked up at GitHub to determine the real upstream repository. .sp The upstream repository is cloned as \fI\-\-upstreamremote\fP (or \fIhub.upstreamremote\fP, \fIupstream\fP by default), the remote for the fork is added as \fI\-\-forkremote\fP (or \fIhub.forkremote\fP, \fIfork\fP by default) and the fork is set as the git \fIremote.pushdefault\fP (so pushing will hit the fork by default), unless \fI\-\-no\-triangular\fP is used (please see the option for more details). .sp After cloning and fetching, the git configuration variables \fIhub.upstream\fP, \fIhub.upstreamremote\fP and \fIhub.forkremote\fP are set in the new cloned repo (see \fI\%CONFIGURATION\fP). .INDENT 7.0 .TP .B \-U NAME, \-\-upstreamremote=NAME Use \fINAME\fP as the upstream remote repository name instead of the default \(aqupstream\(aq). .TP .B \-F NAME, \-\-forkremote=NAME Use \fINAME\fP as the fork remote repository name instead of the default \(aqfork\(aq). .TP .B \-t, \-\-triangular Use Git\(aqs \fItriangular workflow\fP configuration (this is the default). This option clones from the parent/upstream repository, and adds the fork as a remote repository. Then sets the \fIremote.pushdefault\fP Git option and \fIhub.forkremote\fP git\-hub option to the just cloned repository. .sp 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\(aqs pull requests. .sp 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). .sp To change the default you can set the option \fIhub.triangular\fP\&. See \fI\%CONFIGURATION\fP for details. .TP .B \-\-no\-triangular Don\(aqt use Git\(aqs \fItriangular workflow\fP 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. .sp This option could be also used to clone a GitHub repository without forking it, but some functionality of the tool will be lost. .TP .B GIT CLONE OPTIONS Any standard \fBgit clone\fP option can be passed. Not all of them might make sense when cloning a GitHub repo to be used with this tool though. .UNINDENT .sp This command will run the \fIhub.hookscript\fP on some events, please have a look at \fI\%HOOK SCRIPT\fP for more details. .TP .B \fIissue\fP This command is used to manage GitHub issues through a set of subcommands. .INDENT 7.0 .TP .B \fIlist\fP Show a list of open issues. .INDENT 7.0 .TP .B \-c, \-\-closed Show closed issues instead. .TP .B \-C, \-\-created\-by\-me Show only issues created by me .TP .B \-A, \-\-assigned\-to\-me Show only issues assigned to me .UNINDENT .TP .B \fIshow\fP ISSUE [ISSUE ...] Show issues identified by \fBISSUE\fP\&. .TP .B \fInew\fP Create a new issue. .sp The content of the template files \fBISSUE_TEMPLATE\fP or \fBISSUE_TEMPLATE.md\fP will be added to the issue message if any of those template files is found in the top\-level directory of the project, the \fB\&.github\fP directory or the \fB\&.git\fP 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. .INDENT 7.0 .TP .B \-m MSG, \-\-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 \fIGIT_EDITOR\fP is opened to write one. .TP .B \-l LABEL, \-\-label=LABEL Attach \fILABEL\fP to the issue (can be specified multiple times to set multiple labels). .TP .B \-a USER, \-\-assign=USER Assign a user to the issue. \fIUSER\fP must be a valid GitHub login name. .TP .B \-M ID, \-\-milestone=ID Assign the milestone identified by the number ID to the issue. .TP .B \-\-no\-template Do not add the template content to the message. .UNINDENT .TP .B \fIupdate\fP ISSUE Similar to \fInew\fP but update an existing issue identified by \fBISSUE\fP\&. .sp A convenient shortcut to close an issue is provided by the \fIclose\fP subcommand. .INDENT 7.0 .TP .B \-m MSG, \-\-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. .TP .B \-t TITLE, \-\-title=TITLE New issue title. .TP .B \-e, \-\-edit\-message Open the default \fIGIT_EDITOR\fP to edit the current title (and description) of the issue. .TP .B \-o, \-\-open Reopen the issue. .TP .B \-c, \-\-close Close the issue. .TP .B \-l LABEL, \-\-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 \fB\-l\(aq\(aq\fP to clear the labels of an issue. .TP .B \-a USER, \-\-assign=USER Assign a user to the issue. \fIUSER\fP must be a valid GitHub login name. .TP .B \-M ID, \-\-milestone=ID Assign the milestone identified by the number ID to the issue. .UNINDENT .TP .B \fIcomment\fP ISSUE Add a new comment to an existing issue identified by \fBISSUE\fP\&. .INDENT 7.0 .TP .B \-m MSG, \-\-message=MSG Comment to be added to the issue. If this option is not used, the default \fIGIT_EDITOR\fP is opened to write the comment. .UNINDENT .TP .B \fIclose\fP ISSUE Alias for \fIupdate \-\-close\fP\&. (+ \fIcomment\fP if \fB\-\-message\fP or \fB\-\-edit\-message\fP is specified). Closes issue identified by \fBISSUE\fP\&. .INDENT 7.0 .TP .B \-m MSG, \-\-message=MSG Add a comment to the issue before closing it. .TP .B \-e, \-\-edit\-message Open the default \fIGIT_EDITOR\fP to write a comment to be added to the issue before closing it. .UNINDENT .UNINDENT .TP .B \fIpull\fP 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 \fIissue\fP command for convenience. Only the \fIlist\fP and \fInew\fP commands are really different, and \fIattach\fP and \fIrebase\fP are added. .INDENT 7.0 .TP .B \fIlist\fP Show a list of open pull requests. .INDENT 7.0 .TP .B \-\-closed Show closed pull requests instead. .UNINDENT .TP .B \fIshow\fP PULL [PULL ...] Alias for \fIissue show\fP\&. .TP .B \fIcheckout\fP PULL ... Checkout the remote branch (head) of the pull request. This command first fetches the \fIhead\fP reference from the pull request and then calls the standard \fIgit checkout\fP command and any extra argument will be passed to \fIgit checkout\fP as\-is, after the reference that was just fetched. Remember this creates a detached checkout by default, use \fI\-b\fP if you want to create a new branch based on the pull request. Please take a look at \fIgit checkout\fP help for more details. .TP .B \fInew\fP [HEAD] Create a new pull request. If \fBHEAD\fP 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. .sp The repository to issue the pull request from is taken from the \fIhub.forkrepo\fP configuration, which defaults to \fIhub.username/\fP\&. .sp The content of the template files \fBPULL_REQUEST_TEMPLATE\fP or \fBPULL_REQUEST_TEMPLATE.md\fP 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 \fB\&.github\fP directory or the \fB\&.git\fP 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. .INDENT 7.0 .TP .B \-m MSG, \-\-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 \fIGIT_EDITOR\fP is opened. If the HEAD branch have a proper description (see \fIgit branch \-\-edit\-description\fP), 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. .TP .B \-l LABEL, \-\-label=LABEL Attach \fILABEL\fP to the pull request (can be specified multiple times to set multiple labels). .TP .B \-a USER, \-\-assign=USER Assign a user to the pull request. \fIUSER\fP must be a valid GitHub login name. .TP .B \-M ID, \-\-milestone=ID Assign the milestone identified by the number ID to the pull request. .TP .B \-b BASE, \-\-base=BASE Branch (or git ref) you want your changes pulled into. By default the tracking branch (\fIbranch..merge\fP configuration variable) is used or the configuration \fIhub.pullbase\fP if not tracking a remote branch. If none is present an error will be displayed. .TP .B \-c NAME, \-\-create\-branch=NAME Create a new remote branch with (with name \fBNAME\fP) as the real head for the pull request instead of using the HEAD name passed as \fBHEAD\fP\&. This is useful to create a pull request for a hot\-fix you committed to your regular HEAD without creating a branch first. .TP .B \-f, \-\-force\-push Force the push operations. Use with care! .TP .B \-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. .UNINDENT .TP .B \fIattach\fP ISSUE [HEAD] Convert the issue identified by \fBISSUE\fP to a pull request by attaching commits to it. The branch (or git ref) where your changes are implemented can be optionally specified with \fBHEAD\fP (otherwise the current branch is used). This subcommand is very similar to the \fInew\fP subcommand, please refer to it for more details. .sp 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. .INDENT 7.0 .TP .B \-m MSG, \-\-message=MSG Add a comment to the issue/new pull request. .TP .B \-e, \-\-edit\-message Open the default \fIGIT_EDITOR\fP to write a comment to be added to the issue/new pull request. The default message is taken from the \fB\-\-message\fP option if present, otherwise the branch description or the first commit message is used as with the \fInew\fP subcommand. .TP .B \-b BASE, \-\-base=BASE Same as \fIpull new\fP, please see the details there. .TP .B \-c NAME, \-\-create\-branch=NAME Create a new remote branch with (with name \fBNAME\fP) as the real head for the pull request instead of using the HEAD name passed as \fBHEAD\fP\&. This is useful to create a pull request for a hot\-fix you committed to your regular HEAD without creating a branch first. .TP .B \-f, \-\-force\-push Force the push operations. Use with care! .UNINDENT .TP .B \fIrebase\fP PULL Close a pull request identified by \fBPULL\fP by rebasing its base branch (specified in the pull request) instead of merging as GitHub\(aqs \fIMerge Button™\fP would do. .sp 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. .sp The type of URL used to fetch and push can be specified through the \fIhub.pullurltype\fP configuration variable (see \fI\%CONFIGURATION\fP for more details). Your working copy should stay the same ideally, if everything went OK. .sp The operations performed by this subcommand are roughly these: .INDENT 7.0 .IP 1. 3 git stash .IP 2. 3 git fetch \fIpullhead\fP .IP 3. 3 git checkout \-b \fItmp\fP FETCH_HEAD .IP 4. 3 git pull \-\-rebase \fIpullbase\fP .IP 5. 3 git push \fIpullbase\fP .IP 6. 3 git checkout \fIoldhead\fP .IP 7. 3 git branch \-D \fItmp\fP .IP 8. 3 git stash pop .UNINDENT .sp If \fIhub.forcerebase\fP is set to "true" (the default), \fB\-\-force\fP will be passed to rebase (not to be confused with this command option \fB\-\-force\-push\fP 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. .sp If conflicts are found, the command is interrupted, similarly to how \fIgit rebase\fP would do. The user should either \fB\-\-abort\fP the rebasing, \fB\-\-skip\fP the conflicting commit or resolve the conflict and \fB\-\-continue\fP\&. When using one of these actions, you have to omit the \fBPULL\fP argument. .INDENT 7.0 .TP .B \-m MSG, \-\-message=MSG Use this message for the comment instead of the default. Specify an empty message (\fB\-m\(aq\(aq\fP) to completely omit the comment. .TP .B \-e, \-\-edit\-message Open the default \fIGIT_EDITOR\fP to write the comment. .TP .B \-\-force\-push Force the push operations. Use with care! .TP .B \-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 \fB\-\-continue\fP action. This is particularly useful for testing. .TP .B \-u, \-\-stash\-include\-untracked Passes the \fB\-\-include\-untracked\fP 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. .TP .B \-a, \-\-stash\-all Passes the \fB\-\-all\fP option to stash. Is like \fB\-\-stash\-include\-untracked\fP 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. .TP .B \-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. .UNINDENT .sp Actions: .INDENT 7.0 .TP .B \-\-continue Continue an ongoing rebase. .TP .B \-\-abort Abort an ongoing rebase. .TP .B \-\-skip Skip current patch in an ongoing rebase and continue. .UNINDENT .TP .B \fIupdate\fP PULL Alias for \fIissue update\fP\&. .TP .B \fIcomment\fP PULL Alias for \fIissue comment\fP\&. .TP .B \fIclose\fP PULL Alias for \fIissue close\fP\&. .UNINDENT .UNINDENT .SH HOOK SCRIPT .sp If the git configuration \fIhub.hookscript\fP is present, it will be used as a (shell) script to execute on certain events. Some data is passed as environment variables to the script. All events will set the \fIHUB_HOOK\fP environment variable with the name of the hook being executed. .sp \fBNOTE:\fP This is an experimental feature, so it is only enabled for one event only so far. .sp Available hooks (events): .INDENT 0.0 .TP .B \fIpostclone\fP Executed after a \fIclone\fP command was done successfully. The script will be run with the freshly cloned repository directory as the current working directory, so the git configuration just done by the \fIclone\fP command is available (for example, \fIgit config hub.forkremote\fP will get the fork remote). .sp The following extra environment variables are defined: .INDENT 7.0 .TP .B \fIHUB_TRIANGULAR\fP will be set to \fItrue\fP if the clone was done in triangular mode and to \fIfalse\fP otherwise. .TP .B \fIHUB_FETCHREMOTE\fP will be set to \fIhub.forkremote\fP if \fItriangular\fP was used and to \fIhub.upstreamremote\fP otherwise. .UNINDENT .sp This hook is useful to set some extra git configuration that should be enabled only when cloning a repository via this tool. For example, to prune the \fIfork\fP remote when it is updated, but only when \fItriangular\fP was used in the clone you can use: .sp \fIgit config \-\-global hub.hookscript \(aqif test "$HUB_HOOK" = postclone && $HUB_TRIANGULAR ; then git config remote.fork.prune true; fi\(aq\fP .UNINDENT .SH CONFIGURATION .sp This program use the git configuration facilities to get its configuration from. These are the git config keys used: .INDENT 0.0 .TP .B \fIhub.username\fP Your GitHub username. [default: \fIcurrent OS username\fP] .TP .B \fIhub.oauthtoken\fP required This is the authorization token obtained via the \fIsetup\fP command. Even when required, you shouldn\(aqt need to set this variable manually. Use the \fIsetup\fP command instead. .sp If you don\(aqt want to store the token in plain text, you can also specify a command by prefixing a \fI!\fP\&. The output of that command will be used as the token. The command will be run with the default shell. .sp For example: \fIoauthtoken = !password\-manager ~/my.db get github\-oauth\-token\fP\&. .TP .B \fIhub.upstream\fP required Blessed repository used to get the issues from and make the pull requests to. The format is \fI/\fP\&. This option can be automatically set by the \fIclone\fP command and is not really required by it or the \fIsetup\fP command. .TP .B \fIhub.upstreamremote\fP Remote name for accessing the upstream repository [default: \fIupstream\fP]. .TP .B \fIhub.forkrepo\fP Your blessed repository fork. The format is \fI/\fP\&. Used to set the head for your pull requests. [default: \fI/(upstream part)\fP] .TP .B \fIhub.forkremote\fP Remote name for accessing your fork. Used to push branches before creating a pull request. [default: \fIfork\fP] .TP .B \fIhub.pullbase\fP Default remote branch (or git reference) you want your changes pulled into when creating a pull request. [default: \fImaster\fP] .TP .B \fIhub.urltype\fP Type of URL to use when an URL from a GitHub API is needed (for example, when \(aqpull rebase\(aq is used). At the time of writing it could be \fIssh_url\fP or \fIclone_url\fP for HTTP). See GitHub\(aqs API documentation[1] for more details or options. [default: \fIssh_url\fP] .TP .B \fIhub.baseurl\fP GitHub\(aqs 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 \fI\%https://host/api/v3\fP). This will be prepended to all GitHub API calls and it has to be a full URL, not just something like "www.example.com/api/v3/". .TP .B \fIhub.forcerebase\fP If is set to "true", \fB\-\-force\fP will be passed to rebase. If is set to "false" a regular rebase is performed. See the \fIpull\fP \fIrebase\fP command for details. [default: \fItrue\fP] .TP .B \fIhub.triangular\fP Makes \fB\-\-triangular\fP for \fIclone\fP if set to "true" (boolean value). See \fIclone\fP documentation for details. .TP .B \fIhub.hookscript\fP Script to run on certain events. Please have a look at \fI\%HOOK SCRIPT\fP for more details. .UNINDENT .sp [1] \fI\%https://developer.github.com/v3/pulls/#get\-a\-single\-pull\-request\fP .SH FILES .sp This program creates some temporary files in the \(aq.git\(aq directory during its operation. The contents of these files can be used for debugging/recovery purposes if necessary. .INDENT 0.0 .TP .B \fIHUB_EDITMSG\fP This file is used to take input from the user, e.g. issue comments, pull request title & description etc. If, after accepting user input, the command given by the user fails for some reason, then the entered text can still be retrieved from this file. .TP .B \fIHUB_PULL_REBASING\fP This file is used to store various metadata information related to a rebase operation (with the primary aim of being able to rollback the repository to its original state if the rebase fails or is interrupted due to conflicts). The sole presence of this file indicates that a rebase is in progress. .UNINDENT .SH VIM SYNTAX HIGHLIGHT .sp A VIM ftdetect plugin is provided, to enable it you have to follow some steps though. All you need to do is copy (or preferably make a symbolic link) the script to \fI~/.vim/ftdetect/githubmsg.vim\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mkdir \-p ~/.vim/ftdetect ln \-s /usr/share/vim/addons/ftdetect/githubmsg.vim ~/.vim/ftdetect/ # or if you are copying from the sources: # ln \-s ftdetect.vim ~/.vim/ftdetect/githubmsg.vim .ft P .fi .UNINDENT .UNINDENT .\" vim: set et sw=2 : . .SH AUTHOR Leandro Lucarella .SH COPYRIGHT 2013 dunnhumby Germany GmbH .\" Generated by docutils manpage writer. .