Rebuilding the container in a codespace

About rebuilding a container

When you work in a codespace, your development environment is a Docker container that runs on a virtual machine. If you make changes to your dev container configuration from within a codespace, and you want to apply those changes to the current codespace, you need to rebuild the container.

By default, when you rebuild a container, GitHub Codespaces will speed up the build process by reusing cached images from previous builds of the container. This is usually the quickest way to implement changes to your dev container configuration, for the following reasons.

GitHub Codespaces can reuse images in your cache rather than repulling them from container registries.
The parts of your dev container configuration that define how the container is built, such as dev container features and Dockerfile instructions, may have already been implemented in image layers in your cache, so you won't need to wait for these processes to run again. (However, commands in your configuration that run after the container is built, such as onCreateCommand, will run again.)

Occasionally, you may want to perform a full rebuild of your container. With a full rebuild, GitHub Codespaces cleans all Docker containers, images, and volumes from the cache, then rebuilds your container with newly pulled images. All the setup defined in your configuration will run again, generating new image layers. You may want to perform a full rebuild after many iterations of rebuilding your container with cached images, in situations such as the following.

You want to ensure that the setup defined in your configuration is not dependent on cached images, and will run as required when someone creates a new codespace based on the configuration. For example, a dependency may have been removed from the base image since it was last pulled into your codespace.
You want to free up the disk space used by your cache, for example if you are low on disk space or want to minimize storage charges. Your image cache might be using a significant amount of disk space if you've changed your base image multiple times, if you've made a large number of iterative changes to your configuration, or if you're running multiple containers with Docker Compose.

Rebuilding a container

You can rebuild a container within a codespace in the VS Code web client or desktop application, or you can use GitHub CLI.

Rebuilding the dev container in the VS Code web client or desktop application

使用 Shift+Command+P (Mac) 或 Ctrl+Shift+P (Windows/Linux) 访问 VS Code Command Palette。
Start typing "Rebuild" and select Codespaces: Rebuild Container or Codespaces: Full Rebuild Container.
如果对 codespace 配置的更改导致容器错误，则 codespace 将在恢复模式下运行，并且你将看到错误消息。
- 若要通过查看创建日志来诊断错误，请单击“查看创建日志”。
- 若要修复日志中标识的错误，请更新 devcontainer.json 文件。
- 要应用更改，请重建容器。

使用 GitHub CLI 重新生成开发容器

如果更改了 VS Code 外部的开发容器配置（例如在 GitHub.com 上或在 JetBrains IDE 中），则可以使用 GitHub CLI 为现有 codespace 重新生成开发容器。

在终端中输入以下命令。
```
gh codespace rebuild
```
将列出 codespace。
使用键盘上的箭头键突出显示所需的 codespace，然后按 Enter。

To perform a full rebuild with GitHub CLI, you can use the gh codespace rebuild --full command.

Persisting data over a rebuild

创建 codespace 时，存储库将克隆到 codespace 的 /workspaces 目录中。这是装载到容器中的永久性目录。停止和启动 codespace 以及在 codespace 中重新生成容器时，将保留在此目录中所做的任何更改（包括编辑、添加或删除文件）。

在 /workspaces 目录外，codespace 包含 Linux 目录结构，该结构因用于生成 codespace 的映像而异。可以添加文件或对 /workspaces 目录外的文件进行更改：例如，可以安装新程序，也可以在文件（如 ~/.bashrc）中设置 shell 配置。作为非根用户，你可能不会自动拥有对某些目录的写入访问权限，但大多数映像允许使用 sudo 命令对这些目录进行根访问。

在 /workspaces 外，除 /tmp 目录，codespace 中的目录都与容器的生命周期相关联。这意味着在停止和启动 codespace 时，所做的任何更改都将保留，但在重新生成容器时则不会保留。

If you want to preserve files outside the /workspaces directory over a rebuild, you can create, at the desired location in the container, a symbolic link (symlink) to the persistent directory. For example, in your /workspaces/.devcontainer directory, you can create a config directory that will be preserved across a rebuild. You can then symlink the config directory and its contents as a postCreateCommand in your devcontainer.json file.

{
    "image": "mcr.microsoft.com/vscode/devcontainers/base:alpine",
    "postCreateCommand": ".devcontainer/postCreate.sh"
}

In the example postCreate.sh file below, the contents of the config directory are symbolically linked to the home directory.

#!/bin/bash
ln -sf $PWD/.devcontainer/config $HOME/config && set +x