[Improvement] Codespaces: Document that any changes outside /workspaces are cleared on rebuild (github#35698)

isaacmbrown · jules-p · jkeech · web-flow · commit 26f8384356bc · 2023-03-24T10:10:33.000Z
Co-authored-by: Jules &lt;19994093+jules-p@users.noreply.github.com&gt;
Co-authored-by: John Keech &lt;jokeech@microsoft.com&gt;
diff --git a/content/codespaces/codespaces-reference/index.md b/content/codespaces/codespaces-reference/index.md
@@ -10,7 +10,6 @@ children:
   - /using-the-github-codespaces-plugin-for-jetbrains
   - /using-the-vs-code-command-palette-in-codespaces
   - /security-in-github-codespaces
-  - /performing-a-full-rebuild-of-a-container
   - /disaster-recovery-for-github-codespaces
 ---
 
diff --git a/content/codespaces/developing-in-codespaces/index.md b/content/codespaces/developing-in-codespaces/index.md
@@ -17,6 +17,7 @@ children:
   - /using-github-codespaces-for-pull-requests
   - /stopping-and-starting-a-codespace
   - /forwarding-ports-in-your-codespace
+  - /rebuilding-the-container-in-a-codespace
   - /default-environment-variables-for-your-codespace
   - /persisting-environment-variables-and-temporary-files
   - /connecting-to-a-private-network
diff --git a/content/codespaces/developing-in-codespaces/persisting-environment-variables-and-temporary-files.md b/content/codespaces/developing-in-codespaces/persisting-environment-variables-and-temporary-files.md
@@ -22,7 +22,7 @@ For all the methods of setting custom variables listed below, you can access the
 
 You can set the value of the environment variable in the `~/.bashrc` file, or in an equivalent configuration file if you are not using the Bash shell. For example, add the statement `VARNAME=value`.
 
-After you save the change to this file, the value will be set the next time you open the codespace, or you can set it immediately by using a command such as `source ~/.bashrc`. The variable will remain set if you stop and start the codespace. However, changes to files in the home directory will be reset if you rebuild the container, so variables set in the `~/.bashrc` file will not persist over a rebuild.
+After you save the change to this file, the value will be set the next time you open the codespace, or you can set it immediately by using a command such as `source ~/.bashrc`. The variable will remain set if you stop and start the codespace. However, changes to files in the home directory will be reset if you rebuild the container, so variables set in the `~/.bashrc` file will not persist over a rebuild. For more information, see "[Preventing temporary files from being automatically deleted](#preventing-temporary-files-from-being-automatically-deleted)."
 
 ### For all codespaces for a repository
 
@@ -72,6 +72,8 @@ If you want to set a personalized environment variable for all codespaces that y
 
 ## Preventing temporary files from being automatically deleted
 
-Files saved to your workspace will be available the next time you start the codespace. The exception to this is any file you save in the `/tmp` directory. The contents of this directory are deleted each time the codespace stops (for example, when the codespace session times out after a period of inactivity).
+{% data reusables.codespaces.workspaces-directory %} For information about creating symlinks to preserve data outside the `/workspaces` directory, see "[AUTOTITLE](/codespaces/developing-in-codespaces/rebuilding-the-container-in-a-codespace#persisting-data-over-a-rebuild)."
 
-If you have temporary files that you want to be available the next time you start the codespace, do not save them in the `/tmp` directory. For more information, see "[AUTOTITLE](/codespaces/customizing-your-codespace/setting-your-timeout-period-for-github-codespaces)."
+The `/tmp` directory is an exception because it is mounted into the container, but it is not persistent. Therefore, the contents of the `/tmp` directory are persisted over a rebuild, but are cleared each time the codespace stops. For example, the `/tmp` directory is cleared when a codespace session times out after a period of inactivity. For more information, see "[AUTOTITLE](/codespaces/customizing-your-codespace/setting-your-timeout-period-for-github-codespaces)."
+
+If you have temporary files that you want to be available the next time you start the codespace, do not save them in the `/tmp` directory. 
diff --git a/content/codespaces/developing-in-codespaces/rebuilding-the-container-in-a-codespace.md b/content/codespaces/developing-in-codespaces/rebuilding-the-container-in-a-codespace.md
@@ -1,13 +1,15 @@
 ---
-title: Performing a full rebuild of a container
-intro: 'If you are low on disk space, or want to ensure your dev container configuration will work in new codespaces, you can perform a full rebuild of a container.'
+title: Rebuilding the container in a codespace
+intro: 'You can rebuild a container to apply configuration changes to the codespaces you are working in. From time to time, you may want to perform a full rebuild.'
 versions:
   fpt: '*'
   ghec: '*'
-type: reference
+type: how_to
 topics:
   - Codespaces
-shortTitle: Full rebuilds
+shortTitle: Rebuilding a container
+redirect_from:
+  - /codespaces/codespaces-reference/performing-a-full-rebuild-of-a-container
 ---
 
 ## About rebuilding a container
@@ -23,20 +25,26 @@ Occasionally, you may want to perform a full rebuild of your container. With a f
 - 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.
 
-## Performing a full rebuild
+## Rebuilding a container
 
-You can perform a full rebuild in {% data variables.product.prodname_vscode %}.
+You can rebuild a container within a codespace in the {% data variables.product.prodname_vscode_shortname %} web client or desktop application, or you can use {% data variables.product.prodname_cli %}.
+
+### Rebuilding the dev container in the {% data variables.product.prodname_vscode_shortname %} web client or desktop application
 
 {% data reusables.codespaces.command-palette %}
-1. Start typing "Rebuild" and select **Codespaces: Full Rebuild Container**.
+1. Start typing "Rebuild" and select **Codespaces: Rebuild Container** or **Codespaces: Full Rebuild Container**.
 
    ![Screenshot of the "Codespaces: Full Rebuild Container" option in the Command Palette.](/assets/images/help/codespaces/codespaces-rebuild-full.png)
 
-## Persisting data over a full rebuild
+{% data reusables.codespaces.rebuilding-container-procedures %}
+
+To perform a full rebuild with {% data variables.product.prodname_cli %}, you can use the `gh codespace rebuild --full` command.
+
+## Persisting data over a rebuild
 
-Any files and folders contained in the `/workspaces` directory of your codespace are always persisted over a rebuild. You do not need to change any settings or add any configuration to retain the contents of this directory over a full rebuild.
+{% data reusables.codespaces.workspaces-directory %}
 
-If you want to preserve files outside the `/workspaces` directory over a full 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.
+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.
 
 ```json
 {
diff --git a/content/codespaces/getting-started/deep-dive.md b/content/codespaces/getting-started/deep-dive.md
@@ -42,6 +42,8 @@ When you create a codespace, various steps happen in the background before the c
 
 When you create a codespace, a [shallow clone](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/) is made of your repository, or of the template repository if you're creating a codespace from a template. The repository is cloned to a Linux virtual machine that is both dedicated and private to you. Having a dedicated VM ensures that you have the entire set of compute resources from that machine available to you. If necessary, this also allows you to have full root access to your container.
 
+Your repository is cloned into the `/workspaces` directory in the codespace. For more information, see "[About the directory structure of a codespace](#about-the-directory-structure-of-a-codespace)" below.
+
 ### Step 2: Container is created
 
 {% data variables.product.prodname_github_codespaces %} uses a container as the development environment. This container is created based on configurations that you can define in a `devcontainer.json` file and, optionally, a Dockerfile. If you create a codespace from {% data variables.product.company_short %}'s blank template, or from a repository with no `devcontainer.json` file, {% data variables.product.prodname_github_codespaces %} uses a default image, which has many languages and runtimes available. For more information, see "[AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers)." For details of what the default image contains, see the [`devcontainers/images`](https://github.com/devcontainers/images/tree/main/src/universal) repository.
@@ -153,6 +155,18 @@ If you work on your codespaces in a JetBrains IDE, you can add plugins from the
 
 1. Click **Install** beside the required plugin.
 
+## About the directory structure of a codespace
+
+{% data reusables.codespaces.workspaces-directory %} For more information on the `/tmp` directory, see "[AUTOTITLE](/codespaces/developing-in-codespaces/persisting-environment-variables-and-temporary-files#preventing-temporary-files-from-being-automatically-deleted)."
+
+Clearing the directories outside `/workspaces` helps to ensure the rebuilt container is in the same state as it would be in a newly created codespace. If you're rebuilding a container to apply configuration changes to the codespace you're working in, you can be confident that any configuration changes you have made will work the same for users creating new codespaces with the same configuration. For more information, see "[AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers)."
+
+If you want to make changes to your codespace that will be more robust over rebuilds and across different codespaces, you have several options.
+
+- To install programs and tools in all codespaces created from a repository, in your dev container configuration, you can use lifecycle command properties such as `postCreateCommand` to run custom installation commands, or you can choose from pre-written installation commands called "features." For more information, see the [dev containers specification](https://containers.dev/implementors/json_reference/#lifecycle-scripts) on the Development Containers website and "[AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/adding-features-to-a-devcontainer-file)."
+- To install tools or customize your setup in every codespace you create, such as configuring your `bash` profile, you can link {% data variables.product.prodname_github_codespaces %} with a dotfiles repository. The dotfiles repository is also cloned into the persistent `/workspaces` directory. For more information, see "[AUTOTITLE](/codespaces/customizing-your-codespace/personalizing-github-codespaces-for-your-account#dotfiles)."
+- If you want to preserve specific files over a rebuild, you can use a `devcontainer.json` file to create a symlink between the files and a persistent directory within `/workspaces`. For more information, see "[AUTOTITLE](/codespaces/developing-in-codespaces/rebuilding-the-container-in-a-codespace#persisting-data-over-a-rebuild)."
+
 ## Further reading
 
 - "[AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/enabling-github-codespaces-for-your-organization)"
diff --git a/content/codespaces/getting-started/the-codespace-lifecycle.md b/content/codespaces/getting-started/the-codespace-lifecycle.md
@@ -43,7 +43,9 @@ When a codespace times out, your data is preserved from the last time your chang
 
 You can rebuild your codespace to implement changes to your dev container configuration. For most uses, you can create a new codespace as an alternative to rebuilding a codespace. By default, when you rebuild your codespace, {% data variables.product.prodname_github_codespaces %} will reuse images from your cache to speed up the rebuild process. Alternatively, you can perform a full rebuild, which clears your cache and rebuilds the container with fresh images.
 
-For more information, see "[AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#applying-configuration-changes-to-a-codespace)" and "[AUTOTITLE](/codespaces/codespaces-reference/performing-a-full-rebuild-of-a-container)."
+{% data reusables.codespaces.rebuild-note %}
+
+For more information, see "[AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers)" and "[AUTOTITLE](/codespaces/developing-in-codespaces/rebuilding-the-container-in-a-codespace)."
 
 ## Stopping a codespace
 
diff --git a/content/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers.md b/content/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers.md
@@ -151,7 +151,7 @@ You can add a predefined dev container configuration either while working in a c
 
 1. Follow the prompts to customize your definition.
 1. Click **OK**.
-1. If you are working in a codespace, apply your changes, by clicking **Rebuild now** in the message at the bottom right of the window. For more information about rebuilding your container, see "[Applying changes to your configuration](#applying-configuration-changes-to-a-codespace)."
+1. If you are working in a codespace, apply your changes by clicking **Rebuild now** in the pop-up at the bottom right of the window. For more information about rebuilding your container, see "[Applying configuration changes to a codespace](#applying-configuration-changes-to-a-codespace)."
 
    ![Screenshot of the message: "We've noticed a change to the dev container configuration." Below this is the "Rebuild Now" button.](/assets/images/help/codespaces/rebuild-prompt.png)
 
@@ -227,31 +227,12 @@ You can define default interface settings for {% data variables.product.prodname
 
 Changes to a configuration will be applied the next time you create a codespace. However, you can apply your changes to an existing codespace by rebuilding the container. You can do this within a codespace in the {% data variables.product.prodname_vscode_shortname %} web client or desktop application, or you can use {% data variables.product.prodname_cli %}.
 
+{% data reusables.codespaces.rebuild-note %}
+
 ### Rebuilding the dev container in the {% data variables.product.prodname_vscode_shortname %} web client or desktop application
 
 {% data reusables.codespaces.rebuild-command %}
-1. {% data reusables.codespaces.recovery-mode %}
-
-   ![Screenshot of a message saying that the codespace is running in recovery mode. Below the message are buttons labeled "Cancel" and "View creation log."](/assets/images/help/codespaces/recovery-mode-error-message.png)
-
-   - To diagnose the error by reviewing the creation logs, click **View creation log**.
-   - To fix the errors identified in the logs, update your `devcontainer.json` file.
-   - To apply the changes, rebuild your container.
-
-### Using {% data variables.product.prodname_cli %} to rebuild a dev container
-
-If you've changed a dev container configuration outside of VS Code (for example, on {% data variables.product.prodname_dotcom_the_website %} or in a JetBrains IDE), you can use {% data variables.product.prodname_cli %} to rebuild the dev container for an existing codespace.
-
-1. In a terminal, enter the following command.
-
-   ```
-   gh cs rebuild
-   ```
-
-   Your codespaces are listed.
-
-1. Use the arrow keys on your keyboard to highlight the required codespace, then press <kbd>Enter</kbd>.
-
+{% data reusables.codespaces.rebuilding-container-procedures %}
 
 ## Further reading
 
diff --git a/data/reusables/codespaces/full-rebuild-tip.md b/data/reusables/codespaces/full-rebuild-tip.md
@@ -1,5 +1,5 @@
 {% tip %}
 
-**Tip:** You may occasionally want to perform a full rebuild to clear your cache and rebuild your container with fresh images. For more information, see "[AUTOTITLE](/codespaces/codespaces-reference/performing-a-full-rebuild-of-a-container)."
+**Tip:** You may occasionally want to perform a full rebuild to clear your cache and rebuild your container with fresh images. For more information, see "[AUTOTITLE](/codespaces/developing-in-codespaces/rebuilding-the-container-in-a-codespace#about-rebuilding-a-container)."
 
 {% endtip %}
diff --git a/data/reusables/codespaces/rebuild-note.md b/data/reusables/codespaces/rebuild-note.md
@@ -0,0 +1,5 @@
+{% note %}
+
+**Note:** When you rebuild the container in a codespace, changes you have made outside the `/workspaces` directory are cleared. Changes you have made inside the `/workspaces` directory, which includes the clone of the repository or template from which you created the codespace, are preserved over a rebuild. For more information, see "[AUTOTITLE](/codespaces/getting-started/deep-dive#about-the-directory-structure-of-a-codespace)."
+
+{% endnote %}
diff --git a/data/reusables/codespaces/rebuilding-container-procedures.md b/data/reusables/codespaces/rebuilding-container-procedures.md
@@ -0,0 +1,21 @@
+1. {% data reusables.codespaces.recovery-mode %}
+
+   ![Screenshot of a message saying that the codespace is running in recovery mode. Below the message are buttons labeled "Cancel" and "View creation log."](/assets/images/help/codespaces/recovery-mode-error-message.png)
+
+   - To diagnose the error by reviewing the creation logs, click **View creation log**.
+   - To fix the errors identified in the logs, update your `devcontainer.json` file.
+   - To apply the changes, rebuild your container.
+
+### Using {% data variables.product.prodname_cli %} to rebuild a dev container
+
+If you've changed a dev container configuration outside of {% data variables.product.prodname_vscode_shortname %} (for example, on {% data variables.product.prodname_dotcom_the_website %} or in a JetBrains IDE), you can use {% data variables.product.prodname_cli %} to rebuild the dev container for an existing codespace.
+
+1. In a terminal, enter the following command.
+
+   ```
+   gh codespace rebuild
+   ```
+
+   Your codespaces are listed.
+
+1. Use the arrow keys on your keyboard to highlight the required codespace, then press <kbd>Enter</kbd>.
diff --git a/data/reusables/codespaces/workspaces-directory.md b/data/reusables/codespaces/workspaces-directory.md
@@ -0,0 +1,5 @@
+When you create a codespace, your repository is cloned into the `/workspaces` directory in your codespace. This is a persistent directory that is mounted into the container. Any changes you make inside this directory, including editing, adding, or deleting files, are preserved when you stop and start the codespace, and when you rebuild the container in the codespace.
+
+Outside the `/workspaces` directory, your codespace contains a Linux directory structure that varies depending on the image used to build your codespace. You can add files or make changes to files outside the `/workspaces` directory: for example, you can install new programs, or you can set up your shell configuration in a file such as `~/.bashrc`. As a non-root user, you may not automatically have write access to certain directories, but most images allow root access to these directories with the `sudo` command.
+
+Outside `/workspaces`, with the exception of the `/tmp` directory, the directories in a codespace are tied to the lifecycle of the container. This means any changes you make are preserved when you stop and start your codespace, but are not preserved when you rebuild of the container.
