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]
The plugin works only if Obsidian is running during the external renames.
The plugin only handles renames for those files/folders that Obsidian tracks.
The plugin only handles renames made inside the vault.
The plugin doesn't handle the renames made outside of the vault even if the renamed files are referenced within the vault.
The plugin doesn't handle the renames in files/folders that start with
.(dot).
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
- 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
- Every setting, by the key it is stored under. 04 Settings
Renames
Up to version 3 this plugin rewrote the links itself, through a copy of a rename/delete handler that four other plugins also bundled — so which copy actually ran depended on Obsidian's load order. Since 4.0.0 it does not, and rename and delete handling belongs to Advanced Rename and Delete Handler instead — one plugin owning it for the whole vault.
The two are meant to be used together: 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.
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 are hidden.
To show them, run the following command in the DevTools Console:
window.DEBUG.enable('external-rename-handler');
For more details, 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.
Support
My other Obsidian resources
See my other Obsidian resources.