CLI Contract: `renamer replace`

Command Synopsis

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 `
`--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

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

3.1 KiB Raw Blame History

CLI Contract: renamer replace