Git provides the functionality to mark a point in your repository’s history with a “tag”. These tags are typically used to indicate the release of a version. With Git you can create two types of tags: Annotated and Lightweight. These two types differ in how they are stored in the Git repository and the amount of meta data they contain.
Annotated tags are normally what you want when tagging a release. You want this because they have more meta-data attached to them, much like regular commits. They contain a checksum, name, email, date and have a tagging message. Optionally you can sign annotated tags with your GPG key.
Lightweight tags point to a commit in a similar way as branches do. The difference being that a branch points to the next commit as soon as you add a commit. Lightweight tags will keep pointing to the commit that was tagged. Lightweight are useful for private use. You can use them like a bookmark for yourself.
Git comes with a whole set of commands to deal with tags. We’ll go over all the commands you need to manage the tags in your repository.
You can create a Lightweight tag by using the
git tag command and provide a name for the tag. This creates a lightweight tag to the last commit it your currently active branch.
$ git tag lw-bookmark
Creating Annotated tags is similar to creating lightweight tags. You use the same
git tag command but have to add the
-a option. Since annotated tags require a message Git will launch an editor for you to enter one. If you prefer you can also use the
-m option to specify the message directly.
$ git tag -a v0.2-annotated # or $ git tag -a v0.2-annotated -m "Release v0.2"
Both examples tag the current place in time of your Git repository. You can ofcourse also tag previous commits. This can be done by adding the commit hash after the name of the tag.
$ git tag -a v0.1-annotated -m "Release v0.1" 3f18d02
To list the tags we just created we can use the
git tag command without any arguments. This lists all the lightweight and annotated tags in your repository in alphabetical order.
$ git tag lw-bookmark v0.1-annotated v0.2-annotated
This listing tags gets quickly out of hand in a large Git repository. So it might be useful to list tags with a pattern. For example, if you’re only interested in seeing tags for the v0 releases you can run the following command.
$ git tag -l "v0.*" v0.1-annotated v0.2-annotated
Listing the tags doesn’t provide a whole lot of details. It is just a list of what is available in your repository. To show more details of a tag you use the
git show command.
$ git show v0.2-annotated tag v0.2-annotated Tagger: John Developer <firstname.lastname@example.org> Date: Tue Feb 24 20:56:07 2020 +0100 Release v0.2 commit 321f7dde2c3bc5458c030ee6e9ee3825d91514ca (HEAD -> master, tag: v0.2-annotated) Author: John Developer <email@example.com> Date: Tue Feb 24 20:55:36 2020 +0100 Add an awesome feature
As you can see above you can see quite some details of annotated tags. You see details about the tag created and the commit that was tagged. Lightweight tags are a lot less detailed. As you can see below they just show details of the commit that was tagged.
$ git show lw-bookmark commit c773c5822b253b6f483e6c63ba73ec55f61faf8f (tag: lw-bookmark) Author: John Developer <firstname.lastname@example.org> Date: Tue Feb 24 20:51:18 2020 +0100 Tiny bug fix
When you push changes to a remote server Git doesn’t include tags by default. If you want to push your tags you have to do this explicitly. To push a single tag to a remote server you run the command
git push [remote] [tagname].
$ git push origin v0.2-annotated
In case you have multiple tags to push you can use the
--tags option instead. But keep in mind that this will push all your tags, lightweight and annotated.
$ git push origin --tags
Deleting a tag from just your local repository is straight forward. It works the same for annotated and lightweight tags and you do it by running the command
git tag -d [tagname].
See the example below where we delete the lightweight tag that we created before.
$ git tag -d lw-bookmark Deleted tag 'lw-bookmark' (was c773c58)
In case you pushed the tag to a remote server before you can delete by passing the
--delete option to the Git push command.
$ git push --delete origin lw-bookmark