# Refresh a bundle

Build an updated bundle using a fresh snapshot and previously downloaded packages.

Source: https://debark.dev/docs/operate/refreshing

---
To add packages or get newer versions, take a fresh snapshot and build again. Debark reuses cached downloads across builds, including builds written to a new folder.

## 1. Capture the target’s current state

On the offline machine:

```bash
debark snapshot create --out target-latest.snapshot.tar.zst
```

Copy the snapshot to the online builder. A fresh snapshot includes changes since the previous installation, such as new packages, holds, and repository settings.

## 2. Build the updated bundle

On the online builder, use the new snapshot and your current package list:

```bash
debark build --snapshot target-latest.snapshot.tar.zst \
  --out ./bundle-next --sign operator.key --update jq tree
```

This example assumes you already have `operator.key` from [Sign a bundle](/docs/trust/signing).

`--update` refreshes the repository indexes and resolves the request again. It does not add a full system upgrade; add `--upgrades` if you want to include updates for packages already installed on the target.

Use a new output folder when you want to keep the previous bundle intact. Cached packages are still reused.

## Updating an existing folder

You can point `--out` at the previous bundle instead. During an update, Debark removes superseded package files, while preserving files required by the current plan and files marked as user-supplied. Add `--no-prune` to keep superseded files too.

The following files describe the changes:

| File                        | Contents                                                                |
| --------------------------- | ----------------------------------------------------------------------- |
| `last-run-added.txt`        | Paths added by the latest build.                                        |
| `last-run-removed.txt`      | Paths removed by the latest build.                                      |
| `last-run-unreferenced.txt` | Package files left in the folder but absent from the current apt index. |

Dropping a package from your request does not necessarily remove its old file from the folder. Build into a new folder if you want the output to contain only the current build’s files.

## 3. Review and transfer

```bash
debark verify ./bundle-next --key operator.pub
debark inspect ./bundle-next
debark doctor ./bundle-next
```

Check the build’s exit code and warnings before copying the bundle. Exit code 3 means the build is incomplete; resolve the missing inputs and rebuild.

## 4. Install on the target

```bash
debark install ./bundle-next --key operator.pub --status
sudo debark install ./bundle-next --key operator.pub --yes
```

If you included upgrades, pass `--upgrade` to both commands. Packages already at the required version do not need to be installed again.

## Clean up cached downloads

Preview cache cleanup while keeping downloads used by selected bundles:

```bash
debark store gc ./bundle ./bundle-next --dry-run
```

Remove `--dry-run` to apply it. Cache cleanup does not delete files from those bundle folders. See [Download cache and cleanup](/docs/concepts/store-and-incremental) for retention rules.

<NextSteps
  items={[
    {
      title: 'Upgrade installed packages',
      href: '/docs/guides/upgrades',
      description: 'Include and apply updates for existing packages.',
    },
    {
      title: 'Download cache and cleanup',
      href: '/docs/concepts/store-and-incremental',
      description: 'Understand reuse and free disk space.',
    },
  ]}
/>