📋 git-metadata

Porcelain for adding metadata to any object without rewriting history.

[!CAUTION] This project is in active development. There are surely bugs and misbehaviors that have not yet been discovered. Please file a new issue for any misbehaviors you find!

Overview

To support a more expansive usage of the Git object database — as is the goal for other projects within the git-ents organization — new tooling is needed. This project provides a command that allows users to associate arbitrary data to any object in Git's store. The metadata command follows notes semantics.

Notes are a tragically underutilized feature of Git. For more information about git notes entries, Tyler Cipriani's blog post is an excellent introduction, and some highly-motivating examples. One such example is Google's open-source git-appraise project, which stores code review metadata as structured entries in a note blob. While impressive, that design highlights a limitation of notes: structured data, or data that does not map cleanly onto UTF-8 text, is difficult to represent in a blob format. The git-metadata project provides a structured alternative to the notes-blob design using Git trees objects. Just like notes, metadata added to an object does not alter the object's history.

[!TIP] Unlike notes, metadata is not added to git log.

Usage

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.

# 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

For more information, see git metadata --help.

Installation

CLI

The git-metadata plumbing command can be installed with cargo install.

cargo install --locked git-metadata

If ~/.cargo/bin is on your PATH, you can invoke the command with git.

git metadata -h

Library

The git-metadata library can be added to your Rust project via cargo add.

cargo add git-metadata