feat: path-based metadata API following git-notes semantics

Redesign the metadata system to store entries as paths within
Git tree objects, rather than mapping target OIDs directly to
raw tree OIDs. This provides structured, hierarchical metadata
analogous to git-notes but using trees instead of blobs.

Library API (MetadataIndex trait):
- metadata_show: list all entries in a target's metadata tree
- metadata_add: insert a path with optional blob content
- metadata_remove_paths: remove entries by glob pattern (with --keep inversion)
- metadata_copy: copy metadata from one target to another
- metadata_prune: remove entries for non-existent target objects
- metadata_get_ref: return the resolved ref name
- Retain low-level metadata_get, metadata_set, metadata_remove

CLI subcommands (git-notes parity):
- list: show all targets with metadata
- show: display metadata entries for an object
- add: add a path entry (-m, -F, stdin, --force, --allow-empty)
- remove: remove by glob patterns (--keep for inversion)
- copy: copy metadata between objects (-f for overwrite)
- prune: remove stale entries (-n dry run, -v verbose)
- get-ref: print the metadata ref name

feat: resolve revisions (HEAD, refs, short OIDs) in all object arguments
feat: glob matching for remove patterns (*, **, prefix match)

Assisted-by: Zed (Claude Opus 4.6)

Author: jdc-pub

README.md

@@ -35,11 +35,49 @@ Just like notes, metadata added to an object does not alter the object's history
 
 ## Usage
 
-Given any blob (file), tree (folder), or commit, add metadata using `metadata add`.
-By default, `add` assumes you're adding metadata to `HEAD`.
-Alternatively, use the `--oid` option to specify a Git object identifier.
-To remove metadata for a particular object, use `metadata remove` and provide glob patterns which represent entries in the metadata tree to be deleted.
-Use the `--keep` option to instead specify patterns to keep.
+Metadata entries are paths (with optional blob content) stored in a Git tree object, associated with any target object (blob, tree, or commit) via a fanout ref.
+The command follows `git notes` semantics: `list`, `show`, `add`, `remove`, `copy`, `prune`, and `get-ref`.
+
+<!-- rumdl-disable MD013 -->
+
+```shell
+# Add a path entry to HEAD's metadata tree
+git metadata add labels/bug
+git metadata add review/status -m approved
+
+# Add metadata to a specific object
+git metadata add labels/urgent abc1234
+
+# Show all metadata entries for an object
+git metadata show          # defaults to HEAD
+git metadata show abc1234
+
+# List all targets that have metadata
+git metadata list
+
+# Remove entries by glob pattern
+git metadata remove 'labels/*'
+git metadata remove 'labels/bug' -o abc1234
+
+# Keep only matching entries (remove everything else)
+git metadata remove --keep 'review/**'
+
+# Copy metadata from one object to another
+git metadata copy abc1234 def5678
+
+# Remove metadata for objects that no longer exist
+git metadata prune
+git metadata prune -n  # dry run
+
+# Print the metadata ref name
+git metadata get-ref
+
+# Use a custom ref
+git metadata --ref refs/metadata/custom add labels/bug
+```
+
+<!-- rumdl-enable MD013 -->
+
 For more information, see `git metadata --help`.
 
 ## Installation

src/cli.rs

