# Base Path Updater

Automatically update path references in Obsidian Bases after folders are moved or renamed.

For example, when `Work/Research` is moved to `Archive/Research`, a Base that filters by that folder automatically uses the new path instead of requiring manual edits.

[English](README.md) · [简体中文](README.zh-CN.md)

## Features

- **Automatic path updates**: Responds to folder renames and moves, including references to their subfolders and files.
- **Multiple view levels**: Checks global Base filters, view-specific filters, and formulas.
- **Reviewable undo history**: Shows before-and-after paths for each affected Base and can undo one complete folder operation.
- **Lightweight daily use**: Does not scan on a timer. Markdown notes are indexed only after you turn on embedded Base updates. Path rewriting still runs only after folder moves.

## Installation

Requires Obsidian **1.9.0 or later** and the built-in **Bases** plugin. The plugin can currently be installed manually and is not yet listed in the Community Plugins directory.

1. Copy the `dist/base-path-updater` folder generated by this project to `.obsidian/plugins/` in your vault.
2. Confirm that the plugin folder contains `main.js`, `manifest.json`, and `styles.css`.
3. Reload Obsidian and enable **Base Path Updater** under **Settings → Community plugins**.

If you downloaded the source code, follow the [development notes](docs/IMPLEMENTATION.md#development-and-build) to generate the installation files first.

## Usage and undo

Once enabled, move or rename a folder in Obsidian. The plugin updates matching Base paths and shows a notice when updates or errors occur.

You can open the history in three ways:

- Click the folder-sync ribbon icon and select **View update history / undo**.
- Search for **Base Path Updater** in the command palette.
- Open the plugin settings and select **View history / undo**.

Expand an entry to see how each Base path changed, then select **Undo Base changes** to restore it. History persists across restarts and keeps up to **30 operations**, with a snapshot budget of approximately **5 MiB**. When the budget is reached, the oldest entries are removed first. If one operation is too large, files that would exceed the budget are skipped and reported.

**Undo restores Base content only; it does not move folders back.** To keep a filter valid, move the folder back to its original location. When undoing multiple operations, start with the newest entry. If a `.base` file was manually edited, changed by a later operation, or deleted, the plugin skips it instead of overwriting newer content. For Bases embedded in Markdown, undo restores matching `base` code blocks and keeps other note edits. Other files from the same operation can still be undone.

## Supported path forms

| Form                  | Example                                  |
| --------------------- | ---------------------------------------- |
| Folder filter         | `file.inFolder("Work/Research")`         |
| Full file path filter | `file.path == "Work/Research/Notes.md"`  |
| Path prefix filter    | `file.path.startsWith("Work/Research/")` |

Single and double quotes are supported, as is placing the path on the left side of an equality comparison. Matching is case-sensitive. Only the original folder and paths below it are updated: moving `Work/Research` does not modify `Work/Researcher`.

When using `startsWith` for a folder, keep the trailing `/` as shown in the example to avoid matching similarly named folders.

## Scope and limitations

- Standalone `.base` files are always processed. `base` code blocks embedded in Markdown are processed only when **Update Bases embedded in Markdown** is turned on in the plugin settings. That switch is off by default. Other fenced examples, such as a `base` block shown inside a longer outer fence, are left unchanged.
- Only folder moves and renames trigger path updates. Renaming an individual note does not trigger a scan.
- The plugin supports explicit fixed paths. Concatenated paths, variables, regular expressions, and other unsupported forms are not rewritten. YAML anchors, aliases, and custom tags are not expanded or modified.
- View names, property display names, and ordinary text are not modified. Matching filters or formulas may be rewritten using YAML double-quoted strings while preserving their meaning.
- Folder moves made while the plugin is disabled are not backfilled. Moves made in an external file manager also depend on whether Obsidian reports them as folder rename events.
- History is stored only in the plugin data directory for the current vault. The plugin makes no network requests, and history is not a complete vault backup.

See the [implementation notes](docs/IMPLEMENTATION.md) for design decisions, references, and acceptance checks. 中文说明请见 [README.zh-CN.md](README.zh-CN.md)。