Lightweight vs annotated tags in Git - CLI Comparison

Introduction

Tags in Git mark specific points in history as important. Lightweight tags are simple bookmarks, while annotated tags store extra information like author and message.

When you want to quickly mark a commit without extra details for personal reference.

When you want to create a release version with author info, date, and a message.

When you need to share a tag with others that includes metadata for clarity.

When you want to sign a tag cryptographically for security.

When you want to list tags and see detailed info about them.

Commands

Creates a lightweight tag named v1.0-lightweight pointing to the current commit. This is a simple pointer without extra info.

Terminal

git tag v1.0-lightweight

Expected Output

No output (command runs silently)

Creates an annotated tag named v1.0-annotated with a message describing the release. This tag stores author, date, and message.

Terminal

git tag -a v1.0-annotated -m "Release version 1.0 with features"

Expected Output

No output (command runs silently)

→

-a - Create an annotated tag

→

-m - Add a message to the tag

Displays detailed information about the annotated tag including the message, author, and the commit it points to.

Terminal

git show v1.0-annotated

Expected Output

tag v1.0-annotated

Tagger: Your Name <[e-mail]>

Date:   Fri Jun 7 12:00:00 2024 +0000



Release version 1.0 with features



commit abcdef1234567890abcdef1234567890abcdef12

Author: Your Name <[e-mail]>

Date:   Fri Jun 7 11:59:00 2024 +0000



    Commit message here

Lists all tags in the repository, both lightweight and annotated.

Terminal

git tag

Expected Output

v1.0-lightweight

v1.0-annotated

Key Concept

If you remember nothing else from this pattern, remember: lightweight tags are simple pointers, while annotated tags store extra information and are better for releases.

Common Mistakes

Creating a lightweight tag when you need to share detailed release info.

Lightweight tags do not store author, date, or messages, so collaborators won't see important context.

Use annotated tags with -a and -m flags to include metadata.

Assuming annotated tags show up automatically on remote after push.

Tags are not pushed by default, so the remote won't have the tag unless explicitly pushed.

Use git push origin v1.0-annotated to share the tag.

Summary

Use 'git tag <name>' to create a lightweight tag as a simple bookmark.

Use 'git tag -a <name> -m "message"' to create an annotated tag with metadata.

Use 'git show <tag>' to see detailed info about an annotated tag.

List all tags with 'git tag' to see both lightweight and annotated tags.