README file from
GithubExternal Rename Handler
Rename a note inside Obsidian and every link to it is updated. Rename the same file in your file manager, from a script, or through a sync client, and Obsidian sees a delete followed by a create — so the links are not updated, and every note that pointed at it is left pointing at nothing.
This plugin recognizes those external renames for what they are and reports them to Obsidian as a single rename, so the file keeps its identity instead of arriving as a stranger. Rewriting the links that pointed at the old name is then done by Advanced Rename and Delete Handler — see Renames below.
[!WARNING]
A rename is recognized only where the file keeps its identity on disk (its inode), and not every file system keeps it: see 05 File systems.
Only files and folders inside the vault that Obsidian tracks are handled, and never those whose names start with
.(dot). See 03 How it works for every limit.
Demo vault
The documentation is a demo vault. Every feature has a note that explains what it does and why you would want it, with a note ready to rename and backlinks ready to watch.
Start reading here — it is plain markdown, so it works on GitHub with nothing installed.
A copy of the vault ships with every release. You can access it via any of the following:
- Running the
External Rename Handler: Open demo vault command. - Downloading
external-rename-handler-demo-vault.zipfrom the Releases. It unzips into a singleexternal-rename-handler-demo-vault-<version>folder. - Browsing its source in
demo-vault/in this repository.
What it does
- A rename made outside Obsidian is recognized as a rename, instead of arriving as an unrelated delete and create. 01 External renames
- A rename made while Obsidian was closed is recognized when Obsidian starts again. 03 How it works
- Moving a file, and moving whole folders, are handled the same way. 02 Moving and folders
- How the detection works, and therefore where its limits are — worth reading before trusting it with anything irreversible. 03 How it works
- Which file systems it works on, each one measured. 05 File systems
- Every setting, by the key it is stored under. 04 Settings
Renames
Since 4.0.0 this plugin no longer rewrites links itself: Advanced Rename and Delete Handler owns rename and delete handling for the whole vault. This plugin sees the rename your file manager made, that one updates the notes pointing at the old name. This plugin offers to install it, once, and carries your old Should update links value over for you to approve. Decline, and external renames are still detected — the file keeps its identity, its open tab and the file explorer follow it — but the links are left as they were.
See also
| Plugin | Features | How External Rename Handler differs |
|---|---|---|
Auto Refresh Explorer |
Polls selected folders; adds externally created files | Different event scope: recognizes external renames |
Link Keeper |
Unlisted/experimental; pairs create/delete within 0.5 seconds by name/folder; updates links; mobile | Alternative detection: inodes; catches offline renames too; delegates link updates |
Vault File Refresh |
Polls for externally added/changed files; Flatpak/network-drive use | Different event scope: recognizes external renames |
Last searched for similar plugins on 2026-10-26.
Installation
The plugin is available in the official Community Plugins repository.
Beta versions
To install the latest beta release of this plugin (regardless if it is available in the official Community Plugins repository or not), follow these steps:
- Ensure you have the BRAT plugin installed and enabled.
- Click Install via BRAT.
- An Obsidian pop-up window should appear. In the window, click the
Add pluginbutton once and wait a few seconds for the plugin to install.
Debugging
By default, debug messages for this plugin (id: external-rename-handler) are hidden.
If you need to enable them refer to the documentation.
Changelog
All notable changes to this project will be documented in the CHANGELOG.
Contributing
Contributions are welcome — see CONTRIBUTING to get set up.