# GitHub CLI 快速入门

开始使用 GitHub CLI 在命令行中使用 GitHub。

## 关于 GitHub CLI

GitHub CLI 是用于从计算机的命令行使用 GitHub 的开源工具。 从命令行操作时，您可以使用 GitHub CLI 来节省时间并避免切换上下文。

## Prerequisites

1. 在 macOS、Windows 或 Linux 上安装 GitHub CLI。 有关安装说明的详细信息，请参阅 GitHub CLI 存储库中的[安装](https://github.com/cli/cli?ref_product=cli\&ref_type=engagement\&ref_style=text#installation)。

2. 若要向 GitHub 进行身份验证，请从终端运行以下命令。

   ```shell
   gh auth login
   ```

3. 选择要进行身份验证的位置：

   * 如果通过 GitHub 访问 GitHub.com，请选择“GitHub.com”\*\*\*\*。
   * 如果通过其他域访问 GitHub，请选择“其他”，然后输入主机名（例如 \*\*\*\*）`octocorp.ghe.com`。

4. 按照屏幕上的其余提示操作。

   选择 HTTPS 作为 Git 操作的首选协议时，GitHub CLI 将自动存储 Git 凭据，并对询问是否要使用 GitHub 凭据向 Git 进行身份验证的提示回答“是”。 此操作非常有用，因为这允许直接使用 `git push`、`git pull` 等 Git 命令，无需设置单独的凭据管理器或使用 SSH。

## 一些有用的命令

> \[!NOTE]
> 首次使用某些命令（例如 `gh codespace SUBCOMMAND`）时，系统会提示你向身份验证令牌添加额外的范围。 按照屏幕说明进行操作。

### 查看状态

输入 `gh status`，可查看在 GitHub 上订阅的所有存储库中当前工作的详细信息。

### 查看存储库

输入 `gh repo view OWNER/REPO`，可查看存储库说明和存储库 `README.md`。 输入 `gh repo view OWNER/REPO --web`，可在默认浏览器中查看存储库。

如果从本地 Git 存储库（其在 GitHub 上有远程存储库）的目录中运行 `repo` 子命令，则可以省略 `OWNER/REPO`。

### 克隆仓库

输入 `gh repo clone OWNER/REPO`。 示例：`gh repo clone octo-org/octo-repo` 将 `octo-org/octo-repo` 存储库克隆到在本地计算机上运行此命令的目录。

### 创建仓库

输入 `gh repo create`，然后按照屏幕说明进行操作。 可以在 GitHub 上创建新的空存储库，然后可以选择在本地进行克隆。 另外，可以将现有本地存储库推送到 GitHub，并可以选择将其设置为本地存储库的远程存储库。 有关将本地目录设置为 Git 存储库的信息，请参阅 [将本地托管代码添加到 GitHub](/zh/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github#initializing-a-git-repository)。

### 处理问题

输入 `gh issue list --repo OWNER/REPO` 列出当前为指定存储库打开的最近创建的问题。 如果从本地 Git 存储库（其在 GitHub 上有远程存储库）的目录中运行 `issue` 子命令，则可以省略 `--repo OWNER/REPO`。 示例：输入 `gh issue list --assignee "@me"` 列出在此存储库中分配到的问题，或输入 `gh issue list --author monalisa` 列出用户“monalisa”创建的问题。

还可以创建新问题，请参阅 [创建议题](/zh/issues/tracking-your-work-with-issues/creating-an-issue#creating-an-issue-with-github-cli) 或搜索问题，请参阅 [筛选和搜索议题以及拉取请求](/zh/issues/tracking-your-work-with-issues/filtering-and-searching-issues-and-pull-requests?tool=cli#searching-for-issues-and-pull-requests)。

### 处理拉取请求

输入 `gh pr list --repo OWNER/REPO` 列出当前为指定存储库打开的最近创建的拉取请求。 如果从本地 Git 存储库（其在 GitHub 上有远程存储库）的目录中运行 `pr` 子命令，则可以省略 `--repo OWNER/REPO`。 示例：输入 `gh pr list --author "@me"` 列出在此存储库中创建的打开拉取请求。

输入 `gh pr list --label LABEL-NAME` 列出具有特定标签的打开拉取请求。 输入 `gh search prs --review-requested=@me --state=open` 列出被要求审阅的拉取请求。

若要创建拉取请求，输入 `gh pr create`，然后按照屏幕说明进行操作。 有关详细信息，请参阅“[创建拉取请求](/zh/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request?tool=cli#creating-the-pull-request)”。

### 处理 codespace

若要创建新的 codespace，输入 `gh codespace create`，然后按照屏幕说明进行操作。

若要显示现有 codespace，输入 `gh codespace list`。 若要在 VS Code 的 Web 版本中打开 codespace，输入 `gh codespace code -w` 并选择一个 codespace。

在这些命令中，可以用 `cs` 替代 `codespace`。

## 获取帮助

输入 `gh` 提醒用户可以使用的顶级 GitHub CLI 命令。 例如 `issue`、`pr`、`repo` 等。

对于每个命令和每个附属子命令，可以追加 `--help` 标志了解其用法。 例如 `gh issue --help` 或 `gh issue create --help`。

## GitHub CLI

可以更改配置设置并添加别名或扩展，让 GitHub CLI 以最合适的方式工作。

* 输入 `gh config set SUBCOMMANDS` 配置 GitHub CLI 的设置，将 `SUBCOMMANDS` 替换为要调整的设置。

  示例：可以指定 GitHub CLI 命令要求编辑文本时使用的文本编辑器，例如在为要创建的新问题添加正文文本时。 要将首选文本编辑器设置为 Visual Studio Code，输入 `gh config set editor "code -w"`。 本示例中的 `-w`（或 `--wait`）标志会导致命令等待文件在 Visual Studio Code 中关闭，再在终端中继续执行下一步。

  有关详细信息，请参阅 [`gh config set`](https://cli.github.com/manual/gh_config_set)。

* 为通常运行的命令定义别名。 例如，如果运行 `gh alias set prd "pr create --draft"`，则你可以运行 `gh prd` 以快速打开草稿拉取请求。 有关详细信息，请参阅 [`gh alias`](https://cli.github.com/manual/gh_alias)。

* 使用 GitHub CLI 扩展创建或添加自定义命令。 有关详细信息，请参阅 [使用 GitHub 命令行工具 (CLI) 扩展](/zh/github-cli/github-cli/using-github-cli-extensions) 和 [创建 GitHub CLI 扩展](/zh/github-cli/github-cli/creating-github-cli-extensions)。

## 对多个帐户使用 GitHub CLI

如果同一 GitHub 平台（例如 GitHub.com）上有多个帐户，则可以使用 `gh auth switch` 命令对每个帐户进行身份验证，并在各个帐户之间进行切换。 请参阅 GitHub CLI 手册中的 [gh auth switch](https://cli.github.com/manual/gh_auth_switch)。

如果需要在多个 GitHub CLI 平台（例如 GitHub 上的个人帐户和 GitHub.com 上的 托管用户帐户）上使用 GHE.com，请参阅 [跨 GitHub 平台使用 GitHub CLI](/zh/github-cli/github-cli/using-multiple-accounts)。

## 其他阅读材料

* [GitHub CLI 参考文档](/zh/github-cli/github-cli/github-cli-reference)
* [GitHub CLI 联机手册](https://cli.github.com/manual/gh)