gritHEAD → docs/tag
Commands / Branches and tagsMarkdown

grit tag

List tags, or create or delete one (lightweight or annotated).

grit tag
grit tag -l [<pattern>...]
grit tag --sort version|date|name [--reverse] [--contains [REV]] [--points-at REV] [-n N]
grit tag <name>
grit tag <name> [<target>]
grit tag <name> -m <message>
grit tag <name> -F <path|->
grit tag <name> -s -m <message>
grit tag <name> -s --tree-sha256 -m <message>
grit tag <name> -f
grit tag <name> --dry-run
grit tag -d <name>
grit tag --verify <name>...
grit tag -v <name>... --no-signature

Description

With no arguments, lists tag names sorted by version (version:refname). Use -l / --list with optional glob patterns (repeatable), --sort version|date|name, --reverse, --contains [REV] (defaults to HEAD), --points-at <REV> (repeatable), and -n / --limit to cap the list. Plain human output reads names only and avoids loading annotated tag objects; --json and --markdown retain full annotation metadata.

With a name and no -m/-F, creates a lightweight tag pointing at HEAD or the optional <target> revision. With -m or -F, creates an annotated tag object with that message (comment lines starting with # are stripped, matching Git's default cleanup). Use -s / --sign (or tag.gpgSign=true) to cryptographically sign an annotated tag; signed tags verify with git verify-tag and system git tag -v.

Annotated tag messages are stored as raw bytes (Git has no encoding header on tags). When listing with --json or --markdown, a message that is not valid UTF-8 is shown as a Unicode string with U+FFFD replacement characters, not as a corrupt object.

Use -f / --force to replace an existing tag (lightweight or annotated). The previous ref target is reported in --json as replaced.

Use --dry-run on create or delete to preview the outcome without changing refs.

Use --tree-sha256 on a signed tag to attach a tree-sha256 content digest of the tagged commit's tree (implies signing). Repeat --exclude-submodule <glob> to record excluded submodule paths in tree-sha256-excluded headers.

Use --verify / -v on one or more annotated tag names to check the tag object's signature (OpenPGP or SSH, when present) and, when the tag carries a tree-sha256 header, recompute that digest against the tagged commit's tree. Lightweight tags cannot be verified. Use --no-signature to skip signature checking while still validating tree-sha256 when present.

Exit codes: grit tag --verify exits 0 when every named tag passes and 1 when any tag fails verification or is not an annotated tag. Other grit tag modes use the default exit code (0 on success).

Tag names must be valid as refs/tags/<name> under Git's ref-name rules (same checks as git check-ref-format refs/tags/<name>). Invalid names are rejected before writing under .git/refs.

Tags are local until you publish them with grit push --tags. Delete a remote tag with grit push --delete.

Options

Option Description
<name> The tag to create or delete. Omit to list tags.
<target> Revision to tag (default HEAD).
-l, --list List tags matching PATTERN (repeatable). Omit PATTERN to list all.
--sort version (default), date, or name.
--reverse Reverse the sort order.
--contains Only tags whose peeled commit contains REV (default HEAD).
--points-at Only tags pointing at REV (repeatable).
-n, --limit Maximum number of tags to print.
-d, --delete Delete the tag locally.
-a, --annotate Git habit for an annotated tag; ignored when -m or -F is set (those already create an annotated tag). Without a message, grit errors instead of opening an editor.
-m, --message Annotated tag message (repeatable; paragraphs are separated by a blank line, like Git).
-F, --message-file Read the annotated tag message from a file (- reads stdin).
--file Hidden alias for --message-file (deprecated; emits a one-time warning).
-f, --force Replace an existing tag with the same name.
--dry-run Preview create or delete without updating refs.
-s, --sign Sign the tag object (implies annotated; honors tag.gpgSign when omitted).
--no-sign Do not sign, even when tag.gpgSign is true.
--signing-key Signing key id or path for this tag (overrides user.signingkey).
--tree-sha256 Attach a tree-sha256 digest (implies --sign).
--exclude-submodule Submodule path glob excluded from the digest (repeatable).
-v, --verify Verify annotated tags (one or more names).
--no-signature With --verify, skip signature checks (digest still checked when present).
--object Hidden alias for <target> (one release).

JSON output

Schema: v2, v1

Pass --json for stable, scripting-friendly output. The object's action field says what happened:

Field Type Meaning
action string list, create, delete, or verify.
tags array For list, each tag with name, oid, kind, target_kind, optional peeled, and optional annotation (subject, message, tagger with name, email, date in RFC 3339).
truncated boolean For list: true when more tags matched than returned (-n / --limit).
name string For create or delete, the tag name.
oid string For create, full id the tag ref points at (tag object or commit).
kind string For create or list entries: lightweight or annotated.
signed boolean For create, whether the tag object was signed.
peeled string Commit oid when the tag peels to a commit.
replaced string For create with --force, oid the tag ref pointed at before replacement.
dry_run boolean For create or delete, whether refs were left unchanged.
tree_sha256 string For create with --tree-sha256, hex digest recorded on the tag.
tree_sha256_excluded array Submodule paths excluded from the digest (when --exclude-submodule is used).
tree_sha256_files integer Blob count hashed for the tree-sha256 claim.
tree_sha256_submodules integer Submodule trees included in the digest walk.
tree_sha256_hash_ms number Wall time spent computing the tree-sha256 digest (milliseconds).
ok boolean For verify, whether every tag passed.

For action: verify, each element of tags includes name, oid, target, ok, signature (with verdict, optional signer, key, trust), optional tree_sha256 (claimed, computed, match_digest, files, submodules, excluded, bogus_excluded, cycles), not_verifiable_submodules (path, reason), and elapsed.ms.

Markdown output

Pass --markdown for agent-friendly output.

Schema: v2, v1

Markdown uses headings, bullet lists, and fenced blocks; pipe characters inside table cells are escaped. See the JSON output section for the stable field contract.

Exit status

Code Meaning
0 Success, or --verify when every tag passes.
1 --verify when any tag fails or is not annotated.
2 Invalid flags (usage).

See Exit codes.