Articles

How to Create, List, and Manage Tags in Git

  • Free course

    Learn Git: Introduction

    Learn how to track changes in your code and switch between different versions with Git, an open-source version control system.
    • Beginner Friendly.
      1 hour
  • Free course

    Using Git for DevOps: Using Git Effectively

    Become proficient in Git for DevOps, including repository management, Git commands, GUI, distributed workflows, branching, Git server protocols, and Gitflow.
    • Intermediate.
      1 hour

What is a Git tag?

A Git tag is a special kind of reference that points to a specific commit in the commit history of a repository. Unlike branches, which move forward with each new commit, tags remain attached to the commit that they are assigned to.

Tags serve as human-readable labels that make it easier to navigate a project’s timeline. For example, instead of trying to remember the hash 9fceb02, we can simply refer to it as v2.0.1. By tagging a commit, teams can signal that a specific version of the code is ready for staging or live deployment, eliminating guesswork and reducing human error.

There are two types of tags in Git:

  • Lightweight tags
  • Annotated tags

Let’s first learn how to create lightweight tags in Git.

How to create lightweight Git tags

A lightweight Git tag is like a bookmark to a specific commit. It doesn’t contain any extra metadata — just the reference itself.

To create a lightweight tag, run this command in the terminal: 

git tag v1.0

This command tags the latest commit with the name v1.0.

To verify if the operation was successful, run this command: 

git show v1.0

This will display the commit message, author, and diff associated with that commit. 

commit d4ebf2e23845268a2bf3bd68ef482449a7b1c58c (HEAD -> main, tag: v1.0, origin/main, origin/HEAD) 
Author: Codecademy <[email protected]> 
Date:   Sat May 10 20:57:33 2025 +0530 
    [UI] Improve UI of the landing page 
diff --git a/client/styles.css b/client/styles.css 
...

Lightweight tags are simple, but sometimes we need more context. That’s where annotated tags come in.

How to create annotated Git tags

An annotated Git tag stores additional information like the tagger’s name, date, email, and a message. These are recommended for public releases.

To create an annotated tag, run this command: 

git tag -a v1.0 -m "Initial stable release"

In this command:

  • -a: Specifies the tag name
  • -m: Specifies the tag message

This command tags the latest commit with the name v1.0 and the given message.

Run this command to check if the operation is successful: 

git show v1.0

Here is the output: 

tag v1.0 
Tagger: Codecademy <[email protected]> 
Date:   Fri Jul 11 18:23:39 2025 +0530 


Initial stable release 


commit d4ebf2e23845268a2bf3bd68ef482449a7b1c58c (HEAD -> main, tag: v1.0, origin/main, origin/HEAD) 
Author: Codecademy <[email protected]> 
Date:   Sat May 10 20:57:33 2025 +0530 


    [UI] Improve UI of the landing page 
diff --git a/client/styles.css b/client/styles.css 
...

Whether we’re tagging the latest commit or an older one, Git gives us flexibility. Let’s see how to tag a specific commit using git tag.

How to create Git tags for specific commits

We might need to tag a commit that isn’t the most recent. In that case, find the commit hash first using: 

git log

Then, create a lightweight tag for it using: 

git tag v1.0 d1e5b1a

We can also create an annotated tag for it using: 

git tag -a v1.0 d1e5b1a -m "First official release"

What if we want to explore the code at a specific tag? That’s where checkout comes in.

How to checkout Git tags

Checking out Git tags enables us to view the state of the repository at that point. Here’s how we can check out a Git tag (v1.0): 

git checkout v1.0

Running this command puts us in a detached HEAD state. This means, we’re no longer on a branch, so any new commits won’t belong to a named branch unless we create one: 

git checkout -b new-feature v1.0

After tagging, it’s important to know how to retrieve all our tags. Let’s learn how to do that next.

How to list Git tags

There are multiple ways to list Git tags.

To list all tags in the repository, run this command: 

git tag

Here is the output: 

v1.0.0 
v1.1.0 
v2.0.0 
...

This is useful for quickly checking which versions exist in our codebase.

Sometimes, we may want to filter tags based on a specific version series or naming convention. Git allows us to do that using the -l flag along with a pattern with git tag: 

git tag -l "v1.*"

This command will list all tags in the repository that start with v1.: 

v1.0.0 
v1.1.0 
V1.2.5 
...

As we continue working, we may need to clean up old or unused tags. Let’s see how it’s done.

How to delete Git tags

Git gives us the power to delete tags both locally and remotely.

To delete a tag named v1.0, run this command: 

git tag -d v1.0

This command removes the tag v1.0 from our local Git environment. The associated commit remains in our history — only the reference (tag) is deleted.

To delete the same tag remotely, run this command: 

git push origin -d tag v1.0

This command instructs Git to remove the v1.0 tag from the origin remote. After doing this, anyone who pulls from the remote will no longer see the deleted tag.

The next step is understanding how to push Git tags to a remote repository.

How to push Git tags

