Standard keys · git-meta

This document suggests a small set of commonly useful metadata keys.

These are not mandatory exchange-format rules. They are implementation-level recommendations intended to improve interoperability between tools that use git-meta.

Note

To propose a new standard key, change to an existing one, or report an issue with this list, open a GitHub issue.

Metadata Keys

Agents

Agent-generated metadata is likely to be common, so a stable namespace is useful.

These keys can be attached to commit, change-id or branch targets.

Implementations should avoid storing secrets in agent metadata keys.

`agent:provider`

string

service or runtime provider that produced the content

Examples

openaianthropiclocal

`agent:model`

string

model identifier used for generation or analysis

Examples

gpt-5claude-sonnet-4llama-3.3-70b

`agent:session-id`

string

provider or tool session identifier

Format

opaque stable string from the originating system

`agent:prompt`

string

canonical prompt or final instruction associated with the target

`agent:summary`

string

human-readable summary of what the agent did or concluded

`agent:transcript`

list

ordered record of the agent session, one message per list item

Format

each item is a single JSON Lines (JSONL) record encoding one message (role, content, and any tool calls)

Commit Data

These keys cover common commit/change level metadata that often needs to live alongside or after the commit itself.

These keys can generally be attached to commit, or change-id targets, though some only make sense on commit as it's contents cannot change (such as signoffs).

`branch-id`

string

stable identifier of the branch the commit originated on, preserved across squash, rebase, or merge operations that would otherwise erase the source branch name

`signed-off`

set

identities that have signed off on the commit (e.g. DCO sign-offs, legal or security approvals)

Format

each entry is Name <email> or another stable identifier for the signer

`review:reviewed`

set

identities of users that reviewed the change

Format

each entry is Name <email> or another stable identifier for the signer

`review:approved`

set

identities that approved the change (a subset of reviewers with an explicit approve verdict)

Format

each entry is Name <email> or another stable identifier for the signer

`conventional:type`

set

conventional commit style high-level classification of the change

Examples

featfixdocsrefactorchorebreaking

`released-in`

set

release tags or versions that introduced this change

`attestation`

list

attestations describing how the content was built or verified, using something like gitsign

Format

each list item is an Signed JSON (DSSE) envelope

Branch Data

These keys cover common branch level metadata that describes the purpose, lifecycle, and integration state of a branch.

These keys are attached to branch targets.

`description`

string

human-readable description of the branch's purpose

`status`

string

lifecycle state of the branch

Examples

draftreadyin-reviewmergedabandonedarchived

`review:url`

string

canonical pull-request, merge-request, or change-list URL or identifier associated with the branch

`ci:url`

string

canonical URL of the most recent CI run for the branch

`issue:id`

set

external issue or ticket references the branch addresses

Examples

GH-1234JIRA-5678

`issue:url`

set

canonical URLs for issues this branch addresses

`label`

set

free-form tags or labels applied to the branch

Examples

securityinfraexperiment

Path Data

These keys describe ownership, provenance, and documentation for a file or directory path in the project. They are useful for replacing checked-in helper files like CODEOWNERS and for annotating vendored or imported code.

These keys are attached to path targets, but most can also be attached to project if they are the default for all paths.

`owner`

set

identities or teams that own the path

Format

each entry is Name <email>, a team handle, or another stable identifier

`reviewer`

set

identities or teams that should be automatically requested to review changes to this path

Format

each entry is Name <email>, a team handle, or another stable identifier

`description`

string

human-readable description of what the file or directory is for

`topic`

set

domain topics this path relates to

Examples

authbillingsearch

`license`

string

SPDX license identifier for paths whose license differs from the project default

Examples

Apache-2.0MITGPL-3.0-or-later

`upstream:url`

string

canonical origin URL for vendored or imported code at this path

`upstream:version`

string

pinned upstream version, tag, or commit identifier for vendored or imported code

`docs:url`

string

canonical documentation URL for this module or path

`agent:instructions`

string

persistent instructions, system prompt, or rules provided to the agent when working on this path

Project Data

These keys cover project-wide metadata that applies to the repository as a whole.

These keys are attached to project targets.

`description`

string

human-readable description of the project

`homepage:url`

string

canonical URL for the project's homepage

`repository:url`

string

canonical URL of the project's source repository

`license`

string

SPDX license identifier for the project

Examples

Apache-2.0MITGPL-3.0-or-later

The meta: namespace is reserved for git-meta protocol configuration (auto-pruning, serialization filters, and similar tooling rules). Project metadata that is not protocol configuration should use a different namespace.

`meta:prune:since`

string

retention window used when auto-pruning is triggered during serialization

Format

ISO-8601 date (e.g. 2025-01-01) or relative duration (90d, 6m, 1y)

`meta:prune:max-keys`

string

integer threshold; when the total number of metadata keys in the serialized tree exceeds this value, an auto-prune is triggered

Examples

10000

`meta:prune:max-size`

string

size threshold; when the total size of all blobs in the serialized tree exceeds this value, an auto-prune is triggered

Format

integer with optional human-friendly suffix (512k, 10m, 1g)

`meta:prune:min-size`

string

minimum subtree size threshold passed through to the prune operation; target subtrees smaller than this are kept in full regardless of age

Format

integer with optional human-friendly suffix (512k, 10m)

`meta:filter`

set

shared serialization filter rules that exclude keys from serialization or route them to alternative refs

Format

each entry is <action> <pattern> [<destination>] where action is exclude or route, pattern is a :-segmented glob, and destination is required for route

Examples

exclude draft:**route myteam:** private

`meta:local:filter`

set

personal serialization filter rules that are themselves never serialized; same format as meta:filter

Format

each entry is <action> <pattern> [<destination>]

Examples

exclude scratch:**route myname:** mine

Format Recommendations

Naming

Keys should use a stable namespace-like structure with : separators.

Recommended conventions:

use short, lowercase segments
kebab/dash case preferred (branch-id rather than branchId or branch_id)
use a broad domain first, then more specific segments
prefer singular nouns for scalar values
reserve plural concepts for collection-typed keys
keep the same key meaning across all target types when possible
tool specific fields should top-level namespace (ie gitbutler: or google:)

Format

Where possible, string values should use simple portable text formats:

timestamps as RFC 3339 / ISO 8601 UTC strings
UUIDs in canonical lowercase hyphenated form
commit IDs as full Git object IDs unless a host system has a stronger stable identifier
enums as short lowercase tokens like pending, success, failed

If a value needs structured payloads, implementations should prefer:

multiple related keys
a collection type
a stable serialized string format such as JSON only when necessary