github.com/trevoraustin/hub@v2.2.0-preview1.0.20141105230840-96d8bfc654cc+incompatible/man/hub.1 (about)

     1  .\" generated with Ronn/v0.7.3
     2  .\" http://github.com/rtomayko/ronn/tree/0.7.3
     3  .
     4  .TH "HUB" "1" "October 2014" "GITHUB" "Hub Manual"
     5  .
     6  .SH "NAME"
     7  \fBhub\fR \- git + hub = github
     8  .
     9  .SH "SYNOPSIS"
    10  \fBhub\fR [\fB\-\-noop\fR] \fICOMMAND\fR \fIOPTIONS\fR
    11  .
    12  .br
    13  \fBhub alias\fR [\fB\-s\fR] [\fISHELL\fR]
    14  .
    15  .SS "Expanded git commands:"
    16  \fBgit init \-g\fR \fIOPTIONS\fR
    17  .
    18  .br
    19  \fBgit clone\fR [\fB\-p\fR] \fIOPTIONS\fR [\fIUSER\fR/]\fIREPOSITORY\fR \fIDIRECTORY\fR
    20  .
    21  .br
    22  \fBgit remote add\fR [\fB\-p\fR] \fIOPTIONS\fR \fIUSER\fR[/\fIREPOSITORY\fR]
    23  .
    24  .br
    25  \fBgit remote set\-url\fR [\fB\-p\fR] \fIOPTIONS\fR \fIREMOTE\-NAME\fR \fIUSER\fR[/\fIREPOSITORY\fR]
    26  .
    27  .br
    28  \fBgit fetch\fR \fIUSER\-1\fR,[\fIUSER\-2\fR,\.\.\.]
    29  .
    30  .br
    31  \fBgit checkout\fR \fIPULLREQ\-URL\fR [\fIBRANCH\fR]
    32  .
    33  .br
    34  \fBgit merge\fR \fIPULLREQ\-URL\fR
    35  .
    36  .br
    37  \fBgit cherry\-pick\fR \fIGITHUB\-REF\fR
    38  .
    39  .br
    40  \fBgit am\fR \fIGITHUB\-URL\fR
    41  .
    42  .br
    43  \fBgit apply\fR \fIGITHUB\-URL\fR
    44  .
    45  .br
    46  \fBgit push\fR \fIREMOTE\-1\fR,\fIREMOTE\-2\fR,\.\.\.,\fIREMOTE\-N\fR [\fIREF\fR]
    47  .
    48  .br
    49  \fBgit submodule add\fR [\fB\-p\fR] \fIOPTIONS\fR [\fIUSER\fR/]\fIREPOSITORY\fR \fIDIRECTORY\fR
    50  .
    51  .SS "Custom git commands:"
    52  \fBgit create\fR [\fINAME\fR] [\fB\-p\fR] [\fB\-d\fR \fIDESCRIPTION\fR] [\fB\-h\fR \fIHOMEPAGE\fR]
    53  .
    54  .br
    55  \fBgit browse\fR [\fB\-u\fR] [[\fIUSER\fR\fB/\fR]\fIREPOSITORY\fR] [SUBPAGE]
    56  .
    57  .br
    58  \fBgit compare\fR [\fB\-u\fR] [\fIUSER\fR] [[\fISTART\fR\.\.\.]\fIEND\fR]
    59  .
    60  .br
    61  \fBgit fork\fR [\fB\-\-no\-remote\fR]
    62  .
    63  .br
    64  \fBgit pull\-request\fR [\fB\-o\fR|\fB\-\-browse\fR] [\fB\-f\fR] [\fB\-m\fR \fIMESSAGE\fR|\fB\-F\fR \fIFILE\fR|\fB\-i\fR \fIISSUE\fR|\fIISSUE\-URL\fR] [\fB\-b\fR \fIBASE\fR] [\fB\-h\fR \fIHEAD\fR]
    65  .
    66  .br
    67  \fBgit ci\-status\fR [\fB\-v\fR] [\fICOMMIT\fR]
    68  .
    69  .SH "DESCRIPTION"
    70  hub enhances various git commands to ease most common workflows with GitHub\.
    71  .
    72  .TP
    73  \fBhub \-\-noop\fR \fICOMMAND\fR
    74  Shows which command(s) would be run as a result of the current command\. Doesn\'t perform anything\.
    75  .
    76  .TP
    77  \fBhub alias\fR [\fB\-s\fR] [\fISHELL\fR]
    78  Shows shell instructions for wrapping git\. If given, \fISHELL\fR specifies the type of shell; otherwise defaults to the value of SHELL environment variable\. With \fB\-s\fR, outputs shell script suitable for \fBeval\fR\.
    79  .
    80  .TP
    81  \fBgit init\fR \fB\-g\fR \fIOPTIONS\fR
    82  Create a git repository as with git\-init(1) and add remote \fBorigin\fR at "git@github\.com:\fIUSER\fR/\fIREPOSITORY\fR\.git"; \fIUSER\fR is your GitHub username and \fIREPOSITORY\fR is the current working directory\'s basename\.
    83  .
    84  .TP
    85  \fBgit clone\fR [\fB\-p\fR] \fIOPTIONS\fR [\fIUSER\fR\fB/\fR]\fIREPOSITORY\fR \fIDIRECTORY\fR
    86  Clone repository "git://github\.com/\fIUSER\fR/\fIREPOSITORY\fR\.git" into \fIDIRECTORY\fR as with git\-clone(1)\. When \fIUSER\fR/ is omitted, assumes your GitHub login\.
    87  .
    88  .IP
    89  If the repository is private or the current user has push access to the repository, hub will use the ssh protocol for cloning\. Use \fB\-p\fR to select the ssh protocol unconditionally\. HTTPS protocol can be used instead by setting "hub\.protocol" (see \fICONFIGURATION\fR)\.
    90  .
    91  .TP
    92  \fBgit remote add\fR [\fB\-p\fR] \fIOPTIONS\fR \fIUSER\fR[\fB/\fR\fIREPOSITORY\fR]
    93  Add remote "git://github\.com/\fIUSER\fR/\fIREPOSITORY\fR\.git" as with git\-remote(1)\. When /\fIREPOSITORY\fR is omitted, the basename of the current working directory is used\. With \fB\-p\fR, use private remote "git@github\.com:\fIUSER\fR/\fIREPOSITORY\fR\.git"\. If \fIUSER\fR is "origin" then uses your GitHub login\.
    94  .
    95  .TP
    96  \fBgit remote set\-url\fR [\fB\-p\fR] \fIOPTIONS\fR \fIREMOTE\-NAME\fR \fIUSER\fR[/\fIREPOSITORY\fR]
    97  Sets the url of remote \fIREMOTE\-NAME\fR using the same rules as \fBgit remote add\fR\.
    98  .
    99  .TP
   100  \fBgit fetch\fR \fIUSER\-1\fR,[\fIUSER\-2\fR,\.\.\.]
   101  Adds missing remote(s) with \fBgit remote add\fR prior to fetching\. New remotes are only added if they correspond to valid forks on GitHub\.
   102  .
   103  .TP
   104  \fBgit checkout\fR \fIPULLREQ\-URL\fR [\fIBRANCH\fR]
   105  Checks out the head of the pull request as a local branch, to allow for reviewing, rebasing and otherwise cleaning up the commits in the pull request before merging\. The name of the local branch can explicitly be set with \fIBRANCH\fR\.
   106  .
   107  .TP
   108  \fBgit merge\fR \fIPULLREQ\-URL\fR
   109  Merge the pull request with a commit message that includes the pull request ID and title, similar to the GitHub Merge Button\.
   110  .
   111  .TP
   112  \fBgit cherry\-pick\fR \fIGITHUB\-REF\fR
   113  Cherry\-pick a commit from a fork using either full URL to the commit or GitHub\-flavored Markdown notation, which is \fBuser@sha\fR\. If the remote doesn\'t yet exist, it will be added\. A \fBgit fetch <user>\fR is issued prior to the cherry\-pick attempt\.
   114  .
   115  .TP
   116  \fBgit [am|apply]\fR \fIGITHUB\-URL\fR
   117  Downloads the patch file for the pull request or commit at the URL and applies that patch from disk with \fBgit am\fR or \fBgit apply\fR\. Similar to \fBcherry\-pick\fR, but doesn\'t add new remotes\. \fBgit am\fR creates commits while preserving authorship info while \fBapply\fR only applies the patch to the working copy\.
   118  .
   119  .TP
   120  \fBgit push\fR \fIREMOTE\-1\fR,\fIREMOTE\-2\fR,\.\.\.,\fIREMOTE\-N\fR [\fIREF\fR]
   121  Push \fIREF\fR to each of \fIREMOTE\-1\fR through \fIREMOTE\-N\fR by executing multiple \fBgit push\fR commands\.
   122  .
   123  .TP
   124  \fBgit submodule add\fR [\fB\-p\fR] \fIOPTIONS\fR [\fIUSER\fR/]\fIREPOSITORY\fR \fIDIRECTORY\fR
   125  Submodule repository "git://github\.com/\fIUSER\fR/\fIREPOSITORY\fR\.git" into \fIDIRECTORY\fR as with git\-submodule(1)\. When \fIUSER\fR/ is omitted, assumes your GitHub login\. With \fB\-p\fR, use private remote "git@github\.com:\fIUSER\fR/\fIREPOSITORY\fR\.git"\.
   126  .
   127  .TP
   128  \fBgit help\fR
   129  Display enhanced git\-help(1)\.
   130  .
   131  .P
   132  hub also adds some custom commands that are otherwise not present in git:
   133  .
   134  .TP
   135  \fBgit create\fR [\fINAME\fR] [\fB\-p\fR] [\fB\-d\fR \fIDESCRIPTION\fR] [\fB\-h\fR \fIHOMEPAGE\fR]
   136  Create a new public GitHub repository from the current git repository and add remote \fBorigin\fR at "git@github\.com:\fIUSER\fR/\fIREPOSITORY\fR\.git"; \fIUSER\fR is your GitHub username and \fIREPOSITORY\fR is the current working directory name\. To explicitly name the new repository, pass in \fINAME\fR, optionally in \fIORGANIZATION\fR/\fINAME\fR form to create under an organization you\'re a member of\. With \fB\-p\fR, create a private repository, and with \fB\-d\fR and \fB\-h\fR set the repository\'s description and homepage URL, respectively\.
   137  .
   138  .TP
   139  \fBgit browse\fR [\fB\-u\fR] [[\fIUSER\fR\fB/\fR]\fIREPOSITORY\fR] [SUBPAGE]
   140  Open repository\'s GitHub page in the system\'s default web browser using \fBopen(1)\fR or the \fBBROWSER\fR env variable\. If the repository isn\'t specified, \fBbrowse\fR opens the page of the repository found in the current directory\. If SUBPAGE is specified, the browser will open on the specified subpage: one of "wiki", "commits", "issues" or other (the default is "tree")\. With \fB\-u\fR, outputs the URL rather than opening the browser\.
   141  .
   142  .TP
   143  \fBgit compare\fR [\fB\-u\fR] [\fIUSER\fR] [[\fISTART\fR\.\.\.]\fIEND\fR]
   144  Open a GitHub compare view page in the system\'s default web browser\. \fISTART\fR to \fIEND\fR are branch names, tag names, or commit SHA1s specifying the range of history to compare\. If a range with two dots (\fBa\.\.b\fR) is given, it will be transformed into one with three dots\. If \fISTART\fR is omitted, GitHub will compare against the base branch (the default is "master")\. If \fIEND\fR is omitted, GitHub compare view is opened for the current branch\. With \fB\-u\fR, outputs the URL rather than opening the browser\.
   145  .
   146  .TP
   147  \fBgit fork\fR [\fB\-\-no\-remote\fR]
   148  Forks the original project (referenced by "origin" remote) on GitHub and adds a new remote for it under your username\.
   149  .
   150  .TP
   151  \fBgit pull\-request\fR [\fB\-o\fR|\fB\-\-browse\fR] [\fB\-f\fR] [\fB\-m\fR \fIMESSAGE\fR|\fB\-F\fR \fIFILE\fR|\fB\-i\fR \fIISSUE\fR|\fIISSUE\-URL\fR] [\fB\-b\fR \fIBASE\fR] [\fB\-h\fR \fIHEAD\fR]
   152  Opens a pull request on GitHub for the project that the "origin" remote points to\. The default head of the pull request is the current branch\. Both base and head of the pull request can be explicitly given in one of the following formats: "branch", "owner:branch", "owner/repo:branch"\. This command will abort operation if it detects that the current topic branch has local commits that are not yet pushed to its upstream branch on the remote\. To skip this check, use \fB\-f\fR\.
   153  .
   154  .IP
   155  Without \fIMESSAGE\fR or \fIFILE\fR, a text editor will open in which title and body of the pull request can be entered in the same manner as git commit message\. Pull request message can also be passed via stdin with \fB\-F \-\fR\.
   156  .
   157  .IP
   158  With \fB\-o\fR or \fB\-\-browse\fR, the new pull request will open in the web browser\.
   159  .
   160  .IP
   161  Issue to pull request conversion via \fB\-i <ISSUE>\fR or \fIISSUE\-URL\fR arguments is deprecated and will likely be removed from the future versions of both hub and GitHub API\.
   162  .
   163  .TP
   164  \fBgit ci\-status\fR [\fB\-v\fR] [\fICOMMIT\fR]
   165  Looks up the SHA for \fICOMMIT\fR in GitHub Status API and displays the latest status\. Exits with one of:
   166  .
   167  .br
   168  success (0), error (1), failure (1), pending (2), no status (3)
   169  .
   170  .IP
   171  If \fB\-v\fR is given, additionally print the URL to CI build results\.
   172  .
   173  .SH "CONFIGURATION"
   174  .
   175  .SS "GitHub OAuth authentication"
   176  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"\.
   177  .
   178  .P
   179  To avoid being prompted, use \fIGITHUB_USER\fR and \fIGITHUB_PASSWORD\fR environment variables\.
   180  .
   181  .SS "HTTPS instead of git protocol"
   182  If you prefer the HTTPS protocol for GitHub repositories, you can set "hub\.protocol" to "https"\. This will affect \fBclone\fR, \fBfork\fR, \fBremote add\fR and other operations that expand references to GitHub repositories as full URLs that otherwise use git and ssh protocols\.
   183  .
   184  .P
   185  "hub\.protocol" only applies when the "OWNER/REPO" shorthand is used instead of a full git URL\.
   186  .
   187  .IP "" 4
   188  .
   189  .nf
   190  
   191  # default behavior
   192  $ git clone defunkt/repl
   193  < git clone >
   194  
   195  # opt into HTTPS:
   196  $ git config \-\-global hub\.protocol https
   197  $ git clone defunkt/repl
   198  < https clone >
   199  .
   200  .fi
   201  .
   202  .IP "" 0
   203  .
   204  .SS "GitHub Enterprise"
   205  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:
   206  .
   207  .IP "" 4
   208  .
   209  .nf
   210  
   211  $ git config \-\-global \-\-add hub\.host my\.git\.org
   212  .
   213  .fi
   214  .
   215  .IP "" 0
   216  .
   217  .P
   218  The default host for commands like \fBinit\fR and \fBclone\fR is still github\.com, but this can be affected with the \fIGITHUB_HOST\fR environment variable:
   219  .
   220  .IP "" 4
   221  .
   222  .nf
   223  
   224  $ GITHUB_HOST=my\.git\.org git clone myproject
   225  .
   226  .fi
   227  .
   228  .IP "" 0
   229  .
   230  .SH "EXAMPLES"
   231  .
   232  .SS "git clone"
   233  .
   234  .nf
   235  
   236  $ git clone schacon/ticgit
   237  > git clone git://github\.com/schacon/ticgit\.git
   238  
   239  $ git clone \-p schacon/ticgit
   240  > git clone git@github\.com:schacon/ticgit\.git
   241  
   242  $ git clone resque
   243  > git clone git@github\.com/YOUR_USER/resque\.git
   244  .
   245  .fi
   246  .
   247  .SS "git remote add"
   248  .
   249  .nf
   250  
   251  $ git remote add rtomayko
   252  > git remote add rtomayko git://github\.com/rtomayko/CURRENT_REPO\.git
   253  
   254  $ git remote add \-p rtomayko
   255  > git remote add rtomayko git@github\.com:rtomayko/CURRENT_REPO\.git
   256  
   257  $ git remote add origin
   258  > git remote add origin git://github\.com/YOUR_USER/CURRENT_REPO\.git
   259  .
   260  .fi
   261  .
   262  .SS "git fetch"
   263  .
   264  .nf
   265  
   266  $ git fetch mislav
   267  > git remote add mislav git://github\.com/mislav/REPO\.git
   268  > git fetch mislav
   269  
   270  $ git fetch mislav,xoebus
   271  > git remote add mislav \.\.\.
   272  > git remote add xoebus \.\.\.
   273  > git fetch \-\-multiple mislav xoebus
   274  .
   275  .fi
   276  .
   277  .SS "git cherry\-pick"
   278  .
   279  .nf
   280  
   281  $ git cherry\-pick http://github\.com/mislav/REPO/commit/SHA
   282  > git remote add \-f mislav git://github\.com/mislav/REPO\.git
   283  > git cherry\-pick SHA
   284  
   285  $ git cherry\-pick mislav@SHA
   286  > git remote add \-f mislav git://github\.com/mislav/CURRENT_REPO\.git
   287  > git cherry\-pick SHA
   288  
   289  $ git cherry\-pick mislav@SHA
   290  > git fetch mislav
   291  > git cherry\-pick SHA
   292  .
   293  .fi
   294  .
   295  .SS "git am, git apply"
   296  .
   297  .nf
   298  
   299  $ git am https://github\.com/defunkt/hub/pull/55
   300  [ downloads patch via API ]
   301  > git am /tmp/55\.patch
   302  
   303  $ git am \-\-ignore\-whitespace https://github\.com/davidbalbert/hub/commit/fdb9921
   304  [ downloads patch via API ]
   305  > git am \-\-ignore\-whitespace /tmp/fdb9921\.patch
   306  
   307  $ git apply https://gist\.github\.com/8da7fb575debd88c54cf
   308  [ downloads patch via API ]
   309  > git apply /tmp/gist\-8da7fb575debd88c54cf\.txt
   310  .
   311  .fi
   312  .
   313  .SS "git fork"
   314  .
   315  .nf
   316  
   317  $ git fork
   318  [ repo forked on GitHub ]
   319  > git remote add \-f YOUR_USER git@github\.com:YOUR_USER/CURRENT_REPO\.git
   320  .
   321  .fi
   322  .
   323  .SS "git pull\-request"
   324  .
   325  .nf
   326  
   327  # while on a topic branch called "feature":
   328  $ git pull\-request
   329  [ opens text editor to edit title & body for the request ]
   330  [ opened pull request on GitHub for "YOUR_USER:feature" ]
   331  
   332  # explicit title, pull base & head:
   333  $ git pull\-request \-m "Implemented feature X" \-b defunkt:master \-h mislav:feature
   334  .
   335  .fi
   336  .
   337  .SS "git checkout"
   338  .
   339  .nf
   340  
   341  $ git checkout https://github\.com/defunkt/hub/pull/73
   342  > git remote add \-f \-t feature mislav git://github\.com/mislav/hub\.git
   343  > git checkout \-\-track \-B mislav\-feature mislav/feature
   344  
   345  $ git checkout https://github\.com/defunkt/hub/pull/73 custom\-branch\-name
   346  .
   347  .fi
   348  .
   349  .SS "git merge"
   350  .
   351  .nf
   352  
   353  $ git merge https://github\.com/defunkt/hub/pull/73
   354  > git fetch git://github\.com/mislav/hub\.git +refs/heads/feature:refs/remotes/mislav/feature
   355  > git merge mislav/feature \-\-no\-ff \-m \'Merge pull request #73 from mislav/feature\.\.\.\'
   356  .
   357  .fi
   358  .
   359  .SS "git create"
   360  .
   361  .nf
   362  
   363  $ git create
   364  [ repo created on GitHub ]
   365  > git remote add origin git@github\.com:YOUR_USER/CURRENT_REPO\.git
   366  
   367  # with description:
   368  $ git create \-d \'It shall be mine, all mine!\'
   369  
   370  $ git create recipes
   371  [ repo created on GitHub ]
   372  > git remote add origin git@github\.com:YOUR_USER/recipes\.git
   373  
   374  $ git create sinatra/recipes
   375  [ repo created in GitHub organization ]
   376  > git remote add origin git@github\.com:sinatra/recipes\.git
   377  .
   378  .fi
   379  .
   380  .SS "git init"
   381  .
   382  .nf
   383  
   384  $ git init \-g
   385  > git init
   386  > git remote add origin git@github\.com:YOUR_USER/REPO\.git
   387  .
   388  .fi
   389  .
   390  .SS "git push"
   391  .
   392  .nf
   393  
   394  $ git push origin,staging,qa bert_timeout
   395  > git push origin bert_timeout
   396  > git push staging bert_timeout
   397  > git push qa bert_timeout
   398  .
   399  .fi
   400  .
   401  .SS "git browse"
   402  .
   403  .nf
   404  
   405  $ git browse
   406  > open https://github\.com/YOUR_USER/CURRENT_REPO
   407  
   408  $ git browse \-\- commit/SHA
   409  > open https://github\.com/YOUR_USER/CURRENT_REPO/commit/SHA
   410  
   411  $ git browse \-\- issues
   412  > open https://github\.com/YOUR_USER/CURRENT_REPO/issues
   413  
   414  $ git browse \-\- issues/10
   415  > open https://github\.com/YOUR_USER/CURRENT_REPO/issues/10
   416  
   417  $ git browse schacon/ticgit
   418  > open https://github\.com/schacon/ticgit
   419  
   420  $ git browse schacon/ticgit commit/SHA
   421  > open https://github\.com/schacon/ticgit/commit/SHA
   422  
   423  $ git browse resque
   424  > open https://github\.com/YOUR_USER/resque
   425  
   426  $ git browse resque network
   427  > open https://github\.com/YOUR_USER/resque/network
   428  .
   429  .fi
   430  .
   431  .SS "git compare"
   432  .
   433  .nf
   434  
   435  $ git compare refactor
   436  > open https://github\.com/CURRENT_REPO/compare/refactor
   437  
   438  $ git compare 1\.0\.\.1\.1
   439  > open https://github\.com/CURRENT_REPO/compare/1\.0\.\.\.1\.1
   440  
   441  $ git compare \-u fix
   442  > (https://github\.com/CURRENT_REPO/compare/fix)
   443  
   444  $ git compare other\-user patch
   445  > open https://github\.com/other\-user/REPO/compare/patch
   446  .
   447  .fi
   448  .
   449  .SS "git submodule"
   450  .
   451  .nf
   452  
   453  $ git submodule add wycats/bundler vendor/bundler
   454  > git submodule add git://github\.com/wycats/bundler\.git vendor/bundler
   455  
   456  $ git submodule add \-p wycats/bundler vendor/bundler
   457  > git submodule add git@github\.com:wycats/bundler\.git vendor/bundler
   458  
   459  $ git submodule add \-b ryppl \-\-name pip ryppl/pip vendor/pip
   460  > git submodule add \-b ryppl \-\-name pip git://github\.com/ryppl/pip\.git vendor/pip
   461  .
   462  .fi
   463  .
   464  .SS "git ci\-status"
   465  .
   466  .nf
   467  
   468  $ git ci\-status [commit]
   469  > (prints CI state of commit and exits with appropriate code)
   470  > One of: success (0), error (1), failure (1), pending (2), no status (3)
   471  .
   472  .fi
   473  .
   474  .SS "git help"
   475  .
   476  .nf
   477  
   478  $ git help
   479  > (improved git help)
   480  $ git help hub
   481  > (hub man page)
   482  .
   483  .fi
   484  .
   485  .SH "BUGS"
   486  \fIhttps://github\.com/github/hub/issues\fR
   487  .
   488  .SH "AUTHORS"
   489  \fIhttps://github\.com/github/hub/contributors\fR
   490  .
   491  .SH "SEE ALSO"
   492  git(1), git\-clone(1), git\-remote(1), git\-init(1), \fIhttp://github\.com\fR, \fIhttps://github\.com/github/hub\fR