Skip to Content
GuidesSafety best practices

Safety best practices

AlignTrue follows a safety-first design with automatic backups, dry-run previews, and easy recovery. This guide shows you how to use these features effectively.

Core safety principles

  1. Preview before applying: Always use --dry-run first
  2. Automatic protection: Backups are attempted before every sync (skipped on --dry-run; sync proceeds with a warning if backup creation fails)
  3. Easy recovery: aligntrue revert for quick rollback with preview
  4. Retention control: Keep 10-100 backups based on your workflow

The dry-run workflow

Always start with preview

Before any sync, see what will change:

# Step 1: Preview (no changes, no backup needed)
aligntrue sync --dry-run
 
# Step 2: Review output carefully
# - Which files will change?
# - Are the changes expected?
# - Any warnings or errors?
 
# Step 3: Sync for real
aligntrue sync

What dry-run shows you

$ aligntrue sync --dry-run
 
Previewing changes (dry-run mode)
 
Files that would be written:
  .cursor/rules/rule1.mdc
  .cursor/rules/rule2.mdc
  AGENTS.md
 
Changes preview:
  - 2 sections updated
  - 1 section added
 
No files were modified (dry-run)

When to skip dry-run

You might skip dry-run when:

  • Rules haven’t changed
  • Just ran dry-run seconds ago
  • Emergency rollback needed
  • Confident in change (your call)

But when in doubt, dry-run.

Understanding automatic backups

Backups are attempted before sync

AlignTrue creates a safety backup before sync (unless --dry-run). If backup creation fails, the sync continues with a warning so you can address the issue:

$ aligntrue sync
 
✔ Creating safety backup
✔ Safety backup created: 2025-11-18T14-30-00-000
✔ Syncing to agents
✔ Wrote 3 files

You cannot disable the attempt, but sync will continue if backup creation fails—fix the warning before relying on the backup.

What gets backed up

