Undo

Every file operation in fialr is logged to an append-only audit ledger. The undo system reads this ledger to reverse operations — moving files back to their original locations, clearing provenance metadata, and logging the reversal. Dry-run is default. No file moves without explicit confirmation.

How it works

fialr tracks three pieces of provenance for every file operation:

1. Operations table — the SQLite audit ledger records source path, destination path, operation type, and job UUID for every move, rename, and archive
2. XATTRs — original_name and original_path are stamped on every file before it is moved or renamed
3. Paths table — the is_current flag tracks which path is the file’s current location

The undo system uses all three to reconstruct and execute the reverse operation.

---

Reversible operations

Operation	Reversal
Move	File moved back to original path
Rename	File renamed to original name
Archive (vault)	File rehydrated from vault to original path

Enrichment metadata changes, classification assignments, and deduplication groupings are not reversible via undo.

---

Conflict detection

Before executing any reversal, fialr checks for three conflict types:

Conflict	Cause	Resolution
file_exists	Another file occupies the original path	Skip (default) or overwrite with --force
dir_missing	Original parent directory was deleted	Skip (default) or force creates directory with --force
file_modified	File content changed since the operation	Skip (default) or force moves current version with --force

Conflicts are always surfaced in the dry-run preview. With --force, all conflicts are overridden. Without --force, conflicting operations are skipped and reported.

---

Usage

Preview before undoing

Always preview first. The default mode is dry-run:

# Show the last 10 reversible operations
fialr undo --last 10

# Preview undo for a specific job
fialr undo --job 2026-03-11_organize_a1b2c3d4

Execute the undo

Add --execute to apply the reversal:

# Undo the last 5 operations
fialr undo --last 5 --execute

# Undo a specific job
fialr undo --job 2026-03-11_organize_a1b2c3d4 --execute

# Force through conflicts
fialr undo --last 5 --execute --force

Undo specific operations

Target individual operations by UUID:

fialr undo --op abc123 def456 --execute

---

What happens during undo

For each operation being reversed:

1. Source file verified at current location (BLAKE3 hash check)
2. Conflict check at original location
3. File moved back to original path
4. original_name and original_path XATTRs cleared
5. paths table updated (is_current flags flipped)
6. Reverse operation logged to operations table

Every reversal is itself logged. The audit ledger remains append-only — undo does not delete the original operation record.

---

See also

• undo CLI reference — full command documentation
• Job Execution Model — how operations are tracked
• organize — the primary source of reversible operations