Git Tagging

Git Tagging

Git Tagging provides essential version control capabilities for managing codebase changes cleanly, predictably, and efficiently.

Core Concepts & Explanation

---

Key Commands for Tagging

• git tag <tagname> - Create a lightweight tag
• git tag -a <tagname> -m "message" - Create an annotated tag
• git tag <tagname> <commit-hash> - Tag a specific commit
• git tag - List tags
• git show <tagname> - Show tag details

---

What is a Tag?

A tag in Git is like a label or bookmark for a specific commit.

Tags are most often used to mark important points in your project history, like releases (v1.0 or v2.0).

Tags are a simple and reliable way to keep track of versions and share them with your team or users.

Some common tag types include:

• Releases: Tags let you mark when your project is ready for release, so you (and others) can always find that exact version later.
• Milestones: Use tags to highlight major milestones, like when a big feature is finished or a bug is fixed.
• Deployment: Many deployment tools use tags to know which version of your code to deploy.
• Hotfixes: If you need to fix an old version, tags make it easy to check out and patch the right code.

---

Create a Lightweight Tag

A lightweight tag is just a name for a commit.

It's quick and simple, but does not store extra information.

Annotated vs Lightweight Tags

• Annotated Tag: Stores author, date, and message.
  Recommended for releases and sharing with others.

• Lightweight Tag: Just a simple name for a commit (no extra info, like a bookmark).

  Example
  git tag v1.0

---

---

Create an Annotated Tag (-a -m)

An annotated tag stores your name, the date, and a message.

This is recommended for most uses.

Example
git tag -a v1.0 -m "Version 1.0 release"

---

Tag a Specific Commit

You can tag an older commit by specifying its hash:

Example
git tag v1.1 1a2b3c4d

Replace 1a2b3c4d with the commit hash you want to tag.

---

List Tags

See all tags in your repository:

Example
git tag

---

Show Tag Details (git show)

See details about a tag and the commit it points to:

Example
git show v1.0

---

Push Tags to Remote

By default, tags exist only on your local computer.

If you want others to see your tags, you need to push them to your remote repository.

If you don't push your tags, only you will see them, and only locally.

To push a single tag to your remote repository (for example, after creating a release tag):

Example: Push a Single Tag
git push origin v1.0

Did you know? Pushing commits with git push does not push your tags!

You must push tags explicitly as shown above.

To push all your local tags to the remote at once (useful if you've created several tags):

Example: Push All Tags
git push --tags

---

Delete Tags

Delete a tag locally:

Example
git tag -d v1.0

Delete a tag from the remote repository:

Example
git push origin --delete tag v1.0

---

Update or Replace a Tag (Force Push)

If you need to move a tag to a different commit and update the remote, use --force:

Example
git tag -f v1.0 <new-commit-hash>
git push --force origin v1.0

---

Tagging Best Practices

• Use tags to mark releases, major milestones, or stable points in your project.
• Always use annotated tags (with -a -m) for anything public or shared.
• Create tags after passing all tests or before deploying/releasing code.

---

Troubleshooting

• Tag already exists? Use git tag -d <tagname> to delete it, then re-create.
• Pushed the wrong tag? Delete it locally and remotely, then push the correct tag.
• Tag not showing on remote? Remember to push tags with git push origin <tagname> or git push --tags.
• Need to overwrite a tag on the remote? You can force-push a tag with git push --force origin <tagname>, but be careful! This will overwrite the tag for everyone using the remote.

---

---

Practical Terminal Workflow

Execute the following terminal commands to work with this concept in your workspace:

# Check repository status
git status

# View formatted log
git log --oneline -n 5

Best Practices & Pro-Tips

• Atomic Commits: Keep each commit small, focused, and dedicated to a single logical feature or bug fix.
• Imperative Commit Messages: Write commit titles in imperative mood (e.g., Fix CORS bug rather than Fixed CORS bug).
• Review Diff Before Staging: Run git diff to review unstaged modifications before adding files to the index.

Common Gotchas & Troubleshooting

• Detached HEAD State: Triggered when checking out a specific commit hash directly rather than a branch. Create a new branch with git switch -c <branch-name> to preserve edits.
• Accidentally Staged Binary Files: Run git restore --staged <filename> to remove the file from the index without altering your local workspace copy.

Self-Check Challenge

Open your terminal in a test project directory, execute git status, and verify your current working tree state. Practice running git log --oneline to review commit history.