{
    "slug": "git_tags",
    "term": "Git Tags",
    "category": "git",
    "difficulty": "beginner",
    "short": "Named references to specific commits, used to mark release points — annotated tags include metadata and are signed; lightweight tags are just pointers.",
    "long": "Lightweight tags are simply named pointers to commits (like branches that never move). Annotated tags are stored as full git objects with tagger identity, timestamp, and message — and can be GPG-signed. Annotated tags are preferred for releases because they carry metadata and appear in git describe output. Tags are not pushed automatically — you must git push origin --tags or push individual tags. Semantic versioning is typically implemented with annotated tags.",
    "aliases": [
        "release tags",
        "version tags"
    ],
    "tags": [
        "git",
        "version-control",
        "releases",
        "semver"
    ],
    "misconception": "git push origin pushes tags — tags require a separate git push origin <tagname> or git push origin --tags.",
    "why_it_matters": "Tags mark production releases for rollback, deployment automation, and changelog generation — missing tags make it impossible to know exactly what code was deployed.",
    "common_mistakes": [
        "Using lightweight tags for releases — annotated tags are preferred as they store who tagged and when.",
        "Forgetting to push tags — git push does not push tags by default.",
        "Not using semver for tag names — v1.2.3 format enables tooling like git describe and release automation.",
        "Tagging the wrong commit — always verify HEAD before tagging, especially after a merge."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "semantic_versioning",
        "changelog",
        "conventional_commits",
        "gitflow_strategy"
    ],
    "prerequisites": [
        "semantic_versioning",
        "git_workflows_compared",
        "continuous_deployment"
    ],
    "refs": [
        "https://git-scm.com/book/en/v2/Git-Basics-Tagging"
    ],
    "bad_code": "# Lightweight tag — no metadata:\ngit tag v1.2.3\ngit push origin main  # Tag NOT pushed!\n# Deploy pipeline cannot find the tag",
    "good_code": "# Annotated tag with message — correct for releases:\ngit tag -a v1.2.3 -m 'Release 1.2.3: fixes #42, adds user export'\ngit push origin v1.2.3  # Push specific tag\n# Or push all tags: git push origin --tags",
    "quick_fix": "Tag every production release: git tag -a v1.2.3 -m 'Release notes' && git push --tags — tags are the permanent anchor between git history and your deployment artefacts",
    "severity": "low",
    "effort": "low",
    "created": "2026-03-15",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/git_tags",
        "html_url": "https://codeclaritylab.com/glossary/git_tags",
        "json_url": "https://codeclaritylab.com/glossary/git_tags.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[Git Tags](https://codeclaritylab.com/glossary/git_tags) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/git_tags"
            }
        }
    }
}