71 lines
3.1 KiB
Markdown
71 lines
3.1 KiB
Markdown
# CLI Contract: `renamer replace`
|
|
|
|
## Command Synopsis
|
|
|
|
```bash
|
|
renamer replace <pattern1> [pattern2 ...] <replacement> [flags]
|
|
```
|
|
|
|
### Global Flags (inherited from root command)
|
|
- `--path <dir>` (defaults to current working directory)
|
|
- `-r`, `--recursive`
|
|
- `-d`, `--include-dirs`
|
|
- `--hidden`
|
|
- `-e`, `--extensions <.ext|.ext2>`
|
|
- `--yes` — apply without interactive confirmation (used by all mutating commands)
|
|
- `--dry-run` — force preview-only run even if `--yes` is supplied
|
|
|
|
## Description
|
|
Batch-replace literal substrings across filenames and directories using shared traversal and preview
|
|
infrastructure. All arguments except the final token are treated as patterns; the last argument is
|
|
the replacement value.
|
|
|
|
## Arguments & Flags
|
|
|
|
| Argument | Required | Description |
|
|
|----------|----------|-------------|
|
|
| `<pattern...>` | Yes (≥2) | Literal substrings to be replaced. Quotes required when containing spaces. |
|
|
| `<replacement>` | Yes | Final positional argument; literal replacement applied to each pattern. |
|
|
|
|
| Flag | Type | Default | Description |
|
|
|------|------|---------|-------------|
|
|
| `--path` | string | `.` | Working directory for traversal (global flag). |
|
|
| `-r`, `--recursive` | bool | `false` | Traverse subdirectories depth-first (global flag). |
|
|
| `-d`, `--include-dirs` | bool | `false` | Include directory names in replacement scope (global flag). |
|
|
| `--hidden` | bool | `false` | Include hidden files/directories (global flag). |
|
|
| `-e`, `--extensions` | string | (none) | Restrict replacements to files matching `|`-delimited extensions (global flag). |
|
|
| `--yes` | bool | `false` | Skip confirmation prompt and apply immediately after successful preview (global flag). |
|
|
| `--dry-run` | bool | `false` | Force preview-only run even if `--yes` is provided (global flag). |
|
|
|
|
## Exit Codes
|
|
|
|
| Code | Meaning | Example Trigger |
|
|
|------|---------|-----------------|
|
|
| `0` | Success | Preview or apply completed without conflicts. |
|
|
| `2` | Validation error | Fewer than two arguments supplied or unreadable directory. |
|
|
| `3` | Conflict detected | Target filename already exists; user must resolve before retry. |
|
|
|
|
## Preview Output
|
|
- Lists each impacted file with columns: `PATH`, `MATCHED PATTERN`, `NEW PATH`.
|
|
- Summary line: `Total: <files> (patterns: pattern1=#, pattern2=#, conflicts=#)`.
|
|
|
|
## Apply Behavior
|
|
- Re-validates preview results before writing changes.
|
|
- Writes ledger entry capturing old/new names, patterns, replacement string, timestamp.
|
|
- On conflict, aborts without partial renames.
|
|
|
|
## Validation Rules
|
|
- Minimum two unique patterns required (at least one pattern plus replacement).
|
|
- Patterns and replacement treated as UTF-8 literals; no regex expansion.
|
|
- Duplicate patterns deduplicated with warning in preview summary.
|
|
- Replacement applied to every occurrence within file/dir name.
|
|
- Empty replacement allowed but requires confirmation message: "Replacement string is empty; affected substrings will be removed."
|
|
|
|
## Examples
|
|
|
|
```bash
|
|
renamer replace draft Draft DRAFT final
|
|
renamer replace "Project X" "Project-X" ProjectX --extensions .txt|.md
|
|
renamer replace tmp temp temp-backup stable --hidden --recursive --yes
|
|
```
|