Aller au contenu principal

git-tags

What are Git Tags?​

At its core, a Git tag is a permanent, unchangeable pointer to a specific commit in your repository's history. Think of it like a bookmark or a milestone marker. Unlike branches, which are designed to move and evolve, tags are static. Once created, a tag always refers to the exact same commit unless you explicitly delete and re-create it.

There are two main types of tags:

  1. Lightweight Tags: These are just a pointer to a commit. They're like a branch that never moves. They simply store the commit SHA-1.
  2. Annotated Tags: These are more robust. They are full Git objects (like commits or blobs) and contain a tagger name, email, date, and a tagging message. They can also be GPG-signed for verification. Annotated tags are generally preferred for marking releases.

Why Do We Use Git Tags?​

The "why" boils down to immutability, reliability, and clear communication for significant points in your project's history.

  1. Permanent Release Markers: This is by far the most common and important use case. When you release a new version of your software (e.g., v1.0.0, v2.1-beta), you want a permanent reference to the exact code that was shipped.

    • Reliability: You can always go back and precisely identify the code that corresponds to a given release version.
    • Traceability: If a bug is reported in v1.2.3, you can git checkout v1.2.3 and inspect the code, compile it, or even hotfix it from that exact state.
    • Consistency: Everyone on the team (and automated systems) refers to the same, unambiguous point in history.

  2. Semantic Versioning (SemVer): Tags perfectly align with SemVer (MAJOR.MINOR.PATCH). A tag like v3.0.0 clearly communicates a major, breaking change, while v3.0.1 indicates a patch fix.

  3. CI/CD Integration: Many Continuous Integration/Continuous Deployment (CI/CD) pipelines can be configured to trigger specific actions (like building a release artifact, deploying to production, or archiving) when a new tag is pushed to the remote repository.

  4. Auditing and Compliance: For regulated industries or internal audits, tags provide a crucial record of code states at specific points in time, making it easier to demonstrate compliance.

  5. Milestone Markers: While releases are the primary use, you might use tags to mark other significant project milestones, like "FeatureX_Complete" or "Pre-QA-Build." (Though releases are generally more formal).

When Do We Use Git Tags?​

The timing for using tags is usually tied to significant events in your project's lifecycle:

  1. Upon Software Release: This is the most crucial time. After you've merged your release branch back into your main development branch (e.g., main or master) and confirmed everything is stable and ready, you create a tag for that specific commit.

    • Example: After merging your release/v1.0 branch into main, you'd tag the main HEAD with v1.0.0.

  2. After a Critical Hotfix: If you've pushed a hotfix directly to production (or a critical environment), you'd typically tag that specific hotfix commit to denote the exact version of the fix.

    • Example: A bug in v1.0.0 leads to a quick fix. You tag the fix commit as v1.0.1.

  3. Beta or Release Candidates: You might tag pre-release versions (e.g., v2.0.0-beta.1, v2.0.0-rc.1) to identify specific builds sent out for testing before the final stable release.

  4. Before Major Refactoring/Breaking Changes: Sometimes, it's useful to tag the last stable version before embarking on a huge, potentially disruptive refactor. This gives you an easy rollback point to the "old way."

  5. For Internal Snapshots (Less Common): While branches are better for ongoing development, a tag can occasionally be used to mark a specific, important internal snapshot of the code that you want to preserve immutably.

How Do We Use Git Tags?​

Here are the essential Git commands for working with tags:

1. Listing Tags​

To see all the tags in your repository:

git tag

To search for tags matching a pattern:

git tag -l "v1.*"

2. Creating Tags​

You can tag the current commit (HEAD) or a specific past commit. Always prefer annotated tags for releases.

a. Creating a Lightweight Tag (Current Commit):​

git tag v1.0-lw

(Only use this for temporary, local bookmarks, not for official releases.)

b. Creating an Annotated Tag (Current Commit - Recommended):​

git tag -a v1.0.0 -m "Release version 1.0.0"
  • -a specifies an annotated tag.
  • -m provides the tag message. If you omit -m, Git will open your editor for the message.

c. Creating an Annotated Tag for a Past Commit:​

You need the SHA-1 of the commit you want to tag. You can find this using git log --oneline or git log.

git log --oneline
# Example output:
# a1b2c3d (HEAD -> main) Latest feature work
# e4f5g6h Release version 0.9.0
# ...

git tag -a v0.9.0 -m "Initial public release" e4f5g6h

(Replace e4f5g6h with the actual commit SHA-1.)

d. Creating a GPG-Signed Tag (Annotated and Secure):​

If you have GPG set up, you can sign your tags for added security and verification.

git tag -s v1.0.0 -m "Signed release of version 1.0.0"
  • -s creates a GPG-signed annotated tag.

3. Viewing Tag Details​

To see the details of an annotated tag (including its message, tagger, and the commit it points to):

git show v1.0.0

4. Pushing Tags to a Remote Repository​

Important: Tags are not pushed to the remote repository by default when you git push. You must explicitly push them.

a. Push a single tag:​

git push origin v1.0.0

b. Push all local tags:​

git push origin --tags

(Use this if you've created multiple tags locally and want to push them all at once.)

5. Checking Out a Tag​

When you check out a tag, you enter a detached HEAD state. This means you are directly on a commit, not on a branch. You can view the files, compile the code, etc., but any new commits you make will not be part of any branch unless you explicitly create one.

git checkout v1.0.0

To start development from a tagged version (e.g., to create a hotfix branch):

git checkout -b hotfix/v1.0.1 v1.0.0

This creates a new branch named hotfix/v1.0.1 starting from the commit that v1.0.0 points to, and then switches you to that new branch.

6. Deleting Tags​

a. Deleting a Local Tag:​

git tag -d v1.0.0

b. Deleting a Remote Tag:​

After deleting the local tag, you need to push the deletion to the remote repository.

git push origin :refs/tags/v1.0.0
# OR (simpler syntax)
git push origin --delete v1.0.0

Best Practices for Git Tags​

  • Always use Annotated Tags for Releases: They provide valuable metadata and immutability guarantees.
  • Follow Semantic Versioning: Use tags like vMAJOR.MINOR.PATCH (e.g., v1.2.3). The v prefix is a common convention, but not strictly required by Git.
  • Push Tags Promptly: After creating a release tag locally, push it to your remote repository immediately so others can see and use it.
  • Do Not Move or Re-tag: Once a tag (especially a release tag) is created and pushed, it should be considered sacred. Moving or re-tagging it can cause confusion and break systems that rely on its stability. If you need to make a correction, create a new tag with an incremented version number (e.g., v1.0.1 instead of v1.0.0 again).
  • Keep Tag Messages Clear: For annotated tags, use descriptive messages that explain the purpose of the tag.

By understanding and utilizing Git tags effectively, you bring a higher level of discipline, clarity, and reliability to your software development lifecycle. They are an indispensable tool for managing releases and navigating your project's history.