Expand the GitHub CLI quickstart (#42249)
Co-authored-by: Steve Guntrip <stevecat@github.com>
This commit is contained in:
hubwriter
@@ -22,6 +22,12 @@ redirect_from:
|
||||
|
||||
For more information about what you can do with {% data variables.product.prodname_cli %}, see the [{% data variables.product.prodname_cli %} manual](https://cli.github.com/manual).
|
||||
|
||||
### What's the difference between {% data variables.product.prodname_cli %} and Git on the command line?
|
||||
|
||||
The Git command line interface (`git`) allows you to work with a local or remote Git repository. The remote repository may be hosted on {% data variables.product.prodname_dotcom %} or it may be hosted by another service.
|
||||
|
||||
{% data variables.product.prodname_cli %} (`gh`) is specifically for working with {% data variables.product.prodname_dotcom %}. It allows you to use the command line to interact with {% data variables.product.prodname_dotcom %} in all sorts of ways, as illustrated by the previous list. If you tend to work on the command line you may prefer using {% data variables.product.prodname_cli %} instead of using {% data variables.product.prodname_dotcom %} in a browser. {% data variables.product.prodname_cli %} also makes it easier for you to create scripts to automate {% data variables.product.prodname_dotcom %} operations.
|
||||
|
||||
## Installing {% data variables.product.prodname_cli %}
|
||||
|
||||
{% data reusables.cli.cli-installation %}
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: GitHub CLI reference
|
||||
intro: 'You can view all of the {% data variables.product.prodname_cli %} commands in your terminal or in the {% data variables.product.prodname_cli %} manual.'
|
||||
intro: 'You can view all of the {% data variables.product.prodname_cli %} commands in your terminal. The same information is available in the {% data variables.product.prodname_cli %} manual.'
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghes: '*'
|
||||
@@ -11,26 +11,34 @@ topics:
|
||||
type: reference
|
||||
---
|
||||
|
||||
To view all top-level {% data variables.product.prodname_cli %} commands, see the [{% data variables.product.prodname_cli %} manual](https://cli.github.com/manual/gh) or call `gh` without arguments.
|
||||
To view all top-level {% data variables.product.prodname_cli %} commands, enter `gh` without arguments.
|
||||
|
||||
```shell
|
||||
gh
|
||||
```
|
||||
|
||||
To list all commands under a specific group, use the top-level command without arguments. For example, to list [commands for managing repositories](https://cli.github.com/manual/gh_repo):
|
||||
To list all of the subcommands that you can use with a {% data variables.product.prodname_cli %} command, use the top-level command without arguments.
|
||||
|
||||
```shell
|
||||
gh repo
|
||||
gh COMMAND
|
||||
```
|
||||
|
||||
To view the environment variables that can be used with {% data variables.product.prodname_cli %}, see the [{% data variables.product.prodname_cli %} manual](https://cli.github.com/manual/gh_help_environment) or use the `environment` command.
|
||||
For example, to view the environment variables that you can set to affect certain aspects of {% data variables.product.prodname_cli %}, use the `environment` command.
|
||||
|
||||
```shell
|
||||
gh environment
|
||||
```
|
||||
|
||||
To view the configuration settings that can be used with {% data variables.product.prodname_cli %}, see the [{% data variables.product.prodname_cli %} manual](https://cli.github.com/manual/gh_config) or use the `config` command.
|
||||
To view the configuration settings that you can set, use the `config` command.
|
||||
|
||||
```shell
|
||||
gh config
|
||||
```
|
||||
|
||||
To view help for a particular subcommand, use the `--help` flag.
|
||||
|
||||
```shell
|
||||
gh COMMAND [SUBCOMMAND ...] --help
|
||||
```
|
||||
|
||||
All of the information that's available by running these commands in the terminal is also included in the [{% data variables.product.prodname_cli %} online manual](https://cli.github.com/manual/gh).
|
||||
@@ -17,32 +17,98 @@ shortTitle: Quickstart
|
||||
|
||||
{% data reusables.cli.about-cli %}
|
||||
|
||||
## Getting started
|
||||
## Prerequisites
|
||||
|
||||
1. [Install](https://github.com/cli/cli#installation) {% data variables.product.prodname_cli %} on macOS, Windows, or Linux.
|
||||
1. In the command line, authenticate to {% data variables.product.company_short %}.{% ifversion not fpt or ghec %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}. For example, `octo-inc.ghe.com`.{% endif %}
|
||||
1. Install {% data variables.product.prodname_cli %} on macOS, Windows, or Linux. For more information, see [Installation](https://github.com/cli/cli#installation) in the {% data variables.product.prodname_cli %} repository.
|
||||
1. Authenticate with {% data variables.product.company_short %} by running this command from your terminal.{% ifversion ghes or ghae %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}. For example, `octo-inc.ghe.com`.{% endif %}
|
||||
|
||||
{% ifversion fpt or ghec %}
|
||||
{%- ifversion fpt or ghec %}
|
||||
|
||||
```shell
|
||||
gh auth login
|
||||
```
|
||||
|
||||
{% else %}
|
||||
{%- else %}
|
||||
|
||||
```shell
|
||||
gh auth login --hostname HOSTNAME
|
||||
```
|
||||
|
||||
{% endif %}
|
||||
1. Start working with {% data variables.product.company_short %} in the command line. For example, find an issue to work on with `gh issue status` or `gh issue list --assignee @me`. Create a pull request with `gh pr create`. Review a pull request with `gh pr checkout`, `gh pr diff` and `gh pr review`.
|
||||
{%- endif %}
|
||||
|
||||
## Next steps
|
||||
1. Follow the on-screen prompts.
|
||||
|
||||
- Tell {% data variables.product.prodname_cli %} which text editor to use for commands that open a text editor. For example, enter `gh config set editor "code -w"` to set your preferred text editor to {% data variables.product.prodname_vscode %}. For more information, see [`gh config set`](https://cli.github.com/manual/gh_config_set).
|
||||
{% data variables.product.prodname_cli %} automatically stores your Git credentials for you when you choose HTTPS as your preferred protocol for Git operations and answer "yes" to the prompt asking if you would like to authenticate to Git with your {% data variables.product.prodname_dotcom %} credentials. This can be useful as it allows you to use `git push`, `git pull`, and so on, without needing to set up a separate credential manager or use SSH.
|
||||
|
||||
## Some useful commands
|
||||
|
||||
{% note %}
|
||||
|
||||
**Note**: When you use some commands for the first time - for example, `gh codespace SUBCOMMAND` - you'll be prompted to add extra scopes to your authentication token. Follow the onscreen instructions.
|
||||
|
||||
{% endnote %}
|
||||
|
||||
### Viewing your status
|
||||
|
||||
Enter `gh status` to see details of your current work on {% data variables.product.prodname_dotcom %} across all the repositories you're subscribed to.
|
||||
|
||||
### Viewing a repository
|
||||
|
||||
Enter `gh repo view OWNER/REPO` to see the repository description and `README.md` for the repository. Enter `gh repo view OWNER/REPO --web` to view the repository in your default browser.
|
||||
|
||||
If you run the `repo` subcommand from within the directory of a local Git repository that has a remote on {% data variables.product.prodname_dotcom %} you can omit `OWNER/REPO`.
|
||||
|
||||
### Cloning a repository
|
||||
|
||||
Enter `gh clone OWNER/REPO`. For example, `gh clone octo-org/octo-repo` clones the `octo-org/octo-repo` repository to the directory from which you ran this command on your local computer.
|
||||
|
||||
### Creating a repository
|
||||
|
||||
Enter `gh repo create` and follow the on-screen instructions. You can create a new, empty repository on {% data variables.product.prodname_dotcom %} and then, optionally, clone it locally. Alternatively, you can push an existing local repository to {% data variables.product.prodname_dotcom %}, and optionally set it as the remote for your local repository. For information on setting a local directory as a Git repository, see "[AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github#initializing-a-git-repository)."
|
||||
|
||||
### Working with issues
|
||||
|
||||
Enter `gh issue list --repo OWNER/REPO` to list the most recently created issues that are currently open for the specified repository. If you run the `issue` subcommand from within the directory of a local Git repository that has a remote on {% data variables.product.prodname_dotcom %} you can omit `--repo OWNER/REPO`. For example, enter `gh issue list --assignee "@me"` to list issues assigned to you in this repository, or `gh issue list --author monalisa` to list issues created by the user "monalisa."
|
||||
|
||||
You can also create a new issue, see "[AUTOTITLE](/issues/tracking-your-work-with-issues/creating-an-issue#creating-an-issue-with-github-cli)," or search for an issue, see "[AUTOTITLE](/issues/tracking-your-work-with-issues/filtering-and-searching-issues-and-pull-requests?tool=cli#searching-for-issues-and-pull-requests)."
|
||||
|
||||
### Working with pull requests
|
||||
|
||||
Enter `gh pr list --repo OWNER/REPO` to list the most recently created pull requests that are currently open for the specified repository. If you run the `pr` subcommand from within the directory of a local Git repository that has a remote on {% data variables.product.prodname_dotcom %} you can omit `--repo OWNER/REPO`. For example, enter `gh pr list --author "@me"` to list open pull requests that you created in this repository.
|
||||
|
||||
Enter `gh pr list --label LABEL-NAME` to list open pull requests with a specific label. Enter `gh search prs --review-requested=@me --state=open` to list pull requests that you've been asked to review.
|
||||
|
||||
To create a pull request, enter `gh pr create` and follow the on-screen instructions. For more information, see "[AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request?tool=cli#creating-the-pull-request)."
|
||||
|
||||
### Working with codespaces
|
||||
|
||||
To create a new codespace, enter `gh codespace create` and follow the on-screen instructions.
|
||||
|
||||
To display your existing codespaces, enter `gh codespace list`. To open a codespace in the web version of {% data variables.product.prodname_vscode_shortname %} enter `gh codespace code -w` and choose a codespace .
|
||||
|
||||
In all of these commands you can substitute `cs` for `codespace`.
|
||||
|
||||
## Getting help
|
||||
|
||||
Enter `gh` for a reminder of the top-level {% data variables.product.prodname_cli %} commands that you can use. For example, `issue`, `pr`, `repo`, and so on.
|
||||
|
||||
For each command, and each subsidiary subcommand, you can append the `--help` flag to find out how it's used. For example, `gh issue --help` or `gh issue create --help`.
|
||||
|
||||
## Customizing {% data variables.product.prodname_cli %}
|
||||
|
||||
You can change configuration settings and add aliases or extensions, to make {% data variables.product.prodname_cli %} work the way that suits you best.
|
||||
|
||||
- Enter `gh config set SUBCOMMANDS` to configure {% data variables.product.prodname_cli %}'s settings, replacing `SUBCOMMANDS` with the setting you want to adjust.
|
||||
|
||||
For example, you can specify the text editor that's used when a {% data variables.product.prodname_cli %} command requires you to edit text - such as when you add the body text for a new issue you're creating. To set your preferred text editor to {% data variables.product.prodname_vscode %} enter `gh config set editor "code -w"`. The `-w` (or `--wait`) flag in this example causes the command to wait for the file to be closed in {% data variables.product.prodname_vscode %} before proceeding with the next step in your terminal.
|
||||
|
||||
For more information, see [`gh config set`](https://cli.github.com/manual/gh_config_set).
|
||||
|
||||
- Define aliases for commands that you commonly run. For example, if you run `gh alias set prd "pr create --draft"`, you will then be able to run `gh prd` to quickly open a draft pull request. For more information, see [`gh alias`](https://cli.github.com/manual/gh_alias).
|
||||
|
||||
- Create or add custom commands with {% data variables.product.prodname_cli %} extensions. For more information, see "[AUTOTITLE](/github-cli/github-cli/using-github-cli-extensions)" and "[AUTOTITLE](/github-cli/github-cli/creating-github-cli-extensions)."
|
||||
|
||||
- For more information about all of the commands that you can run with {% data variables.product.prodname_cli %}, see "[AUTOTITLE](/github-cli/github-cli/github-cli-reference)."
|
||||
## Further reading
|
||||
|
||||
- [AUTOTITLE](/github-cli/github-cli/github-cli-reference)
|
||||
- [{% data variables.product.prodname_cli %} online manual](https://cli.github.com/manual/gh)
|
||||
|
||||
Reference in New Issue
Block a user