CLI Contract: `renamer remove`

Command Synopsis

renamer remove <pattern1> [pattern2 ...] [flags]

Global Flags (inherited from root command)

--path <dir> (defaults to current working directory)
-r, --recursive
-d, --include-dirs
--hidden
-e, --extensions <.ext|.ext2>
--dry-run
--yes

Description

Sequentially removes literal substrings from file and directory names. Every token is applied in the order provided, and the resulting name is used for subsequent removals before any filesystem rename occurs.

Arguments & Flags

Argument	Required	Description
`<pattern...>`	Yes (≥1)	Literal substrings to remove sequentially. Quotes required when tokens contain spaces.

Flag	Type	Default	Description
`--path`	string	`.`	Working directory for traversal (global flag).
`-r`, `--recursive`	bool	`false`	Traverse subdirectories (global flag).
`-d`, `--include-dirs`	bool	`false`	Include directory names in removal scope (global flag).
`--hidden`	bool	`false`	Include hidden files/directories (global flag).
`-e`, `--extensions`	string	(none)	Restrict removals to files matching `
`--dry-run`	bool	`false`	Preview only; print proposed removals without applying (global flag).
`--yes`	bool	`false`	Apply changes without interactive prompt (global flag).

Exit Codes

Code	Meaning	Example Trigger
`0`	Success	Preview completed or apply executed without conflicts.
`2`	Validation error	No patterns provided, empty token after trimming, unreadable directory.
`3`	Conflict detected	Target filename already exists after removals.

Preview Output

Lists each impacted item with columns: PATH, TOKENS REMOVED, NEW PATH.
Summary line: Total: <candidates> (changed: <count>, empties: <skipped>, conflicts: <count>).

Apply Behavior

Re-validates preview results, then performs renames in sequence while tracking undo metadata.
Writes ledger entry containing ordered token list and per-token match counts.
Aborts without partial renames if conflicts arise between preview and apply.

Validation Rules

Tokens are deduplicated case-sensitively but order of first occurrence preserved; duplicates logged as warnings.
Resulting names that collapse to empty strings are skipped with warnings.
Conflicts (targets already existing) abort the operation; users must resolve manually.

Examples

renamer remove " copy" " draft"
renamer remove foo foo- bar --path ./reports --recursive --dry-run
renamer remove "Project X" " X" --extensions .txt|.md --yes

2.8 KiB Raw Permalink Blame History

CLI Contract: renamer remove