---
url: /en/workspaces/file-keeper.md
---
Cloud-native development environments use an on-demand approach with automatic destruction when idle.

To prevent the loss of uncommitted code and configuration files after the development environment is destroyed, cloud-native development adopts the following code backup and file roaming strategies:

## Workspace Code Backup

No need to worry about losing uncommitted code after the environment is destroyed. Cloud-native development uses the following two backup methods to ensure code is not lost.

:::tip
For team development, it is recommended to create personal branches for development. One branch is developed by only one person, which can reduce conflicts caused by code restoration.
:::

### Backup on Development Environment Destruction

After modifying code in the current workspace directory `/workspaces`, if not committed in time, there is no need to worry about losing the modification records. When the environment is recycled, the modified code will be backed up.
After rebuilding the development environment, uncommitted code will be restored to the workspace.

#### 1. Backup and Restore Methods

* Backup on environment destruction: Package uncommitted code into a compressed file and upload for storage.

Note: For the same user, this backup method only retains one backup per branch, i.e., overwriting backup. If two cloud-native development environments are started for the same branch simultaneously, the backup from the later destroyed environment will overwrite the backup from the earlier destroyed environment.

* Restore on environment rebuild: Download the backup compressed file and restore it to the workspace as-is.

:::tip
The following situations will not be backed up:

* Individual code files or individual diff files larger than 100MB will be filtered out; only files not exceeding 100MB will be packaged
* If the total backup file size exceeds 100MB, it will not be backed up

Large files are recommended to be ignored using `.gitignore`
:::

#### 2. Backup Content

* Stashes in the workspace
* Commits in the workspace that have not been pushed
* Uncommitted code in the workspace (including workspace modifications, staging area modifications, untracked files, excluding files ignored by `.gitignore`)

#### 3. When Backup Code Is Deleted

Each branch corresponds to only one backup: the backup from each environment will overwrite the backup from the previous environment, and only the latest backup is saved for each branch.

#### 4. Restore Policy Description

When rebuilding or creating a new environment, it will drift to the latest code, i.e., the development environment starts with the latest branch code by default.
The latest backup will be restored during restoration. If code has been committed in a non-cloud-native development environment, conflicts may occur. In this case, you can discard the restored code.

:::tip
After code restoration, the backup will be deleted, meaning each backup can only be restored once. A new backup will be created when the new environment is destroyed. The following content will not be backed up:

* Content declared in the `.gitignore` file will not be backed up
* Modified content in submodules will not be backed up
* Modifications outside the workspace will not be backed up

:::

### Scheduled Backup Strategy

To avoid failures with the above backup method, cloud-native development also employs a scheduled backup strategy, periodically packaging and uploading uncommitted code.

* Backup: Every 5 minutes, uncommitted code in the workspace is collected, compressed, and uploaded.
* Download: You can download the backup code package from the "My Cloud-Native Development" list page.
* Deletion: The backup will be deleted when you delete the development environment history record on the "My Cloud-Native Development" list page.

:::tip

* Files larger than 100MB will not be backed up.
* Backup code packages larger than 100MB will not be backed up either.

:::

## Non-Workspace File Roaming

Workspaces supports file roaming for certain directories outside the workspace.

After the environment is destroyed and a new development environment is created, roaming files can be restored to the development environment.

Maximum roaming capacity: \_\_ENV\_\_VSCODE\_USER\_DATA\_SIZE MB. Exceeding this limit will result in an error and prevent roaming.

### Roaming Content

The following files or folders will roam by user dimension,
effective for all projects (`~`: the current user's home directory, generally the `/root` directory):

* `~/.gitconfig`: Git global configuration file. Special handling: if this file already exists in the container (e.g., pre-configured in a custom environment), it will be skipped during both restore and save, preserving the container's original configuration. Tip: when customizing environments, it is recommended to modify `/etc/gitconfig` instead to avoid conflicts with user roaming configuration files
* `~/.local/share/code-server/User/settings.json`: WebIDE configuration file
* `~/.local/share/code-server/User/snippets/*`: WebIDE related configurations
* `~/.local/share/code-server/User/keybindings.json`：WebIDE shortcut key configuration
* `~/.cnb`: Users can add personal environment configuration files as needed in this directory.

Instructions for using the `~/.cnb` directory:

* Adding configuration files: If the repository needs to add a personal configuration file `.env.local` to store personal environment variables, you can add the `.env.local` file in the `~/.cnb` directory
* After the environment starts, you can configure [script tasks](../build/grammar.md#script-tasks) to copy or symlink `~/.cnb/.env.local` to the working directory (default is `/workspace`),
  `.cnb.yml` configuration as follows
* Add the ignored file `.env.local` to `.gitignore` to prevent personal configuration files from being committed to the repository

Example 1, copying files to the working directory:

To modify the roaming configuration file, you need to directly modify `/root/.cnb/.env.local`

```yaml title=".cnb.yml"
$:
  vscode:
    - name: vscode
      services:
        - vscode
      stages:
        - name: Copy .env.local file to the working directory (repository root)
          # ./ is the working directory, default is /workspace
          script: |
            if [ -e "/root/.cnb/.env.local" ]; then
                cp -f /root/.cnb/.env.local ./
            else
                echo "File does not exist"
            fi
```

Example 2, symlinking files to the working directory:

To modify the roaming configuration file, you can modify `/workspace/.env.local` in the working directory (symlink method will synchronize changes to the source file)

```yaml title=".cnb.yml"
$:
  vscode:
    - name: vscode
      services:
        - vscode
      stages:
        - name: Symlink .env.local file to the working directory (repository root)
          # ./ is the working directory, default is /workspace
          script: |
            if [ -e "/root/.cnb/.env.local" ]; then
                ln -sf /root/.cnb/.env.local ./.env.local 
            else
                echo "File does not exist"
            fi
```

### Roaming Principle and Timing

**Roaming timing:**

When a user modifies configurations (such as settings.json) in the development environment, the modified content is not immediately roamed.
Instead, it waits until the development environment is destroyed, then extracts the files that need to be roamed from the development environment for persistent storage.

**How to restore roaming files:**

When rebuilding the development environment, roaming files will be automatically restored to the development environment.

**How to verify if files have been successfully roamed:**

After modifying roamable files, to verify the effect of the modifications, you need to wait until the development environment is destroyed, then create/rebuild the development environment to see the roaming effect of the modified files.

:::tip
Note:

* When multiple development environments are open simultaneously, the roaming content from the environment destroyed later will overwrite the roaming content from the environment destroyed earlier.
* Closing the development environment using `kill 1` will not successfully roam the files.
* If the file to be roamed is a soft link, we will roam the original file rather than the soft link, to prevent the loss of the original file. If the original file of the soft link does not exist, it will not be roamed.

:::