@@ -15,46 +15,98 @@ pub struct Cli {
     #[arg(short = 'C', long, global = true)]
     pub repo: Option<PathBuf>,
 
-    /// The ref under which metadata is stored (e.g. `refs/metadata/commits`).
-    #[arg(short, long, global = true, default_value = "refs/metadata/commits")]
-    pub ref_name: String,
+    /// The ref under which metadata is stored.
+    #[arg(long, global = true, default_value = "refs/metadata/commits")]
+    pub r#ref: String,
 
     #[command(subcommand)]
     pub command: Command,
 }
 
 #[derive(clap::Subcommand)]
 pub enum Command {
-    /// List all entries in the metadata index.
+    /// List all targets that have metadata.
     List,
 
-    /// Read the metadata tree OID attached to a target object.
-    Get {
-        /// The OID of the target object to look up.
-        target: String,
+    /// Show the metadata tree entries for an object.
+    Show {
+        /// The target object (OID or revision). Defaults to HEAD.
+        #[arg(default_value = "HEAD")]
+        object: String,
     },
 
-    /// Write or overwrite the metadata tree for a target object.
-    Set {
-        /// The OID of the target object.
-        target: String,
+    /// Add a path entry to an object's metadata tree.
+    Add {
+        /// The path to add (e.g. `labels/bug`, `review/status`).
+        path: String,
 
-        /// The OID of the tree to associate with the target.
-        tree: String,
+        /// The target object (OID or revision). Defaults to HEAD.
+        #[arg(default_value = "HEAD")]
+        object: String,
 
-        /// Overwrite an existing entry without error.
+        /// Content to store in the blob. Reads from stdin when omitted.
+        #[arg(short, long)]
+        message: Option<String>,
+
+        /// Read content from a file.
+        #[arg(short = 'F', long, conflicts_with = "message")]
+        file: Option<PathBuf>,
+
+        /// Overwrite an existing path without error.
         #[arg(short, long)]
         force: bool,
 
-        /// Fanout depth: number of 2-hex-char directory segments.
-        /// 1 means `ab/cdef01...` (like git-notes). 2 means `ab/cd/ef01...`.
+        /// Allow adding an entry with empty content.
+        #[arg(long)]
+        allow_empty: bool,
+
+        /// Fanout depth (number of 2-hex-char directory segments).
         #[arg(long, default_value_t = 1)]
         shard_level: u8,
     },
 
-    /// Remove the metadata entry for a target object.
+    /// Remove path entries from an object's metadata tree.
     Remove {
-        /// The OID of the target object to remove.
-        target: String,
+        /// Glob patterns for entries to remove (or keep with `--keep`).
+        patterns: Vec<String>,
+
+        /// The target object (OID or revision). Defaults to HEAD.
+        #[arg(short, long, default_value = "HEAD")]
+        object: String,
+
+        /// Invert: keep only entries matching the patterns.
+        #[arg(long)]
+        keep: bool,
+    },
+
+    /// Copy metadata from one object to another.
+    Copy {
+        /// The source object (OID or revision).
+        from: String,
+
+        /// The destination object (OID or revision).
+        to: String,
+
+        /// Overwrite existing metadata on the destination.
+        #[arg(short, long)]
+        force: bool,
+
+        /// Fanout depth (number of 2-hex-char directory segments).
+        #[arg(long, default_value_t = 1)]
+        shard_level: u8,
     },
+
+    /// Remove metadata for objects that no longer exist.
+    Prune {
+        /// Only report what would be pruned; do not actually remove.
+        #[arg(short = 'n', long)]
+        dry_run: bool,
+
+        /// Print each pruned object.
+        #[arg(short, long)]
+        verbose: bool,
+    },
+
+    /// Print the metadata ref name.
+    GetRef,
 }

src/exe.rs

@@ -2,7 +2,7 @@ use std::path::Path;
 
 use git2::{Oid, Repository};
 
-use crate::{MetadataIndex, MetadataOptions};
+use git_metadata::{MetadataEntry, MetadataIndex, MetadataOptions};
 
 /// Open a repository from the given path, or from the environment / current
 /// directory when `None` is passed.
@@ -13,37 +13,71 @@ pub fn open_repo(path: Option<&Path>) -> Result<Repository, git2::Error> {
     }
 }
 
-/// List all entries in the metadata index at `ref_name`.
-///
-/// Returns `(target_oid, tree_oid)` pairs.  An empty `Vec` means no entries
-/// are stored under that ref.
+/// Resolve a revision string (OID, ref, or `HEAD`) to an [`Oid`].
+pub fn resolve_oid(repo: &Repository, rev: &str) -> Result<Oid, git2::Error> {
+    // Try parsing as a full hex OID first.
+    if let Ok(oid) = Oid::from_str(rev) {
+        return Ok(oid);
+    }
+    // Fall back to rev-parse.
+    let obj = repo.revparse_single(rev)?;
+    Ok(obj.id())
+}
+
+/// List all targets that have metadata under `ref_name`.
 pub fn list(repo: &Repository, ref_name: &str) -> Result<Vec<(Oid, Oid)>, git2::Error> {
     repo.metadata_list(ref_name)
 }
 
-/// Read the metadata tree OID attached to `target` under `ref_name`.
-///
-/// Returns `None` if no entry exists for `target`.
-pub fn get(repo: &Repository, ref_name: &str, target: &Oid) -> Result<Option<Oid>, git2::Error> {
-    repo.metadata_get(ref_name, target)
+/// Show the metadata tree entries for `target`.
+pub fn show(
+    repo: &Repository,
+    ref_name: &str,
+    target: &Oid,
+) -> Result<Vec<MetadataEntry>, git2::Error> {
+    repo.metadata_show(ref_name, target)
 }
 
-/// Write or overwrite the metadata tree for `target` under `ref_name`.
-///
-/// Returns the new root tree OID committed under `ref_name`.
-pub fn set(
+/// Add a path entry (with optional content) to a target's metadata tree.
+pub fn add(
     repo: &Repository,
     ref_name: &str,
     target: &Oid,
-    tree: &Oid,
+    path: &str,
+    content: Option<&[u8]>,
     opts: &MetadataOptions,
 ) -> Result<Oid, git2::Error> {
-    repo.metadata_set(ref_name, target, tree, opts)
+    repo.metadata_add(ref_name, target, path, content, opts)
+}
+
+/// Remove path entries matching `patterns` from a target's metadata tree.
+pub fn remove_paths(
+    repo: &Repository,
+    ref_name: &str,
+    target: &Oid,
+    patterns: &[&str],
+    keep: bool,
+) -> Result<bool, git2::Error> {
+    repo.metadata_remove_paths(ref_name, target, patterns, keep)
+}
+
+/// Copy metadata from one target to another.
+pub fn copy(
+    repo: &Repository,
+    ref_name: &str,
+    from: &Oid,
+    to: &Oid,
+    opts: &MetadataOptions,
+) -> Result<Oid, git2::Error> {
+    repo.metadata_copy(ref_name, from, to, opts)
+}
+
+/// Remove metadata for targets whose objects no longer exist.
+pub fn prune(repo: &Repository, ref_name: &str, dry_run: bool) -> Result<Vec<Oid>, git2::Error> {
+    repo.metadata_prune(ref_name, dry_run)
 }
 
-/// Remove the metadata entry for `target` under `ref_name`.
-///
-/// Returns `true` if an entry was removed, `false` if no entry existed.
-pub fn remove(repo: &Repository, ref_name: &str, target: &Oid) -> Result<bool, git2::Error> {
-    repo.metadata_remove(ref_name, target)
+/// Return the metadata ref name.
+pub fn get_ref(repo: &Repository, ref_name: &str) -> String {
+    repo.metadata_get_ref(ref_name)
 }