Creating Git tags locally is a great way to mark important commits, but for collaboration, releases, or CI/CD workflows to work properly, those tags need to be pushed to the associated remote repository. Pushing tags makes them accessible to our team and to automated systems that rely on tagged versions of our code.

To push a particular tag to the remote repository, run this command: 

git push origin v1.0

This pushes the tag v1.0 to the origin remote, making it accessible to other developers and automation tools.

To push all the local tags to the remote repository, run this command: 

git push --tags

This command:

  • Pushes all the local tags that are not yet present on the remote
  • Keeps our remote tag list synchronized with our local one

In case we need to roll back to a previous version, reverting to a tag can help. Let’s learn how.

How to revert to a previous Git tag

To revert to a previous Git tag (v1.0) and make it the latest commit on our current branch, we can use this command: 

git reset --hard v1.0

Alternatively, we can create a new branch from the tag: 

git checkout -b rollback v1.0

Next, let’s learn how to update Git tags.

How to update Git tags

Git tags are designed to be immutable references—once created, they’re not meant to change. However, in real-world development, we may find ourselves needing to update, move, or correct a tag that was mistakenly created or pushed too soon. While updating a Git tag is possible, it must be done carefully to avoid breaking CI/CD pipelines or confusing team members.

For example, to update the name of a Git tag from v1.0 to v1.1.0, follow these steps:

Step 1: Delete the tag locally. 

git tag -d v1.0

Step 2: If the tag is already pushed to the remote repository (origin), then delete the tag remotely as well. 

git push origin -d tag v1.0

Step 3: Create the tag again with the updated name locally. 

git tag v1.1.0

Step 4: Push the tag to origin. 

git push origin v1.1.0

Now that we’ve covered tag operations, let’s explore when to use tags in real-world projects.

When to use Git tags

Git tags are ideal for:

  • Marking software release versions (v1.0, v2.1.3)
  • Identifying deployment states
  • Creating release snapshots for rollback
  • Referencing builds in CI/CD pipelines

While tags are helpful, using them wisely ensures long-term project maintainability. Here are some best practices to follow.

Best practices for using Git tags

Apply these best practices to make the most out of Git tags:

  • Follow semantic versioning: Use a structured versioning system like v1.0.0, v2.1.3-beta, or v3.0.0-rc1 for clarity and consistency.
  • Prefer annotated tags for releases: Annotated tags store metadata and messages, making them ideal for official releases and long-term references.
  • Avoid force-pushing tags: Changing existing tags on the remote can break pipelines or confuse collaborators — delete and recreate instead.
  • Delete mistaken tags immediately: If a tag is created in error, remove it locally and remotely as soon as possible to prevent others from using it.

Following these best practices will ensure effective usage of Git tags.

Conclusion

In this guide, we learned what Git tags are, why they matter, and how to create, list, delete, push, and update Git tags. We also identified the ideal scenarios for using them and discussed some best practices for using them efficiently.

Git tags are an essential part of any release strategy. By understanding how to manage them, we can create a more organized, predictable, and collaborative development workflow.

If you want to expand your knowledge of Git, check out the Learn Git & GitHub course on Codecademy.

Frequently asked questions

1. Why use Git tags?

Git tags help identify key moments in a project’s history, especially for marking release versions. They are stable references and ideal for version control and CI/CD processes.

2. What’s the difference between lightweight and annotated Git tags?

  • Lightweight Git tags are simple references with no metadata.
  • Annotated Git tags include the tagger’s name, date, and a message. They’re better suited for releases.

3. Are Git tags commonly used in CI/CD workflows?

Yes, Git tags are widely used to trigger builds, mark deployment-ready code, and trace back to release versions in continuous integration and deployment systems.

4. What happens to commits when a Git tag is deleted?

Deleting a Git tag does not affect the commit it pointed to. The commit remains in the repository’s history. A tag is simply a reference or label — removing it only deletes the label, not the actual content or changes associated with that commit.

5. What’s the difference between a Git branch and a Git tag?

A Git branch is a movable pointer that progresses as new commits are added. It represents an active line of development. A Git tag, in contrast, is a fixed pointer to a specific commit. Tags do not change unless explicitly deleted and recreated, making them ideal for marking static milestones like releases.

Codecademy Team

'The Codecademy Team, composed of experienced educators and tech experts, is dedicated to making tech skills accessible to all. We empower learners worldwide with expert-reviewed content that develops and enhances the technical skills needed to advance and succeed in their careers.'

Meet the full team

Related articles

Learn more on Codecademy

  • Free course

    Learn Git: Introduction

    Learn how to track changes in your code and switch between different versions with Git, an open-source version control system.
    • Beginner Friendly.
      1 hour
  • Free course

    Using Git for DevOps: Using Git Effectively

    Become proficient in Git for DevOps, including repository management, Git commands, GUI, distributed workflows, branching, Git server protocols, and Gitflow.
    • Intermediate.
      1 hour
  • Free course

    Learn Git: Branching and Collaboration

    Learn how to create, merge, clone, and fetch Git branches to collaborate with other developers.
    • Beginner Friendly.
      1 hour
Contents