Skip to main content
The clean-backups command helps you manage disk space by deleting old backup directories while retaining the most recent backups for recovery purposes.

​
Usage

env-twin clean-backups [options]

​
What It Does

The clean-backups command:
  1. Scans the .env-twin/ directory for backup directories
  2. Sorts backups by timestamp (newest first)
  3. Identifies old backups beyond the retention count
  4. Displays which backups will be deleted
  5. Prompts for confirmation (unless --yes is used)
  6. Deletes old backup directories and their contents
  7. Reports the cleanup summary
Deleted backups cannot be recovered. Always review the list of backups to be deleted before confirming.

​
Options

​
--keep
number
default:"10"
Number of recent backups to keepBackups are sorted by timestamp, and the N most recent backups are retained. Older backups are deleted.Example:
env-twin clean-backups --keep 5
This will keep only the 5 most recent backups and delete all older ones.
​
--yes
flag
Skip confirmation prompt and proceed with cleanup immediatelyAliases: -y
Use with caution! Deleted backups cannot be recovered.
Example:
env-twin clean-backups --keep 5 --yes
​
--help
flag
Display help information for the clean-backups commandAliases: -hExample:
env-twin clean-backups --help

​
Examples

Clean up old backups, keeping the default 10 most recent:
env-twin clean-backups
Output:
You have 15 backup(s). Keeping 10 most recent.

Backups to delete:
  - 2024-11-20 09:15:00 (.env, .env.local)
  - 2024-11-19 14:30:00 (.env, .env.local, .env.example)
  - 2024-11-18 11:45:00 (.env, .env.local)
  - 2024-11-17 16:20:00 (.env, .env.example)
  - 2024-11-16 08:50:00 (.env, .env.local)

To skip this confirmation, use: env-twin clean-backups --yes
To keep a different number of backups, use: env-twin clean-backups --keep <number>

Do you want to proceed with the cleanup? (y/N): y

Cleanup Summary:
  ✓ Deleted 5 backup set(s)
  ✓ Kept 10 backup set(s)

Cleanup completed successfully!
Reduce backup retention to 5 backups:
env-twin clean-backups --keep 5
Output:
You have 15 backup(s). Keeping 5 most recent.

Backups to delete:
  - 2024-11-20 09:15:00 (.env, .env.local)
  - 2024-11-19 14:30:00 (.env, .env.local, .env.example)
  - 2024-11-18 11:45:00 (.env, .env.local)
  - 2024-11-17 16:20:00 (.env, .env.example)
  - 2024-11-16 08:50:00 (.env, .env.local)
  - 2024-11-15 13:10:00 (.env, .env.local)
  - 2024-11-14 10:25:00 (.env, .env.local, .env.example)
  - 2024-11-13 15:40:00 (.env, .env.example)
  - 2024-11-12 09:05:00 (.env, .env.local)
  - 2024-11-11 14:55:00 (.env, .env.local)

Do you want to proceed with the cleanup? (y/N):
Skip the confirmation prompt for automated scripts:
env-twin clean-backups --keep 5 --yes
Output:
You have 15 backup(s). Keeping 5 most recent.

Backups to delete:
  - 2024-11-20 09:15:00 (.env, .env.local)
  - 2024-11-19 14:30:00 (.env, .env.local, .env.example)
  ... (8 more)

Cleanup Summary:
  ✓ Deleted 10 backup set(s)
  ✓ Kept 5 backup set(s)

Cleanup completed successfully!
This is useful for:
  • Automated maintenance scripts
  • Scheduled cleanup tasks
  • CI/CD pipeline cleanup stages
When you have fewer backups than the keep count:
env-twin clean-backups --keep 10
Output:
You have 7 backup(s). Keeping 10 most recent.
No backups to delete.
The command exits without prompting since no cleanup is needed.
When no backups are found:
env-twin clean-backups
Output:
No backups found in .env-twin/ directory

​
Backup Sorting

Backups are sorted by timestamp in descending order (newest first): 
Backups (sorted newest to oldest):
  1. 2024-11-25 16:30:22  ← Kept
  2. 2024-11-25 14:30:22  ← Kept
  3. 2024-11-25 09:15:00  ← Kept
  4. 2024-11-24 18:45:00  ← Kept
  5. 2024-11-24 10:20:00  ← Kept (with --keep 5)
  6. 2024-11-23 15:30:00  ← Deleted
  7. 2024-11-22 11:10:00  ← Deleted
  ... older backups ...    ← Deleted
