Skip to main content

​
Overview

The cloudstic prune command removes unreachable objects from the repository using mark-and-sweep garbage collection. After deleting snapshots with forget, their associated chunks, content manifests, and metadata become unreachable. Prune identifies and deletes these orphaned objects to reclaim storage space.

​
Usage

​
How It Works

Prune operates in two phases:
  1. Mark Phase: Walks all existing snapshots and marks reachable objects:
    • Snapshot objects (snapshot/*)
    • HAMT tree nodes (node/*)
    • File metadata (filemeta/*)
    • Content manifests (content/*)
    • Data chunks (chunk/*)
  2. Sweep Phase: Scans all objects in the repository and deletes those not marked as reachable.
After sweep, prune also repacks fragmented packfiles if packfile storage is enabled (default). Any packfile that is more than 30% empty will be consolidated to reduce storage overhead.

​
Options

​
flag
Show what would be deleted without actually deleting anything. Useful for previewing the impact before running prune.Default: false
​
flag
Log each object as it’s processed. Shows every deleted object key during the sweep phase.Default: false

​
Global Options

  • -store: Storage backend URI
  • -password, -encryption-key: Repository credentials
  • -quiet: Suppress progress bars
  • -json: Write the command result as JSON to stdout
  • -debug: Log every store request

​
Output

Prune displays:
  • Objects scanned: Total number of objects examined
  • Objects deleted: Number of unreachable objects removed
  • Space reclaimed: Total storage space freed (actual prune only)

​
Example Output (Dry Run)

​
Example Output (Actual Prune)

​
Examples

​
Preview what will be pruned

Use this to verify what will be deleted before running the actual prune.

​
Prune and see details

Shows each object being deleted:

​
Prune with local store

​
Prune with S3 backend

​
When to Run Prune

Prune should be run after using forget to remove snapshots. Deleting snapshots with forget does not immediately free storage. It only removes the snapshot objects themselves. The actual data chunks remain until prune performs garbage collection.
Typical workflow:
  1. Remove old snapshots:
  2. Reclaim storage:
Alternatively, use forget with the -prune flag to automatically prune after forgetting:

​
Difference Between Prune and Forget

Key concept: forget makes data unreachable by removing the snapshot references. prune then reclaims storage by deleting the unreachable data.

​
Performance Considerations

  • Mark phase complexity scales with the number of snapshots and files
  • Sweep phase must scan all objects with specific prefixes (chunk/, content/, filemeta/, node/, snapshot/)
  • For large repositories, prune can take several minutes to complete
  • The operation acquires an exclusive lock on the repository
  • Use -dry-run first to estimate the impact
Repository Lock: Prune acquires an exclusive lock (index/lock.exclusive) to prevent concurrent modifications. backup and restore will fail immediately if this lock is held. They do not wait. The lock is released when prune exits and expires automatically after 1 minute if the process crashes. See Repository Locking for details.

​
Packfile Repacking

When packfile storage is enabled (default for S3/B2 backends), prune automatically repacks fragmented packfiles:
  • Any packfile that is more than 30% empty is consolidated
  • Small objects (less than 512KB) are bundled into 8MB packfiles to reduce API calls
  • Repacking reclaims additional space and improves performance
  • The repacking phase runs after sweep completes

​
Advanced Usage

​
Prune specific store with debug logging

Debug mode shows every store operation:

​
Dry run with verbose output

Shows exactly what would be deleted without performing the deletion.

​
Error Handling

​
Repository locked

If another operation is running:
Solution: Wait for the other operation to complete, or use break-lock if you’re certain no operations are running.

​
Missing objects during mark phase

If prune encounters missing objects referenced by snapshots:
This indicates repository corruption. Run cloudstic check to diagnose integrity issues.
  • forget: Remove specific snapshots from history
  • check: Verify repository integrity
  • list: List all snapshots to see what would be preserved

​
See Also