How to Create and Use Git Tags for Versioning? (Release Management)

Lightweight tags only have pointers and no metadata, and annotation tags (git tag -a) must be used for official release; explicit operations are required to push tags, otherwise they will not be visible remotely; tag names must strictly comply with the semantic version format (such as v1.2.3); after deleting remote tags, local tags must be deleted simultaneously and prune.

The git tag command without -a is a lightweight tag. Do not mistake it for official release.

A lightweight tag is just a pointer to a commit without an author, time, signature or description - it cannot be used as a reliable basis for publication. In team collaboration, if you use git tag v1.0.0 , you will not be able to trace it later if you want to check who typed it, when it was typed, and whether it has been modified.

• For official release, you must use git tag -a v1.0.0 -m "Release 1.0.0" to generate annotation tags with metadata.
• When the CI/CD pipeline reads tags (such as GITHUB_REF of GitHub Actions), only annotation tags can ensure that git describe and semantic version tools (such as standard-version ) can be stably parsed
• Lightweight tags cannot be signed. git tag -s only takes effect on annotation tags; unsigned tags are directly judged as untrustworthy in the security audit.

Pushing tags is not the default behavior, git push will not automatically synchronize tags

It is tagged locally and cannot be seen in the remote warehouse - this is the most common place for newcomers to get stuck. Git only pushes branches by default, and tags must be operated separately, otherwise other people's git clone or git fetch will not be able to get any tags.

• Push a single tag: git push origin v1.0.0
• Push all local tags: git push origin --tags (Note: This will push all local tags, including temporary tags for testing)
• A safer approach is to push the specified range: git push origin refs/tags/v1.* to avoid accidentally pushing debug tags on the development branch
• If the CI script relies on git describe --tags to calculate the version number, if the tag is not pushed, it will fallback to the latest commit, causing the build product version number to be confused.

The tag name must comply with the semantic version specification, otherwise npm publish or go mod will reject it.

Names such as v1.0 , 1.0.0-rc1 , and release/2.1 will fail to be recognized by the package manager. They only recognize the format that strictly matches v\d \.\d \.\d (-[0-9A-Za-z.-] )?

• Correct examples: v1.2.3 , v0.8.0-beta.2 , v2.0.0-rc.1
• Error examples: 1.2.3 (missing v prefix), version-1.2.3 (containing illegal characters), v1.2 (missing patch number)
• Go modules require the v prefix and the major version number must match the module path (for example, module example.com/lib/v2 corresponds to the label v2.1.0 )
• If the tag name is illegal when npm publishes, npm publish will directly report the error Invalid version: "1.2.3"

After deleting the remote tag, it still exists locally, and next time --tags will be pushed back

Many people think that git push origin :refs/tags/v0.9.0 deletes the remote tag and that's it. However, the next time git push origin --tags gets it back - because the local tag is still there.

• Delete remote tags: git push origin :refs/tags/v0.9.0
• Delete local tags: git tag -d v0.9.0
• If --tags has been executed, you must first synchronize the remote status with git fetch --prune --tags , and then manually clean up the residue.
• Common pitfalls in the CI environment: The build script uses git fetch --tags to pull all historical tags, but does not filter out the deleted ones, resulting in misjudgment of the version detection logic.

The above is the detailed content of How to Create and Use Git Tags for Versioning? (Release Management). For more information, please follow other related articles on the PHP Chinese website!