git mktag

Plumbing for git tag -a.

🎯 What & why

Plumbing that creates an annotated tag object from a strictly-formatted message on stdin and prints its SHA. It is the engine sitting under git tag -a / -s, minus any ref bookkeeping.

🧠 Mental model

Think of it as 'hash-object for tags': you hand it the canonical tag blob, it stores the object, you get a SHA. Nothing in refs/tags/ moves until you call update-ref yourself.

🛠️ Synopsis

git mktag < tag.in
# stdin format (exact order, exact field names):
#   object <sha>
#   type <commit|tree|blob|tag>
#   tag <name>
#   tagger <Name> <email> <unix-ts> <tz>
#   <blank line>
#   <message ...>
# prints: <tag-object-sha>

🎚️ Switches & options

Flag	What it does
`--strict`	Enforce strict tag-format checks (default in modern Git).
`(stdin)`	Reads the canonical tag blob; no flags configure the format.
`(no ref update)`	Writes the object only; you must update refs/tags/<name> separately.
`(fsck-driven)`	Validation is governed by fsck.* config (e.g. fsck.missingTaggerEntry).

💡 Use cases

Reproducing or rewriting a historical annotated tag with a known tagger/timestamp.
Scripted release pipelines that build tag objects deterministically from templates.
Importers and converters writing tag objects directly into the object database.
Teaching the wiring under git tag -a so a broken tag can be diagnosed.

🧪 Examples

Build a tag object from a heredoc

git mktag <<'EOF'
object 1a2b3c4d...
type commit
tag v1.0.0
tagger Jane Dev <jane@x> 1714694400 +0000

First stable release
EOF

Pipe stdin from a file

git mktag < tag.in

Wire the tag SHA into refs/tags/

sha=$(git mktag < tag.in) && git update-ref refs/tags/v1.0.0 "$sha"

End-to-end equivalent of git tag -a

printf 'object %s\ntype commit\ntag v1.0.0\ntagger Jane <j@x> %s +0000\n\nrelease\n' "$(git rev-parse HEAD)" "$(date +%s)" | git mktag

🎓 Recommendations

Always pair with git update-ref refs/tags/<name> <sha> or the tag is invisible to porcelain.
For day-to-day signing/tagging, use git tag -a / -s; reach for mktag only in importers and rewrites.
Validate inputs with git fsck after writing if you are batching many tag objects.

🪤 Common pitfalls

The header order and field names are fixed; a stray space or missing blank line is rejected.
mktag does not move any ref, so a successful SHA without update-ref leaves a dangling object.
Tagger timestamps are seconds since epoch plus tz offset; getting the format wrong fails strict checks.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.