Every sync backs up:

  • .aligntrue/ directory (config, rules, metadata, caches/tracking) except .aligntrue/.backups/
  • Agent files whose exporters declare outputs (e.g., AGENTS.md, .cursor/rules/*.mdc)

Not always backed up:

  • Agent files for exporters that do not declare outputs
  • Anything already under .aligntrue/.backups/

Individual file backup (file-level)

When an agent export file already exists (or was manually edited since the last AlignTrue write), AlignTrue backs it up before overwriting:

  • Location: .aligntrue/.backups/files/ directory
  • Format: Timestamped copies with .bak suffix preserving original path structure
  • Example: .cursor/rules/rule1.mdc → .aligntrue/.backups/files/cursor/rules/rule1.2025-01-15T14-30-00.mdc.bak
  • When: Exporters detect an existing file with content or checksum drift and back it up before writing
  • Scope: Applies to agent exports written by AlignTrue; not a universal backup for all files
  • Review: You can review and delete backups anytime

Two layers you can rely on today:

  1. Auto-backup attempt before sync (skipped on --dry-run; sync continues on failure with warning)
  2. Individual file backup for agent exports before overwriting existing content

Backup retention

Control how long to keep backups:

# .aligntrue/config.yaml
backup:
  retention_days: 30 # Age-based: delete backups older than 30 days
  minimum_keep: 3 # Safety floor: always keep at least 3 most recent

Automatic cleanup:

  • Defaults: retention_days: 30, minimum_keep: 3
  • retention_days: 0 disables auto-cleanup (manual only)
  • Cleanup removes backups older than retention_days while keeping at least minimum_keep most recent

Checking your backups

# List all backups
aligntrue backup list
 
# See what's in a specific backup
aligntrue revert --timestamp 2025-11-18T14-30-00-000
# (cancel when you see the preview)

Recovery workflows

Quick recovery with revert

aligntrue revert is your main recovery tool:

# Interactive: choose backup, preview changes
aligntrue revert
 
# Restore specific file with preview
aligntrue revert AGENTS.md
 
# Restore from specific backup
aligntrue revert --timestamp 2025-11-18T14-30-00-000

Why use revert:

  • See exact changes before restoring
  • Restore single files instead of everything
  • Interactive and safe
  • Colored diff for clarity

Example session:

$ aligntrue revert AGENTS.md
 
Choose backup to restore:
  2025-11-18T14-30-00-000 - sync
  2025-11-18T12-15-45-123 - manual
 
Preview of changes to AGENTS.md:
- ## Testing rules
- Test before committing
+ ## Testing
+ Always write tests first
 
Restore "AGENTS.md" from backup? (y/n): y
 
✔ Restored AGENTS.md

Full backup restore

For complete rollback:

# List backups to find timestamp
aligntrue backup list
 
# Restore entire backup
aligntrue backup restore --timestamp 2025-11-18T14-30-00-000

When to use full restore:

  • Multiple files need rollback
  • Want exact state from backup
  • Recovering from major mistake
  • Config changes went wrong

Safety features:

  • Creates temporary backup before restore
  • Atomic operation (all or nothing)
  • Rolls back if restore fails
  • Shows confirmation before proceeding

Creating safety checkpoints

Before major changes:

# Create named backup
aligntrue backup create --notes "Before schema migration"
 
# Make your changes
# ...
 
# If something breaks
aligntrue backup list
aligntrue backup restore --timestamp <your-checkpoint-timestamp>

Safe editing workflows

Solo developer

# 1. Check current state
aligntrue status
 
# 2. Preview changes
aligntrue sync --dry-run
 
# 3. Sync (automatic backup)
aligntrue sync
 
# 4. Edit agent file
vim AGENTS.md
 
# 5. Preview again
aligntrue sync --dry-run
 
# 6. Sync again (another automatic backup)
aligntrue sync
 
# 7. If mistake, restore
aligntrue revert AGENTS.md

Team mode

# 1. Pull latest team rules
git pull origin main
 
# 2. Preview before sync
aligntrue sync --dry-run
 
# 3. Sync to agents (automatic backup)
aligntrue sync
 
# 4. Make personal edits
vim AGENTS.md
 
# 5. Preview before sync
aligntrue sync --dry-run
 
# 6. Sync (automatic backup)
aligntrue sync
 
# 7. Commit to git
git add .aligntrue/ AGENTS.md .cursor/
git commit -m "Update personal rules"

Experimenting safely

# 1. Create checkpoint
aligntrue backup create --notes "Before experiment"
 
# 2. Try your idea
vim AGENTS.md
aligntrue sync --dry-run
aligntrue sync
 
# 3. Test it
# ...
 
# 4a. Keep changes (do nothing)
# 4b. Rollback experiment
aligntrue backup list
aligntrue backup restore --timestamp <experiment-checkpoint>

Managing backup retention

Choosing retention_days

14 days (short):

  • Tight disk space
  • Lightweight projects
  • Daily syncs, quick feedback

30 days (default):

  • Regular development
  • Good balance between history and storage
  • Covers month-long iterations

90 days (extended):

  • Long-running experiments
  • Infrequent syncs
  • Want longer safety net

365 days (archive):

  • Critical projects
  • Regulatory/compliance needs
  • Long-term history

Adjusting retention

# .aligntrue/config.yaml
backup:
  retention_days: 45 # Keep for 45 days instead of default 30
  minimum_keep: 5 # Always keep at least 5 recent backups

Then sync to apply:

aligntrue sync

Manual cleanup

Remove old backups immediately:

# Clean up based on config settings
aligntrue backup cleanup

Storage considerations

Typical backup sizes:

  • Small config: ~2-5KB per backup
  • Medium config: ~5-10KB per backup
  • Large config: ~10-50KB per backup

With 20 backups at ~5KB each = ~100KB total. Negligible.

Error recovery

Sync failed partway

If sync fails, your backup is intact:

$ aligntrue sync
 
✔ Safety backup created: 2025-11-18T14-30-00-000
✔ Syncing to agents
✗ Error writing .cursor/rules/rule1.mdc
 
# Your files are unchanged
# Backup is available if needed

Fix the error and try again. Previous backup still available.

Wrong changes applied

# Undo specific file
aligntrue revert AGENTS.md
 
# Or full rollback
aligntrue backup restore

Backup system failed

If backup creation fails (rare):

$ aligntrue sync
 
⚠ Failed to create safety backup: Disk full
⚠ Continuing with sync (unsafe)...

Fix immediately:

  1. Free up disk space
  2. Run aligntrue backup create to verify backup system works
  3. Then proceed with syncs

Corrupted config

If config is damaged:

# Restore from backup
aligntrue backup restore
 
# Or restore just config
aligntrue revert .aligntrue/config.yaml

Advanced patterns

Before major refactoring

# Create named checkpoint
aligntrue backup create --notes "Stable state before refactor"
 
# Note the timestamp
aligntrue backup list
 
# Make changes incrementally
# After each step:
aligntrue sync --dry-run
aligntrue sync
 
# If any step breaks things
aligntrue backup restore --timestamp <stable-timestamp>

Testing new exporters

# Checkpoint before enabling
aligntrue backup create --notes "Before adding copilot exporter"
 
# Add exporter to config
vim .aligntrue/config.yaml
 
# Test with dry-run
aligntrue sync --dry-run
 
# If output looks good
aligntrue sync
 
# If something's wrong
aligntrue backup restore

Recovering from git conflicts

# After messy git merge
git status
# shows conflicts in .aligntrue/
 
# Restore known-good state
aligntrue backup list
aligntrue backup restore --timestamp <before-merge>
 
# Retry merge more carefully
git merge --abort
# ... handle conflicts properly ...

Safety checklist

Before every sync

  • Run aligntrue sync --dry-run first
  • Review what files will change
  • Check for unexpected changes
  • Note any warnings or errors
  • Understand why changes are happening

Before major changes

  • Create named backup with --notes
  • Note the backup timestamp
  • Test with --dry-run first
  • Apply changes incrementally
  • Verify each step before continuing

After problems

  • Check aligntrue backup list
  • Use aligntrue revert for single files
  • Use backup restore for full rollback
  • Understand what went wrong
  • Fix root cause before retrying

Common mistakes

Skipping dry-run

Problem:

# Danger: syncing without preview
aligntrue sync

Better:

# Safe: preview first
aligntrue sync --dry-run
aligntrue sync

Not checking backups

Problem:

Making changes without knowing you have backups.

Better:

# Verify backups exist
aligntrue backup list
 
# See what's backed up
aligntrue revert --timestamp <latest>
# (cancel after preview)

Disabling backups

Not possible: Backups are mandatory. If you found a way to disable them, that’s a bug.

Too short retention

Problem:

backup:
  retention_days: 1 # Only keeps backups for 1 day

Better:

backup:
  retention_days: 30 # Default: keep for 30 days
  minimum_keep: 3 # Safety floor: at least 3 recent

Ignoring warnings

Problem:

$ aligntrue sync
⚠ Failed to create safety backup
⚠ Continuing with sync (unsafe)...

Don’t ignore this. Fix the backup system.

Better:

# Stop and fix
# Check disk space
df -h
 
# Verify backup system
aligntrue backup create
 
# Then proceed
aligntrue sync

Integration with git

Backups vs git

Backups:

  • Fast local rollback
  • Only .aligntrue/ and agent files
  • Not shared with team
  • Automatic before every sync

Git:

  • Full repository history
  • All files tracked
  • Shared with team
  • Manual commits

Use both:

# Sync creates local backup
aligntrue sync
 
# Git tracks everything
git add .
git commit -m "Update rules"
git push

Recovery priority

  1. Immediate rollback: Use aligntrue revert (fast, local)
  2. Recent changes: Use aligntrue backup restore (fast, local)
  3. Older changes: Use git log and git checkout (full history)
  4. Team coordination: Use git (shared, reviewable)

See also

Last updated on
CI/CD integrationAI-native engineering