---
url: /en/workspaces/file-keeper.md
description: >
  Describes the code backup and file roaming strategies used by Workspaces to
  prevent loss of uncommitted code and configuration files when development
  environments are automatically destroyed, including backup-on-destruction and
  restore-on-rebuild mechanisms.
---
Cloud-native development environments use an on-demand approach with automatic destruction when idle.
To prevent loss of uncommitted code and configuration, the system automatically performs backups and file roaming.

## Workspace Code Backup

No need to worry about losing uncommitted code after the environment is destroyed — the system provides two backup
methods to ensure code safety.

:::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 workspace directory `/workspace`, even if not committed in time,
the system automatically backs it up when the environment is recycled. After rebuilding,
the code is automatically restored to the workspace.

#### 1. Backup and Restore Methods

* **Backup**: Package uncommitted code and back up on environment destruction.
  Each branch retains only one backup. New backups overwrite old ones.
  If two environments are started for the same branch simultaneously,
  the backup from the later destroyed environment overwrites the earlier one.
* **Restore**: Download the backup and restore it to the workspace on environment rebuild.

:::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 (workspace modifications, staging area modifications, untracked files,
  excluding files ignored by `.gitignore`)

#### 3. When Backup Code Is Deleted

* Each branch retains only the latest backup; new backups overwrite old ones.
* When a branch is deleted, all users' backup code under that branch is automatically cleaned up.

#### 4. Restore Policy Description

When rebuilding or creating a new environment,
it starts with the latest branch code and attempts to restore the latest backup.
Conflicts may occur if code was committed outside of cloud-native development environments;
in this case, the restored code can be discarded.

:::tip
**Workspace code backups** are automatically deleted from remote storage after successful restoration,
meaning each backup can only be restored once. A new backup is created when the new environment is destroyed.

**Non-workspace file roaming** backups (such as `.gitconfig`, custom roaming directories, etc.)
are not deleted and will be retained for reuse across future environments.

The following content will not be backed up:

* Content declared in `.gitignore`
* Modified content in submodules
* Modifications outside the workspace

:::

### Scheduled Backup Strategy

To improve backup reliability, the system also uses a scheduled backup strategy,
automatically packaging and backing up uncommitted code every 5 minutes.

* **Download**: Download the backup code package from the "My Cloud-Native Development" list page.
* **Deletion**: The backup is deleted when you delete the development environment history record.

:::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 directories outside the workspace — roaming files are automatically restored after
the environment is destroyed and a new one is created.

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

### Default Roaming Content

The following files or folders roam by user dimension and apply to all projects (`~` is the current user's home
directory, generally `/root`):

* `~/.gitconfig`: Git global configuration. If this file already exists in the container (e.g.,
  pre-configured in a custom environment), it is skipped during both restore and save.
  It's recommended to modify `/etc/gitconfig` instead to avoid conflicts.
* `~/.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

Users can add personal environment configuration files in the `~/.cnb` directory. For example,
add `.env.local` in `~/.cnb` for personal environment variables,
then use [script tasks](../build/grammar.md#script-tasks) to copy or symlink it to the working directory,
and add it to `.gitignore`.

**Example: Link roaming files to the working directory**

To modify the roaming config file, edit `/root/.cnb/.env.local` directly. The example below
links it to the working directory (repository root `/workspace`), choose copy or symlink as needed:

#### Copy (cp)

```yaml title=".cnb.yml"
$: # Fallback matching all branches not matched by glob
  vscode:
    - services:
        - vscode
      stages:
        - name: Link .env.local to working directory
          script: cp -f /root/.cnb/.env.local ./ 2>/dev/null || echo "File does not exist"
```

#### Symlink (ln)

To have changes in the working directory sync back to the roaming file, use a symlink instead:

```yaml title=".cnb.yml"
$: # Fallback matching all branches not matched by glob
  vscode:
    - services:
        - vscode
      stages:
        - name: Link .env.local to working directory
          script: ln -sf /root/.cnb/.env.local ./.env.local
```

### Custom Roaming Directories or Files

In addition to the default roaming content above, users can also customize the directories or files to be roamed.

On the \[Profile

> Workspaces]\(\_\_ENV\_\_DOMAIN\_WITH\_PROTOCOL/profile/workspaces) page,
> you can configure custom roaming directory or file paths. Once configured,
> these directories or files will be automatically roamed and saved when the cloud-native development
> environment is destroyed, and automatically restored when a new environment is created or rebuilt.

**Configuration notes:**

* Absolute paths are required, Glob patterns are supported
* Multiple paths can be separated by newlines

**Examples:**

```text
/root/.bashrc
/root/.config/
```

### Roaming Principle and Timing

**Roaming timing**: Modified roaming files are not immediately saved,
they are extracted and persisted when the environment is destroyed.

**How to restore**: Roaming files are automatically restored when rebuilding the environment.

**How to verify**: You need to destroy the environment and recreate it to see the roaming effect.

:::tip
Note:

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

:::