📋 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