github.com/jingweno/gh@v2.1.1-0.20221007190738-04a7985fa9a1+incompatible/man/gh.1.ronn (about)

     1  gh(1) -- gh + h = github
     2  ============================
     3  
     4  ## SYNOPSIS
     5  
     6  `gh` [`--noop`] <COMMAND> <OPTIONS>  
     7  `gh alias` [`-s`] [<SHELL>]
     8  
     9  ### Expanded git commands:
    10  
    11  `git init -g` <OPTIONS>  
    12  `git clone` [`-p`] <OPTIONS> [<USER>/]<REPOSITORY> <DIRECTORY>  
    13  `git remote add` [`-p`] <OPTIONS> <USER>[/<REPOSITORY>]  
    14  `git remote set-url` [`-p`] <OPTIONS> <REMOTE-NAME> <USER>[/<REPOSITORY>]  
    15  `git fetch` <USER-1>,[<USER-2>,...]  
    16  `git checkout` <PULLREQ-URL> [<BRANCH>]  
    17  `git merge` <PULLREQ-URL>  
    18  `git cherry-pick` <GITHUB-REF>  
    19  `git am` <GITHUB-URL>  
    20  `git apply` <GITHUB-URL>  
    21  `git push` <REMOTE-1>,<REMOTE-2>,...,<REMOTE-N> [<REF>]  
    22  `git submodule add` [`-p`] <OPTIONS> [<USER>/]<REPOSITORY> <DIRECTORY>  
    23  
    24  ### Custom git commands:
    25  
    26  `git create` [<NAME>] [`-p`] [`-d` <DESCRIPTION>] [`-h` <HOMEPAGE>]  
    27  `git browse` [`-u`] [[<USER>`/`]<REPOSITORY>] [SUBPAGE]  
    28  `git compare` [`-u`] [<USER>] [[<START>...]<END>]  
    29  `git fork` [`--no-remote`]  
    30  `git pull-request` [`-f`] [`-m` <MESSAGE>|`-F` <FILE>|`-i` <ISSUE>|<ISSUE-URL>] [`-b` <BASE>] [`-h` <HEAD>]  
    31  `git release create` [`-d`] [`-p`] [`-a` <ASSETS-DIR>] [`-m` <MESSAGE>|`-f` <FILE>] <TAG>
    32  `git issue create` [`-m` <MESSAGE>|`-f` <FILE>] [`-l` <LABEL-1>,<LABEL-2>,...,<LABEL-N>]
    33  `git ci-status` [`-v`] [<COMMIT>]
    34  
    35  ## DESCRIPTION
    36  
    37  gh enhances various git commands to ease most common workflows with GitHub.
    38  
    39    * `gh --noop` <COMMAND>:
    40      Shows which command(s) would be run as a result of the current command.
    41      Doesn't perform anything.
    42  
    43    * `gh alias` [`-s`] [<SHELL>]:
    44      Shows shell instructions for wrapping git. If given, <SHELL> specifies the
    45      type of shell; otherwise defaults to the value of SHELL environment
    46      variable.  With `-s`, outputs shell script suitable for `eval`.
    47  
    48    * `git init` `-g` <OPTIONS>:
    49      Create a git repository as with git-init(1) and add remote `origin` at
    50      "git@github.com:<USER>/<REPOSITORY>.git"; <USER> is your GitHub username and
    51      <REPOSITORY> is the current working directory's basename.
    52  
    53    * `git clone` [`-p`] <OPTIONS> [<USER>`/`]<REPOSITORY> <DIRECTORY>:
    54      Clone repository "git://github.com/<USER>/<REPOSITORY>.git" into
    55      <DIRECTORY> as with git-clone(1). When <USER>/ is omitted, assumes
    56      your GitHub login.
    57  
    58      If the repository is private or the current user has push access to the
    59      repository, gh will use the ssh protocol for cloning. Use `-p` to select
    60      the ssh protocol unconditionally. HTTPS protocol can be used instead by
    61      setting "gh.protocol" (see <CONFIGURATION>).
    62  
    63    * `git remote add` [`-p`] <OPTIONS> <USER>[`/`<REPOSITORY>]:
    64      Add remote "git://github.com/<USER>/<REPOSITORY>.git" as with
    65      git-remote(1). When /<REPOSITORY> is omitted, the basename of the
    66      current working directory is used. With `-p`, use private remote
    67      "git@github.com:<USER>/<REPOSITORY>.git". If <USER> is "origin"
    68      then uses your GitHub login.
    69  
    70    * `git remote set-url` [`-p`] <OPTIONS> <REMOTE-NAME> <USER>[/<REPOSITORY>]:
    71      Sets the url of remote <REMOTE-NAME> using the same rules as 
    72      `git remote add`.
    73  
    74    * `git fetch` <USER-1>,[<USER-2>,...]:
    75      Adds missing remote(s) with `git remote add` prior to fetching. New
    76      remotes are only added if they correspond to valid forks on GitHub.
    77  
    78    * `git checkout` <PULLREQ-URL> [<BRANCH>]:
    79      Checks out the head of the pull request as a local branch, to allow for
    80      reviewing, rebasing and otherwise cleaning up the commits in the pull
    81      request before merging. The name of the local branch can explicitly be
    82      set with <BRANCH>.
    83  
    84    * `git merge` <PULLREQ-URL>:
    85      Merge the pull request with a commit message that includes the pull request
    86      ID and title, similar to the GitHub Merge Button.
    87  
    88    * `git cherry-pick` <GITHUB-REF>:
    89      Cherry-pick a commit from a fork using either full URL to the commit
    90      or GitHub-flavored Markdown notation, which is `user@sha`. If the remote
    91      doesn't yet exist, it will be added. A `git fetch <user>` is issued
    92      prior to the cherry-pick attempt.
    93  
    94    * `git [am|apply]` <GITHUB-URL>:
    95      Downloads the patch file for the pull request or commit at the URL and
    96      applies that patch from disk with `git am` or `git apply`. Similar to
    97      `cherry-pick`, but doesn't add new remotes. `git am` creates commits while
    98      preserving authorship info while `apply` only applies the patch to the
    99      working copy.
   100  
   101    * `git push` <REMOTE-1>,<REMOTE-2>,...,<REMOTE-N> [<REF>]:
   102      Push <REF> to each of <REMOTE-1> through <REMOTE-N> by executing
   103      multiple `git push` commands.
   104  
   105    * `git submodule add` [`-p`] <OPTIONS> [<USER>/]<REPOSITORY> <DIRECTORY>:
   106      Submodule repository "git://github.com/<USER>/<REPOSITORY>.git" into
   107      <DIRECTORY> as with git-submodule(1). When <USER>/ is omitted, assumes
   108      your GitHub login. With `-p`, use private remote
   109      "git@github.com:<USER>/<REPOSITORY>.git".
   110  
   111    * `git help`:
   112      Display enhanced git-help(1).
   113  
   114  gh also adds some custom commands that are otherwise not present in git:
   115  
   116    * `git create` [<NAME>] [`-p`] [`-d` <DESCRIPTION>] [`-h` <HOMEPAGE>]:
   117      Create a new public GitHub repository from the current git
   118      repository and add remote `origin` at
   119      "git@github.com:<USER>/<REPOSITORY>.git"; <USER> is your GitHub
   120      username and <REPOSITORY> is the current working directory name.
   121      To explicitly name the new repository, pass in <NAME>, optionally in
   122      <ORGANIZATION>/<NAME> form to create under an organization you're a
   123      member of. With `-p`, create a private repository, and with `-d` and `-h`
   124      set the repository's description and homepage URL, respectively.
   125  
   126    * `git browse` [`-u`] [[<USER>`/`]<REPOSITORY>] [SUBPAGE]:
   127      Open repository's GitHub page in the system's default web browser using
   128      `open(1)` or the `BROWSER` env variable. If the repository isn't
   129      specified, `browse` opens the page of the repository found in the current
   130      directory. If SUBPAGE is specified, the browser will open on the specified
   131      subpage: one of "wiki", "commits", "issues" or other (the default is
   132      "tree"). With `-u`, outputs the URL rather than opening the browser.
   133  
   134    * `git compare` [`-u`] [<USER>] [[<START>...]<END>]:
   135      Open a GitHub compare view page in the system's default web browser.
   136      <START> to <END> are branch names, tag names, or commit SHA1s specifying
   137      the range of history to compare. If a range with two dots (`a..b`) is given,
   138      it will be transformed into one with three dots. If <START> is omitted,
   139      GitHub will compare against the base branch (the default is "master").
   140      If <END> is omitted, GitHub compare view is opened for the current branch.
   141      With `-u`, outputs the URL rather than opening the browser.
   142  
   143    * `git fork` [`--no-remote`]:
   144      Forks the original project (referenced by "origin" remote) on GitHub and
   145      adds a new remote for it under your username.
   146  
   147    * `git pull-request` [`-f`] [`-m` <MESSAGE>|`-F` <FILE>|`-i` <ISSUE>|<ISSUE-URL>] [`-b` <BASE>] [`-h` <HEAD>]:
   148      Opens a pull request on GitHub for the project that the "origin" remote
   149      points to. The default head of the pull request is the current branch.
   150      Both base and head of the pull request can be explicitly given in one of
   151      the following formats: "branch", "owner:branch", "owner/repo:branch".
   152      This command will abort operation if it detects that the current topic
   153      branch has local commits that are not yet pushed to its upstream branch
   154      on the remote. To skip this check, use `-f`.
   155  
   156      Without <MESSAGE> or <FILE>, a text editor will open in which title and body
   157      of the pull request can be entered in the same manner as git commit message.
   158      Pull request message can also be passed via stdin with `-F -`.
   159  
   160      Issue to pull request conversion via `-i <ISSUE>` or <ISSUE-URL>
   161      arguments is deprecated and will likely be removed from the future versions
   162      of both hub and GitHub API.
   163  
   164    * `git release`:
   165      Retrieves releases from GitHub for the project that the "origin" remote
   166      points to.
   167  
   168    * `git release create` [`-d`] [`-p`] [`-a` <ASSETS-DIR>] [`-m` <MESSAGE>|`-f` <FILE>] <TAG>:
   169      Creates a new release in GitHub for the project that the "origin" remote
   170      points to. It requires the name of the tag to release as a first argument.
   171  
   172      Specify the assets to include in the release from a directory via `-a`. Without
   173      `-a`, it finds assets from "releases/TAG" of the current directory.
   174  
   175      Without <MESSAGE> or <FILE>, a text editor will open in which title and body
   176      of the release can be entered in the same manner as git commit message.
   177  
   178      If `-d` is given, it creates a draft release.
   179  
   180      If `-p` is given, it creates a pre-release.
   181  
   182    * `git issue`:
   183      List summary of the open issues for the project that the "origin" remote
   184      points to.
   185  
   186    * `git issue create` [`-m` <MESSAGE>|`-f` <FILE>] [`-l` <LABEL-1>,<LABEL-2>,...,<LABEL-N>]:
   187      Creates an issue for the project that the "origin" remote points to.
   188  
   189      Without <MESSAGE> or <FILE>, a text editor will open in which title and body
   190      of the release can be entered in the same manner as git commit message.
   191  
   192      Specify one or more labels via `-a`.
   193  
   194    * `git ci-status` [`-v`] [<COMMIT>]:
   195      Looks up the SHA for <COMMIT> in GitHub Status API and displays the latest
   196      status. Exits with one of:  
   197      success (0), error (1), failure (1), pending (2), no status (3)
   198  
   199      If `-v` is given, additionally print the URL to CI build results.
   200  
   201  
   202  ## CONFIGURATION
   203  
   204  gh will prompt for GitHub username & password the first time it needs to access
   205  the API and exchange it for an OAuth token, which it saves in "~/.config/gh".
   206  
   207  To avoid being prompted, use <GITHUB_USER> and <GITHUB_PASSWORD> environment
   208  variables.
   209  
   210  If you prefer the HTTPS protocol for GitHub repositories, you can set
   211  "gh.protocol" to "https". This will affect `clone`, `fork`, `remote add`
   212  and other operations that expand references to GitHub repositories as full
   213  URLs that otherwise use git and ssh protocols.
   214  
   215      $ git config --global gh.protocol https
   216  
   217  ### GitHub Enterprise
   218  
   219  By default, gh will only work with repositories that have remotes which
   220  point to github.com. GitHub Enterprise hosts need to be whitelisted to
   221  configure hub to treat such remotes same as github.com:
   222  
   223      $ git config --global --add gh.host my.git.org
   224  
   225  The default host for commands like `init` and `clone` is still
   226  github.com, but this can be affected with the <GITHUB_HOST> environment
   227  variable:
   228  
   229      $ GITHUB_HOST=my.git.org git clone myproject
   230  
   231  ## EXAMPLES
   232  
   233  {{README}}
   234  
   235  ## BUGS
   236  
   237  <https://github.com/github/gh/issues>
   238  
   239  ## AUTHORS
   240  
   241  <https://github.com/github/gh/contributors>
   242  
   243  ## SEE ALSO
   244  
   245  git(1), git-clone(1), git-remote(1), git-init(1),
   246  <http://github.com>,
   247  <https://github.com/github/hub>