renamer/specs/002-add-replace-command/quickstart.md

Quickstart: Replace Command with Multi-Pattern Support

Goal

Demonstrate how to consolidate multiple filename patterns into a single replacement while using the preview → apply → undo workflow safely.

Prerequisites

• Go toolchain (>= 1.24) installed for building the CLI locally.
• Sample directory with files containing inconsistent substrings (e.g., draft, Draft, DRAFT).

Steps

1. Build the CLI

   go build -o renamer ./...
   

2. Inspect replace help

   ./renamer replace --help
   

   Review syntax, especially the "final argument is replacement" guidance and quoting rules.

3. Run a preview with multiple patterns

   ./renamer replace draft Draft DRAFT final --dry-run
   

   Confirm the table shows each occurrence mapped to final and the summary lists per-pattern counts.

4. Apply replacements after review

   ./renamer replace draft Draft DRAFT final --yes
   

   Observe the confirmation summary, then verify file names have been updated.

5. Undo if necessary

   ./renamer undo
   

   Ensure the ledger entry created by step 4 is reversed and filenames restored.

6. Handle patterns with spaces

   ./renamer replace "Project X" "Project-X" ProjectX --dry-run
   

   Verify that quoting preserves whitespace and the preview reflects the intended substitution.

7. Combine with scope filters

./renamer replace tmp temp stable --path ./examples --extensions .log|.txt --recursive

Confirm only matching files under `./examples` are listed.

8. **Integrate into automation**
 ```bash
 ./renamer replace draft Draft final --dry-run && \
 ./renamer replace draft Draft final --yes

The first command previews changes; the second applies them with exit code 0 when successful.

Next Steps

• Add contract/integration tests covering edge cases (empty replacement, conflicts).
• Update documentation (docs/cli-flags.md, README) with replace command examples.