The Architecture of Batch Renaming in Personal Knowledge Vaults
As Markdown vaults grow to hundreds or thousands of interconnected notes, naming conventions inevitably drift. What began as a neat system of kebab-case titles frequently absorbs mixed conventions: Title Case notes created in desktop interfaces, snake_case files exported from code repositories, and irregular date prefixes imported from mobile capture apps.
Why Blind Renaming Breaks Vault Integrity
In traditional file management, renaming files is considered a trivial operating system operation. In a linked Markdown knowledge graph, however, every file basename serves as an explicit foreign key. Bidirectional wikilinks such as [[Q4 Product Launch Notes]], image embeds like ![[architecture-diagram.png]], and heading anchors depend strictly on exact filename strings.
Running naive command-line renames or bulk renaming utilities without preflight planning creates broken references across your entire vault. A reliable rename pipeline requires three essential guarantees:
- Target collision prevention: Ensuring that two distinct source notes do not transform into the same target destination.
- Preservation of file extensions: Keeping syntax and media extensions intact without accidental truncation or case degradation.
- Wikilink traceability: Producing an auditable before-and-after mapping so you can safely orchestrate search-and-replace updates across your note library.
The Destination Collision Hazard
A subtle yet dangerous hazard of case and separator normalization is the target collision. Consider a vault containing two notes in the same folder:
notes/my_draft_ideas.mdnotes/my-draft-ideas.md
When transforming these files with a kebab-case rule, both basenames evaluate to my-draft-ideas.md. A naive renaming script would overwrite the first file with the second, permanently destroying document history. This planner proactively detects all target collisions before any shell commands are generated, halting the operation and warning you to disambiguate the source files.
ISO Date Prefix Standardization
Daily notes and meeting records frequently employ diverse date formats: compact 8-digit strings (20261013-standup.md), spaced notations (2026 10 13 Meeting.md), or unformatted titles. The ISO 8601 standard (YYYY-MM-DD) is the universally recommended format for vault organization because it sorts chronologically in all filesystem views and terminal tools regardless of locale.
The ISO date normalization preset identifies existing date strings and cleans them into clean YYYY-MM-DD- prefixes while preserving the rest of the descriptive note title.
Non-Destructive Shell Script Safety
The generated bash shell script enforces zero-data-loss execution:
- No-clobber protection: All rename commands utilize
mv -nto guarantee that an existing file on disk is never overwritten. - Preflight directory creation: Intermediate directory structures are generated with
mkdir -pbefore any files are relocated. - Collision exclusion: Files marked with target collisions are automatically excluded from the script output until manually resolved.
Step-by-Step Vault Normalization Protocol
- Extract file inventory: In your vault root, run
git ls-filesorfind . -name "*.md"to generate a complete list of file paths. - Select your naming preset: Paste your list into the planner above and select your target convention (such as
kebab-caseorISO date prefix). - Verify collision status: Review the staging plan. If any items display the
COLLISIONtag, adjust your rules or disambiguate the source note titles. - Copy the bash rename script: Copy the generated script and run it in your terminal. The script will safely execute the renames while skipping any potential clobbers.
- Export the CSV mapping: Download the CSV plan to update your wikilinks across the vault using global search-and-replace or your editor's link-refactoring tools.