The --keep option determines how many of the newest backups to retain.

​
Use Cases

Run cleanup regularly to prevent disk space issues:
# Weekly cleanup, keep 10 backups
env-twin clean-backups --keep 10
Add this to your scheduled tasks or cron jobs:
# Cron job (every Sunday at 2 AM)
0 2 * * 0 cd /path/to/project && env-twin clean-backups --keep 10 --yes
Clean up old backups before deploying to reduce repository size:
# Keep only 3 most recent backups before deployment
env-twin clean-backups --keep 3 --yes
git add .env-twin/
git commit -m "Clean old backups before deployment"
When running low on disk space:
# Keep only 2 backups to free up space
env-twin clean-backups --keep 2
Before archiving a project, keep minimal backups:
# Keep only 1 backup for archive
env-twin clean-backups --keep 1 --yes

​
Backup Directory Structure

The .env-twin/ directory contains timestamped backup folders: 
.env-twin/
  20241125-163022/         ← Newest (kept)
    .env
    .env.local
    .env.example
  20241125-143022/         ← Kept
    .env
    .env.local
  20241124-091500/         ← Kept
    .env
    .env.local
  20241123-153000/         ← Deleted (if keep < 4)
    .env
    .env.local
    .env.example
Each timestamp directory is treated as one backup set.

​
Best Practices

Don’t keep too few backups. A good rule of thumb:
  • Development: Keep 5-10 backups
  • Staging: Keep 10-20 backups
  • Production: Keep 20-30 backups
# Production environment
env-twin clean-backups --keep 20
Always review the list of backups to be deleted:
# First, see what would be deleted
env-twin clean-backups --keep 5
# Review the output, then confirm with 'y'
Avoid using --yes until you’re confident in your keep count.
When automating cleanup, use a conservative keep count:
# Automated cleanup with safe retention
env-twin clean-backups --keep 15 --yes
Use restore --list to see backup ages:
env-twin restore --list
# Review the ages, then clean up
env-twin clean-backups --keep 5
See the restore command documentation for more details.

​
Comparison with Manual Deletion

Manual Deletion

Pros:
  • Full control over what’s deleted
  • Can inspect each backup individually
Cons:
  • Time-consuming
  • Error-prone
  • Must manually sort by date
  • Risk of deleting wrong backups

clean-backups Command

Pros:
  • Automatic sorting by timestamp
  • Safe retention of recent backups
  • Confirmation prompts
  • Batch operation
  • Scriptable and automatable
Cons:
  • Less granular control

sync

Creates the backups that clean-backups manages

restore

Restore from backups before cleaning them

​
Troubleshooting

Problem: Command reports “No backups found in .env-twin/ directory”Solution: Create backups first by running sync:
env-twin sync
env-twin clean-backups --keep 10
Problem: Cannot delete backup directoriesSolution: Check directory permissions:
ls -la .env-twin/
chmod -R 755 .env-twin/
env-twin clean-backups --keep 10
Problem: .env-twin/ still contains files after cleanupSolution: Some backups were kept (this is expected). To see what’s kept:
env-twin restore --list
If you want to delete all backups:
env-twin clean-backups --keep 0  # Not recommended!
Problem: Deleted backups you neededSolution: Unfortunately, deleted backups cannot be recovered. To prevent this:
  1. Always review the deletion list before confirming
  2. Use a conservative --keep value
  3. Avoid using --yes unless you’re certain
For the future, consider:
  • Version control for .env-twin/ directory (with .gitignore for sensitive files)
  • External backup solutions

​
Safety Features

The clean-backups command includes several safety features:
  1. Confirmation Prompt: Always asks for confirmation unless --yes is used
  2. Detailed Preview: Shows exactly which backups will be deleted
  3. File List Display: Shows which files are in each backup
  4. Keep Count Validation: Ensures at least some backups are retained
  5. Helpful Hints: Provides usage examples and alternative commands
The command will never delete backups if your total backup count is less than or equal to the keep count.

Build docs developers (and LLMs) love

Get started for freeTalk to us