Package: obsidian-metadata
obsidian-metadataA script to make batch updates to metadata in an Obsidian vault. No changes are
made to the Vault until they are explicitly committed.Important DisclaimerIt 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.InstallRequires Python v3.10 or above.pipinstallobsidian-metadataUsageCLI Commands--config-file: Specify a custom configuration file location--dry-run: Make no destructive changes--import-csvImport a CSV file with bulk updates--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--export-template: Specify a path and export all notes with their associated metadata to a CSV file for use as a bulk import template--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 exitsRunning the scriptOnce installed, runobsidian-metadatain your terminal to enter an interactive menu of sub-commands.Vault ActionsBackup: Create a backup of the vault.Delete Backup: Delete a backup of the vault.Export MetadataExport all metadata to a CSV organized by metadata typeExport all metadata to a CSV organized by note pathExport all metadata to a JSON file organized by metadata typeInspect MetadataView all metadata in the vaultView allfrontmatterView allinline metadataView allinline tagsFilter 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 filenameMetadata filter: Limit scope based on a key or key/value pairTag filter: Limit scope based on an in-text tagList and clear filters: List all current filters and clear one or allList notes in scope: List notes that will be processed.Bulk Edit Metadatafrom a CSV file (See theMake Bulk Updatessection below)Add Metadata: Add new metadata to your vault.When adding a new key to inline metadata, theinsert locationvalue in the config file will specify where in the note it will be inserted.Add new metadata to the frontmatterAdd new inline metadata- Setinsert_locationin the config to control where the new metadata is inserted. (Default: Bottom)Add new inline tag- Setinsert_locationin 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 keyRename a valueRename an inline tagDelete Metadata: Delete either a key and all associated values, or a specific value.Delete a key and associated valuesDelete a value from a keyDelete an inline tagMove Inline Metadata: Move inline metadata to a specified location with a noteMove to Top: Move all inline metadata beneath the frontmatterMove to After Title: Move all inline metadata beneath the first markdown headerMove to Bottom: Move all inline metadata to the bottom of the noteTranspose Metadata: Move metadata from inline to frontmatter or the reverse.When transposing to inline metadata, theinsert locationvalue in the config file will specify where in the note it will be inserted.Transpose all metadata- Moves all frontmatter to inline metadata, or the reverseTranspose key- Transposes a specific key and all it's valuesTranspose value- Transpose a specific key:value pairReview Changes: Prior to committing changes, review all changes that will be made.View a diff of the changesthat will be madeCommit Changes: Write the changes to disk. This step is not undoable.Commit changes to the vaultKnown LimitationsMulti-level frontmatter is not supported.# This works perfectly well---key:"value"key2:-one-two-threekey3:["foo","bar","baz"]key4:value# This will not work---key1:key2:-one-two-threekey3:-one-two-three---Configurationobsidian-metadatarequires 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-fileoption.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 fileBelow is an example with two vaults.["Vault One"]# Name of the vault.# Path to your obsidian vault# Note for Windows users: Windows paths must use `\\` as the path separator due to a limitation with how TOML parses strings.#       Example: "C:\\Users\\username\\Documents\\Obsidian"path="/path/to/vault"# Folders within the vault to ignore when indexing metadataexclude_paths=[".git",".obsidian"]# Location to add metadata. One of:#    TOP:            Directly after frontmatter.#    AFTER_TITLE:    After the first header following frontmatter.#    BOTTOM:         The bottom of the noteinsert_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-pathoption.Note for Windows users:Due to how TOMML parses strings, Windows paths must use\\as the path separator.
For example:C:\\Users\\username\\Documents\\ObsidianMake Bulk UpdatesBulk edits are supported by importing a CSV file containing the following columns. Column headers must be lowercase.path- Path to note relative to the vault root foldertype- Type of metadata. One offrontmatter,inline_metadata, ortagkey- The key to add (leave blank for a tag)value- the value to add to the keyAn example valid CSV file ispath,type,key,value
folder 1/note1.md,frontmatter,fruits,apple
folder 1/note1.md,frontmatter,fruits,banana
folder 1/note1.md,inline_metadata,cars,toyota
folder 1/note1.md,inline_metadata,cars,honda
folder 1/note1.md,tag,,tag1
folder 1/note1.md,tag,,tag2How bulk imports work:Only notes which match the path in the CSV file are updatedEffected notes will have ALL of their metadata changedto reflect the values in the CSV fileExisting metadata in a matching note will be rewritten. This may result in it's location and/or formatting within the note being changedInline tags ignore any value added to thekeycolumnCreate a CSV template for making bulk updates containing all your notes and their associated metadata byUsing the--export-templatecli command; orSelecting theMetadata by noteoption within theExport Metadatasection of the appOnce you have a template created you can import it using the--import-csvflag or by navigating to theImport bulk changes from CSVoption.ContributingSetup: Once per projectThere are two ways to contribute to this project.1. Containerized developmentClone this repository.git clone https://github.com/natelandau/obsidian-metadataOpen the repository in Visual Studio CodeStart theDev Container. RunCtrl/⌘+⇧+P→Remote-Containers: Reopen in Container.Runpoetry env info -pto find the PATH to the Python interpreter if needed by VSCode.2. Local developmentInstall Python 3.10 andPoetryClone this repository.git clone https://github.com/natelandau/obsidian-metadataInstall the Poetry environment withpoetry install.Activate your Poetry environment withpoetry shell.Install the pre-commit hooks withpre-commit install --install-hooks.DevelopingThis project follows theConventional Commitsstandard to automateSemantic VersioningandKeep A ChangelogwithCommitizen.When you're ready to commit changes runcz cRunpoefrom within the development environment to print a list ofPoe the Poettasks available to run on this project. Common commands:poe lintruns all linterspoe testruns all tests with PytestRunpoetry add {package}from within the development environment to install a run time dependency and add it topyproject.tomlandpoetry.lock.Runpoetry remove {package}from within the development environment to uninstall a run time dependency and remove it frompyproject.tomlandpoetry.lock.Runpoetry updatefrom within the development environment to upgrade all dependencies to the latest versions allowed bypyproject.toml.