# 将 GitHub Codespaces 与 GitHub CLI 配合使用

你可以通过 gh GitHub Codespaces 命令行界面直接从命令行操作 GitHub。

## 关于 GitHub CLI

GitHub CLI 是用于从计算机的命令行使用 GitHub 的开源工具。 从命令行操作时，您可以使用 GitHub CLI 来节省时间并避免切换上下文。 有关详细信息，请参阅“[关于 GitHub CLI](/zh/github-cli/github-cli/about-github-cli)”。

你可以在 GitHub Codespaces 中操作 GitHub CLI 来：

* [列出所有代码空间](#list-all-of-your-codespaces)
* [创建新的代码空间](#create-a-new-codespace)
* [查看 codespace 的详细信息](#view-details-of-a-codespace)
* [停止代码空间](#stop-a-codespace)
* [删除 codespace](#delete-a-codespace)
* [重命名代码空间](#rename-a-codespace)
* [重新生成 codespace](#rebuild-a-codespace)
* [通过 SSH 连接到 Codespace](#ssh-into-a-codespace)
* [在 Visual Studio Code
  中打开代码空间](#open-a-codespace-in-visual-studio-code)
* [在 JupyterLab 中打开代码空间](#open-a-codespace-in-jupyterlab)
* [将文件复制到代码空间/从代码空间复制文件](#copy-a-file-tofrom-a-codespace)
* [修改 codespace 中的端口](#modify-ports-in-a-codespace)
* [访问 codespace 日志](#access-codespace-logs)
* [访问远程资源](#access-remote-resources)
* [更改 codespace 的计算机类型](#change-the-machine-type-of-a-codespace)

## 安装 GitHub CLI

有关 GitHub CLI 的安装说明，请参阅 [GitHub CLI 存储库](https://github.com/cli/cli#installation)。

## 使用 GitHub CLI

如果尚未执行此操作，请运行 `gh auth login` 对 GitHub 帐户进行身份验证。

若要使用 `gh` 处理 GitHub Codespaces，请键入 `gh codespace SUBCOMMAND` 或其别名 `gh cs SUBCOMMAND`。

作为可用于处理 GitHub Codespaces 的一系列命令的示例，您可以：

* 列出您当前的代码空间，以检查您是否为特定的存储库创建了代码空间：<br>
  `gh codespace list`
* 为需要的代码库分支创建一个新的代码空间。<br>
  `gh codespace create -r github/docs -b main`
* 通过 SSH 连接到新的 codespace：<br>
  `gh codespace ssh -c octocat-literate-space-parakeet-7gwrqp9q9jcx4vq`
* 将端口转发到本地计算机：<br>
  `gh codespace ports forward 8000:8000 -c octocat-literate-space-parakeet-7gwrqp9q9jcx4vq`

## GitHub Codespaces 的 `gh` 命令

以下各节给出了每个可用操作的示例命令。

有关 GitHub Codespaces 的 `gh` 命令的完整参考，包括每个命令的所有可用选项的详细信息，请参阅 GitHub CLI 联机帮助以了解“[gh codespace](https://cli.github.com/manual/gh_codespace)”。 或者，在命令行上，使用 `gh codespace --help` 获取常规帮助，或者使用 `gh codespace SUBCOMMAND --help` 获取特定子命令的帮助。

> \[!NOTE]
> 与许多命令一起使用的 `-c CODESPACE_NAME` 标志是可选的。 如果省略它，则会显示一个代码空间列表供您选择。

### 列出所有代码空间

```shell
gh codespace list
```

该列表包含每个 codespace 的唯一名称，可在其他 `gh codespace` 命令中使用。

codespace 分支名称末尾的星号表示该 codespace 中存在未提交或未推送的更改。

### 创建新的代码空间

```shell
gh codespace create -r OWNER/REPO_NAME [-b BRANCH]
```

有关详细信息，请参阅“[为代码库创建代码空间](/zh/codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository)”。

### 查看 codespace 的详细信息

```shell
gh codespace view
```

运行此命令后，系统要求您选择一个现有的 codespace。 然后显示以下信息：

* 代码空间的名称
* 状态（例如“可用”或“关闭”）
* 存储库
* Git 状态
* 用于创建 codespace 的开发容器配置文件的路径
* 计算机类型
* 空闲超时
* codespace 的创建日期和时间
* 保留期

有关详细信息，请参阅 [GitHub CLI 引用](https://cli.github.com/manual/gh_codespace_view)。

### 停止代码空间

```shell
gh codespace stop -c CODESPACE-NAME
```

有关详细信息，请参阅“[深入了解 GitHub Codespaces](/zh/codespaces/about-codespaces/deep-dive#closing-or-stopping-your-codespace)”。

### 删除代码空间

```shell
gh codespace delete -c CODESPACE-NAME
```

有关详细信息，请参阅“[删除代码空间](/zh/codespaces/developing-in-a-codespace/deleting-a-codespace)”。

### 重命名“codespace”

```shell
gh codespace edit -c CODESPACE-NAME -d 'DISPLAY-NAME'
```

有关详细信息，请参阅“[重命名代码空间](/zh/codespaces/customizing-your-codespace/renaming-a-codespace?tool=cli)”。

### 重新生成代码空间

```shell
gh codespace rebuild
```

若要执行完全重新生成，请在此命令的末尾添加 `--full`。 有关详细信息，请参阅“[在 codespace 中重新生成容器](/zh/codespaces/developing-in-a-codespace/rebuilding-the-container-in-a-codespace)”。

使用此命令重新生成 codespace 时，它将使用当前保存在 codespace 系统中的 `devcontainer.json` 文件。 无论文件的当前状态是否已保存在源代码管理中，都会发生这种情况。 有关详细信息，请参阅“[开发容器简介](/zh/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers)”。

### 通过 SSH 连接到 Codespace（代码空间）

要在远程代码空间计算机上运行命令，请从终端通过 SSH 进入代码空间。

```shell
gh codespace ssh -c CODESPACE-NAME
```

> \[!NOTE]
> 连接到的 codespace 必须运行 SSH 服务器。 默认开发容器映像包含一个可自动启动的 SSH 服务器。 如果未通过默认映像创建 codespace，可以通过将以下内容添加到 `devcontainer.json` 文件中的 `features` 对象来安装和启动 SSH 服务器。
>
> ```jsonc
> "features": {
> // ...
> "ghcr.io/devcontainers/features/sshd:1": {
> "version": "latest"
> },
> // ...
> }
> ```
>
> 有关 `devcontainer.json` 文件和默认容器映像的详细信息，请参阅 [开发容器简介](/zh/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers)。

GitHub Codespaces 会自动创建本地 SSH 密钥，以提供无缝身份验证体验。 若要详细了解如何使用 SSH 进行连接，请参阅 [`gh codespace ssh`](https://cli.github.com/manual/gh_codespace_ssh)。

### 在 Visual Studio Code

中打开代码空间

```shell
gh codespace code -c CODESPACE-NAME
```

必须在本地计算机上安装 VS Code。 有关详细信息，请参阅“[在 Visual Studio Code 中使用 GitHub Codespaces](/zh/codespaces/developing-in-a-codespace/using-github-codespaces-in-visual-studio-code)”。

### 在 JupyterLab 中打开 codespace

```shell
gh codespace jupyter -c CODESPACE-NAME
```

JupyterLab 应用程序必须安装在要打开的 Codespace 中。 默认开发容器映像包括 JupyterLab，因此从默认映像创建的 codespaces 将始终安装 JupyterLab。 有关默认映像的详细信息，请参阅“[开发容器简介](/zh/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#using-the-default-dev-container-configuration)”以及 [`devcontainers/images`](https://github.com/devcontainers/images/tree/main/src/universal) 仓库。 如果未在开发容器配置中使用默认映像，则可以通过将 `ghcr.io/devcontainers/features/python` 功能添加到 `devcontainer.json` 文件来安装 JupyterLab。 应该包括选项 `"installJupyterlab": true`。 有关详细信息，请参阅 `devcontainers/features` 存储库中 [`python`](https://github.com/devcontainers/features/tree/main/src/python#python-python) 功能的 README 文件。

### 将文件复制到代码空间/从代码空间复制文件

```shell
gh codespace cp [-r] SOURCE(S) DESTINATION
```

使用文件或目录名称上的前缀 `remote:` 来指示它位于 codespace 上。 与 UNIX `cp` 命令一样，第一个参数指定源，最后一个参数指定目标。 如果目标是目录，则可以指定多个来源。 如果任何源是目录，请使用 `-r`（递归）标志。

代码空间上文件和目录的位置相对于远程用户的主目录。

#### 示例

* 将文件从本地计算机复制到 codespace 的 `$HOME` 目录：

  `gh codespace cp myfile.txt remote:`

* 将文件复制到代码空间中检出存储库的目录：

  `gh codespace cp myfile.txt remote:/workspaces/REPOSITORY-NAME`

* 将文件从代码空间复制到本地计算机上的当前目录：

  `gh codespace cp remote:myfile.txt .`

* 将三个本地文件复制到 codespace 的 `$HOME/temp` 目录：

  `gh codespace cp a1.txt a2.txt a3.txt remote:temp`

* 将三个文件从代码空间复制到本地计算机上的当前工作目录：

  `gh codespace cp remote:a1.txt remote:a2.txt remote:a3.txt .`

* 将本地目录复制到 codespace 的 `$HOME` 目录：

  `gh codespace cp -r mydir remote:`

* 将目录从代码空间复制到本地计算机，更改目录名称：

  `gh codespace cp -r remote:mydir mydir-localcopy`

有关 `gh codespace cp` 命令的详细信息，包括可以使用的其他标志，请参阅 [GitHub CLI 手册](https://cli.github.com/manual/gh_codespace_cp)。

### 修改 codespace 中的端口

您可以将代码空间上的端口转发到本地端口。 只要进程正在运行，端口就会保持转发状态。 若要停止转发端口，请按 <kbd>Control</kbd>+<kbd>C</kbd>。

```shell
gh codespace ports forward CODESPACE-PORT_NAME:LOCAL-PORT-NAME -c CODESPACE-NAME
```

若要查看转发端口的详细信息，请输入 `gh codespace ports` 并选择 codespace。

您可以设置转发端口的可见性。 有三种可见性设置：

* `private` - 仅对你可见。 这是转发端口时的默认设置。
* `org` - 对拥有存储库的组织成员可见。
* `public` - 对知道 URL 和端口号的任何人可见。

```shell
gh codespace ports visibility CODESPACE-PORT:private|org|public -c CODESPACE-NAME
```

您可以使用一个命令设置多个端口的可见性。 例如：

```shell
gh codespace ports visibility 80:private 3000:public 3306:org -c CODESPACE-NAME
```

有关详细信息，请参阅“[代码空间中的转发端口](/zh/codespaces/developing-in-a-codespace/forwarding-ports-in-your-codespace)”。

### 访问 codespace 日志

您可以查看代码空间的创建日志。 输入此命令后，系统将要求您输入 SSH 密钥的密码。

```shell
gh codespace logs -c CODESPACE-NAME
```

有关创建日志的详细信息，请参阅 [GitHub Codespaces 日志](/zh/codespaces/troubleshooting/github-codespaces-logs#creation-logs)。

### 访问远程资源

可以使用 GitHub CLI 扩展在 codespace 和本地计算机之间创建网桥，以便 codespace 可以访问可从计算机访问的任何远程资源。 有关使用扩展的详细信息，请参阅[使用 GitHub CLI 访问远程资源](https://github.com/github/gh-net#codespaces-network-bridge)。

> \[!NOTE]
> GitHub CLI 扩展当前处于 公共预览版 阶段，可能会有所变更。

### 更改 codespace 的计算机类型

```shell
gh codespace edit -m MACHINE-TYPE-NAME
```

有关详细信息，请参阅 [更改代码空间的计算机类型](/zh/codespaces/customizing-your-codespace/changing-the-machine-type-for-your-codespace) 的“GitHub CLI”选项卡。