restic forget
restic forget manages the lifecycle of your snapshots. It doesn't delete data itself (use prune for that), but it "unregisters" old snapshots so they no longer appear in your history. You can specify exactly which snapshots to keep using flexible time-based rules.
Think of forget as the "Policy Engine." It decides which points in history are still valuable and which are junk. It is almost always followed by a prune operation to physically free up disk space.
Basic Syntax
restic forget [snapshotID...] [flags]
Retention Policy Examples
# Keep only the last 7 snapshots
restic forget --keep-last 7
# Keep one backup per day for the last month
restic forget --keep-daily 30
# Keep one backup per month for the last year
restic forget --keep-monthly 12
# Combine rules (The "GFS" Strategy)
restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6
Key Flags
| Flag | Description |
|---|---|
--keep-last N | Keep the most recent N snapshots |
--keep-daily N | Keep the last N days that have at least one snapshot |
--keep-weekly N | Keep the last N weeks that have at least one snapshot |
--keep-monthly N | Keep the last N months that have at least one snapshot |
--keep-yearly N | Keep the last N years that have at least one snapshot |
--keep-tag TAG | Keep all snapshots with this tag, regardless of other rules |
--prune | Highly Recommended: Automatically run prune after forgetting snapshots |
--dry-run / -n | Preview which snapshots would be removed |
--group-by columns | Apply retention rules separately per host, paths, or tags |
Practical Examples
1. The Standard "Safe" Policy
Keep 7 days, 4 weeks, and 12 months. This provides a deep history without linear storage growth.
restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 12 --prune
2. Deleting a Specific Bad Snapshot
If you accidentally backed up a 1TB junk folder, delete that specific snapshot ID.
restic forget d8f3e2a1 --prune
3. Policy Per Host
If your repo stores data for multiple servers, ensure one server's rules don't delete another's backups.
restic forget --group-by host --keep-last 5 --prune
4. Cleaning Up Old Tags
Remove everything tagged as experimental while keeping the last 2.
restic forget --tag experimental --keep-last 2 --prune
forget vs prune
| Step | Command | Action | Risk |
|---|---|---|---|
| 1. Policy | forget | Removes SNAPSHOT IDs (Metadata) | Low (IDs can be recreated if indexes exist) |
| 2. Cleanup | prune | Deletes DATA blobs (Files) | High (Data is permanently gone) |
Always run restic forget --keep-x --dry-run before applying a new policy to a production repository. It will show you exactly which IDs will be lost.
Common Pitfalls
| Pitfall | Consequence | Prevention |
|---|---|---|
| Forgetting to --prune | Snapshots are gone, but disk space is NOT freed. | Always add --prune to your automated cleanup scripts. |
| Global Retention | restic forget --keep-last 1 will delete everything except 1 snapshot in the entire repo, even if it belongs to different servers. | Use --group-by host,paths to apply rules per-source. |
| Over-aggressive Retention | Losing important history from 6 months ago. | Start with conservative rules (keep more than you think you need). |
Examples with Output
Examples with Output
1. Dry Run (Safety First)
Command:
restic forget --keep-last 1 --dry-run
Output:
repository a7b2c9d opened successfully, password is correct
Applying Retention Policy: keep 1 last snapshots
keep 1 snapshots:
ID Time Host Tags Paths
-
f9e2d1c0 2024-01-11 12:00:00 app-01 daily /srv/data
-
1 snapshots
remove 1 snapshots:
ID Time Host Tags Paths
-
d8f3e2a1 2024-01-10 12:00:00 app-01 daily /srv/data
-
1 snapshots
2. Basic Retention (No Prune)
Command:
restic forget --keep-daily 7
Output:
repository a7b2c9d opened successfully, password is correct
Applying Retention Policy: keep 7 daily snapshots
keep 7 snapshots:
ID Time Host Tags Paths
-
a1b2c3d4 2024-01-16 12:00:00 app-01 daily /srv/data
...
-
7 snapshots
remove 2 snapshots:
ID Time Host Tags Paths
-
d8f3e2a1 2024-01-08 12:00:00 app-01 daily /srv/data
e9a2b3c4 2024-01-09 12:00:00 app-01 daily /srv/data
-
2 snapshots
3. Forget and Prune (Full Cleanup)
Command:
restic forget --keep-last 1 --prune
Output:
repository a7b2c9d opened successfully, password is correct
Applying Retention Policy: keep 1 last snapshots
[...]
removed 2 snapshots from 1 groups
counting files in repo
finding used blobs
finding blobs that need repacking
finding index files to rewrite
finding index files to delete
repacking 2 packs
deleting 4 old packs
done
4. Group By Host (Multi-Server Repo)
Command:
restic forget --keep-last 1 --group-by host --dry-run
Output:
repository a7b2c9d opened successfully, password is correct
Applying Retention Policy: keep 1 last snapshots
Snapshot Group: host [app-01]
keep 1 snapshots:
ID Time Host Tags Paths
-
f9e2d1c0 2024-01-11 12:00:00 app-01 daily /srv/data
Snapshot Group: host [db-01]
keep 1 snapshots:
ID Time Host Tags Paths
-
a1b2c3d4 2024-01-11 15:30:00 db-01 manual /var/lib/mysql
5. Remove Specific Snapshot ID
Command:
restic forget a1b2c3d4
Output:
repository a7b2c9d opened successfully, password is correct
removed snapshot a1b2c3d4
What's Next?
Learn about the physical cleanup process in restic prune.