Retention policies let you automatically expire old snapshots while preserving a defined history. This guide explains how to use the forget command with policy flags to implement backup rotation strategies.
How Retention Policies Work Cloudstic’s retention system uses an OR-based approach:
Snapshots are evaluated against all active policies (-keep-last, -keep-daily, etc.)
A snapshot matching any policy rule is kept
Snapshots matching no rules are removed
Multiple policies can apply to the same snapshot (e.g., a snapshot can be both “daily” and “weekly”)
Running forget only removes snapshot metadata. To reclaim storage space, run prune afterward (or use -prune to do both in one step).
Available Retention Flags Flag Description -keep-last NKeep the N most recent snapshots -keep-hourly NKeep N hourly snapshots (one per hour) -keep-daily NKeep N daily snapshots (one per day) -keep-weekly NKeep N weekly snapshots (one per ISO week) -keep-monthly NKeep N monthly snapshots (one per month) -keep-yearly NKeep N yearly snapshots (one per year)
Basic Examples Keep Only the Latest Snapshots Keep the 7 most recent backups, remove everything older:
cloudstic forget -keep-last 7 -prune
Always preview with -dry-run first: cloudstic forget -keep-last 7 -dry-run
Keep 30 Days of Daily Backups Keep one snapshot per day for the last 30 days:
cloudstic forget -keep-daily 30 -prune
How it works:
Snapshots are grouped by date (YYYY-MM-DD)
The most recent snapshot from each day is kept
Days with no snapshots are skipped
Keep Weekly Backups Keep one snapshot per week for the last 8 weeks:
cloudstic forget -keep-weekly 8 -prune
Weeks are defined by ISO 8601 (Monday is the first day of the week).
Common Retention Strategies Strategy 1: Simple Daily Rotation Keep 7 days of backups:
cloudstic forget -keep-last 7 -prune
Use case: Personal backups with daily snapshots, minimal history.Strategy 2: Grandfather-Father-Son (GFS) Keep recent, daily, weekly, and monthly backups:
cloudstic forget \ -keep-last 7 \ -keep-daily 30 \ -keep-weekly 8 \ -keep-monthly 12 \ -prune
Use case: Production systems requiring multiple recovery points.Breakdown:
Last 7 snapshots (any time of day)
One per day for 30 days
One per week for 8 weeks (~2 months)
One per month for 12 months (1 year)
Strategy 3: Long-Term Archival Keep recent backups plus yearly archives:
cloudstic forget \ -keep-last 14 \ -keep-daily 90 \ -keep-weekly 52 \ -keep-monthly 24 \ -keep-yearly 5 \ -prune
Use case: Compliance requirements, historical records.Breakdown:
Last 14 snapshots
One per day for 90 days (~3 months)
One per week for 52 weeks (1 year)
One per month for 24 months (2 years)
One per year for 5 years
Strategy 4: Frequent Recent, Sparse Historical Many recent backups, fewer old ones:
cloudstic forget \ -keep-last 30 \ -keep-weekly 12 \ -keep-monthly 36 \ -prune
Use case: Development environments, active projects.Understanding Policy Evaluation Grouping By default, snapshots are grouped by source , account , and path before policies are applied. This means each backup source is managed independently.
# These two sources have separate retention schedules cloudstic backup -source local -source-path ~/Documents cloudstic backup -source gdrive # This policy applies to BOTH groups independently cloudstic forget -keep-last 7 -prune
Change grouping behavior with -group-by:
# Apply policy globally (ignore source/account/path) cloudstic forget -keep-last 7 -group-by "" # Group only by source cloudstic forget -keep-last 7 -group-by "source" # Group by tags cloudstic forget -keep-last 7 -group-by "tags"
Filtering Apply policies to specific snapshots only:
By Source
By Tag
By Account
By Path
# Keep 30 daily snapshots for Google Drive only cloudstic forget -keep-daily 30 -source gdrive -prune
Multiple Policies Example Combine multiple retention rules:
cloudstic forget \ -keep-last 5 \ -keep-daily 7 \ -keep-weekly 4 \ -prune
How this works:
keep-last 5 : The 5 most recent snapshots are kept (regardless of age)keep-daily 7 : One snapshot per day for 7 days is keptkeep-weekly 4 : One snapshot per week for 4 weeks is keptAny snapshot matching any of these rules is kept
All other snapshots are removed
If a snapshot matches multiple rules, it’s still only kept once (but labeled with all matching reasons).
Previewing Changes with Dry Run Always preview before removing snapshots:
cloudstic forget -keep-daily 7 -keep-weekly 4 -dry-run
Output:
Snapshots for source:local, path:/Documents: keep 11 snapshots: +-----+---------------------+------------------+--------+---------+------------+------------------+ | Seq | Created | Snapshot Hash | Source | Account | Path | Reasons | +-----+---------------------+------------------+--------+---------+------------+------------------+ | 15 | 2026-03-03 22:00:00 | abc123... | local | | /Documents | last, daily, weekly | | 14 | 2026-03-02 22:00:00 | def456... | local | | /Documents | last, daily | | 13 | 2026-03-01 22:00:00 | ghi789... | local | | /Documents | last, daily | ... +-----+---------------------+------------------+--------+---------+------------+------------------+ would remove 4 snapshots: +-----+---------------------+------------------+--------+---------+------------+ | Seq | Created | Snapshot Hash | Source | Account | Path | +-----+---------------------+------------------+--------+---------+------------+ | 4 | 2026-02-10 22:00:00 | jkl012... | local | | /Documents | ... +-----+---------------------+------------------+--------+---------+------------+ 4 snapshots would be removed (dry run)
Once satisfied, run without -dry-run:
cloudstic forget -keep-daily 7 -keep-weekly 4 -prune
Running Forget Without Prune You can separate snapshot removal from storage reclamation:
# Remove snapshot metadata cloudstic forget -keep-last 10 # Later, reclaim storage cloudstic prune
Prune is a safe operation — it only deletes chunks that are not referenced by any remaining snapshot.
Automating Retention Policies Combine backup and retention management in scripts:
#!/bin/bash set -e # Create backup cloudstic backup -source local -source-path ~/Documents # Apply retention policy cloudstic forget \ -keep-last 7 \ -keep-daily 30 \ -keep-weekly 8 \ -keep-monthly 12 \ -prune # Verify integrity weekly (run on Sundays) if [ "$( date +%u)" = "7" ]; then cloudstic check fi
Schedule with cron:
0 2 * * * /home/user/backup.sh >> /var/log/backup.log 2>&1
See the Automation guide for more details.
Advanced Filtering Per-Source Policies Apply different retention rules to different backup sources:
# Keep 30 days for local backups cloudstic forget -keep-daily 30 -source local -prune # Keep 90 days for cloud backups cloudstic forget -keep-daily 90 -source gdrive -prune
Tag-Based Policies Use tags to control retention:
# Create backups with tags cloudstic backup -source local -source-path ~/critical -tag important cloudstic backup -source local -source-path ~/temp -tag scratch # Keep "important" backups longer cloudstic forget -keep-daily 90 -tag important -prune # Remove "scratch" backups after 3 days cloudstic forget -keep-last 3 -tag scratch -prune
Best Practices
Always use -dry-run first
Preview changes before committing: cloudstic forget -keep-last 7 -dry-run
Combine forget and prune
Use -prune to reclaim storage immediately: cloudstic forget -keep-last 7 -prune
Run retention after every backup
Keep your repository tidy by automatically removing old snapshots: cloudstic backup -source local -source-path ~/Documents cloudstic forget -keep-daily 30 -prune
Document your retention policy
Keep a record of your policy for disaster recovery planning.
Test restoration periodically
Verify you can recover files from kept snapshots: cloudstic restore < snapshot-has h > -path Documents/important.pdf
Troubleshooting ”No snapshots to remove” All snapshots match at least one keep rule. Either adjust your policies or this is expected behavior.
Prune Removes No Data Chunks may still be referenced by other snapshots, or packfiles may need time to compact. Run prune again after removing more snapshots.
Unexpected Snapshot Removal Check grouping behavior with -group-by. By default, snapshots are grouped by source, account, and path.
Next Steps