2.6 Git Basics - Tagging

Tagging

Like most VCSs, Git has the ability to tag specific points in history as being important.
Typically people use this functionality to mark release points (v1.0, and so on).
In this section, you’ll learn how to list the available tags, how to create new tags, and what the different types of tags are.

Listing Your Tags

Listing the available tags in Git is straightforward.
Just type git tag:

$ git tag
v0.1
v1.3

This command lists the tags in alphabetical order; the order in which they appear has no real importance.

You can also search for tags with a particular pattern.
The Git source repo, for instance, contains more than 500 tags.
If you’re only interested in looking at the 1.8.5 series, you can run this:

Creating Tags

Git uses two main types of tags: lightweight and annotated.

A lightweight tag is very much like a branch that doesn’t change – it’s just a pointer to a specific commit.

Annotated tags, however, are stored as full objects in the Git database.
They’re checksummed; contain the tagger name, e-mail, and date; have a tagging message; and can be signed and verified with GNU Privacy Guard (GPG).
It’s generally recommended that you create annotated tags so you can have all this information; but if you want a temporary tag or for some reason don’t want to keep the other information, lightweight tags are available too.

Annotated Tags

Creating an annotated tag in Git is simple.
The easiest way is to specify -a when you run the tag command:

$ git tag -a v1.4 -m 'my version 1.4'
$ git tag
v0.1
v1.3
v1.4

The -m specifies a tagging message, which is stored with the tag.
If you don’t specify a message for an annotated tag, Git launches your editor so you can type it in.

You can see the tag data along with the commit that was tagged by using the git show command:

That shows the tagger information, the date the commit was tagged, and the annotation message before showing the commit information.

Lightweight Tags

Another way to tag commits is with a lightweight tag.
This is basically the commit checksum stored in a file – no other information is kept.
To create a lightweight tag, don’t supply the -a, -s, or -m option:

$ git tag v1.4-lw
$ git tag
v0.1
v1.3
v1.4
v1.4-lw
v1.5

This time, if you run git show on the tag, you don’t see the extra tag information.
The command just shows the commit:

Now, suppose you forgot to tag the project at v1.2, which was at the “updated rakefile” commit.
You can add it after the fact.
To tag that commit, you specify the commit checksum (or part of it) at the end of the command:

Sharing Tags

By default, the git push command doesn’t transfer tags to remote servers.
You will have to explicitly push tags to a shared server after you have created them.
This process is just like sharing remote branches – you can run git push origin [tagname].

If you have a lot of tags that you want to push up at once, you can also use the --tags option to the git push command.
This will transfer all of your tags to the remote server that are not already there.

Now, when someone else clones or pulls from your repository, they will get all your tags as well.

Checking out Tags

You can’t really check out a tag in Git, since they can’t be moved around.
If you want to put a version of your repository in your working directory that looks like a specific tag, you can create a new branch at a specific tag:

$ git checkout -b version2 v2.0.0
Switched to a new branch 'version2'

Of course if you do this and do a commit, your version2 branch will be slightly different than your v2.0.0 tag since it will move forward with your new changes, so do be careful.