Make batch updates to Obsidian metadata
Project description
obsidian-metadata
A script to make batch updates to metadata in an Obsidian vault. No changes are made to the Vault until they are explicitly committed.
Important Disclaimer
It is strongly recommended that you back up your vault prior to committing changes. This script makes changes directly to the markdown files in your vault. Once the changes are committed, there is no ability to recreate the original information unless you have a backup. Follow the instructions in the script to create a backup of your vault if needed. The author of this script is not responsible for any data loss that may occur. Use at your own risk.
Install
Requires Python v3.10 or above.
pip install obsidian-metadata
Usage
CLI Commands
--config-file
: Specify a custom configuration file location--dry-run
: Make no destructive changes--export-csv
: Specify a path and create a CSV export of all metadata--export-json
: Specify a path and create a JSON export of all metadata--help
: Shows interactive help and exits--log-file
: Specify a log file location--log-to-file
: Will log to a file--vault-path
: Specify a path to an Obsidian Vault--verbose
: Set verbosity level (0=WARN, 1=INFO, 2=DEBUG, 3=TRACE)--version
: Prints the version number and exits
Running the script
Once installed, run obsidian-metadata
in your terminal to enter an interactive menu of sub-commands.
Vault Actions
- Backup: Create a backup of the vault.
- Delete Backup: Delete a backup of the vault.
Inspect Metadata
- View all metadata in the vault
- View all frontmatter
- View all inline metadata
- View all inline tags
- Export all metadata to CSV or JSON file
Filter Notes in Scope: Limit the scope of notes to be processed with one or more filters.
- Path filter (regex): Limit scope based on the path or filename
- Metadata filter: Limit scope based on a key or key/value pair
- Tag filter: Limit scope based on an in-text tag
- List and clear filters: List all current filters and clear one or all
- List notes in scope: List notes that will be processed.
Add Metadata: Add new metadata to your vault.
- Add new metadata to the frontmatter
- Add new inline metadata - Set
insert_location
in the config to control where the new metadata is inserted. (Default: Bottom) - Add new inline tag - Set
insert_location
in the config to control where the new tag is inserted. (Default: Bottom)
Rename Metadata: Rename either a key and all associated values, a specific value within a key. or an in-text tag.
- Rename a key
- Rename a value
- Rename an inline tag
Delete Metadata: Delete either a key and all associated values, or a specific value.
- Delete a key and associated values
- Delete a value from a key
- Delete an inline tag
Transpose Metadata: Move metadata from inline to frontmatter or the reverse.
- Transpose all metadata - Moves all frontmatter to inline metadata, or the reverse
- Transpose key - Transposes a specific key and all it's values
- Transpose value- Transpose a specific key:value pair
Review Changes: Prior to committing changes, review all changes that will be made.
- View a diff of the changes that will be made
Commit Changes: Write the changes to disk. This step is not undoable.
- Commit changes to the vault
Configuration
obsidian-metadata
requires a configuration file at ~/.obsidian_metadata.toml
. On first run, this file will be created. You can specify a new location for the configuration file with the --config-file
option.
To add additional vaults, copy the default section and add the appropriate information. The script will prompt you to select a vault if multiple exist in the configuration file
Below is an example with two vaults.
["Vault One"] # Name of the vault.
# Path to your obsidian vault
path = "/path/to/vault"
# Folders within the vault to ignore when indexing metadata
exclude_paths = [".git", ".obsidian"]
# Location to add metadata. One of:
# TOP: Directly after frontmatter.
# AFTER_TITLE: After a header following frontmatter.
# BOTTOM: The bottom of the note
insert_location = "BOTTOM"
["Vault Two"]
path = "/path/to/second_vault"
exclude_paths = [".git", ".obsidian", "daily_notes"]
insert_location = "AFTER_TITLE"
To bypass the configuration file and specify a vault to use at runtime use the --vault-path
option.
Contributing
Setup: Once per project
There are two ways to contribute to this project.
1. Containerized development
- Clone this repository.
git clone https://github.com/natelandau/obsidian-metadata
- Open the repository in Visual Studio Code
- Start the Dev Container. Run Ctrl/⌘ + ⇧ + P → Remote-Containers: Reopen in Container.
- Run
poetry env info -p
to find the PATH to the Python interpreter if needed by VSCode.
2. Local development
- Install Python 3.10 and Poetry
- Clone this repository.
git clone https://github.com/natelandau/obsidian-metadata
- Install the Poetry environment with
poetry install
. - Activate your Poetry environment with
poetry shell
. - Install the pre-commit hooks with
pre-commit install --install-hooks
.
Developing
- This project follows the Conventional Commits standard to automate Semantic Versioning and Keep A Changelog with Commitizen.
- When you're ready to commit changes run
cz c
- When you're ready to commit changes run
- Run
poe
from within the development environment to print a list of Poe the Poet tasks available to run on this project. Common commands:poe lint
runs all linterspoe test
runs all tests with Pytest
- Run
poetry add {package}
from within the development environment to install a run time dependency and add it topyproject.toml
andpoetry.lock
. - Run
poetry remove {package}
from within the development environment to uninstall a run time dependency and remove it frompyproject.toml
andpoetry.lock
. - Run
poetry update
from within the development environment to upgrade all dependencies to the latest versions allowed bypyproject.toml
.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for obsidian_metadata-0.6.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5797cfddd25906eee94aea2dfa093a1f887e5a6c13e93c18684374c46a58b378 |
|
MD5 | b9cce39fe6faf0545962e35ac74955e8 |
|
BLAKE2b-256 | d9e3476de8eeaf088fe4c62ba33cc03046b1f77e50b65a78af39521402c35eb5 |