2. Git Basics
7. Git Tools
10. Git Internals
A3. Git Commands
2.6 Git Basics - 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.
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:
$git tag -l
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.
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
$git tag v1.4-lw
$git show v1.4-lw
Author: Scott Chacon <email@example.com>
Date: Mon Mar 17 21:52:11 2008 -0700
changed the version number
You can also tag commits after you’ve moved past them. Suppose your commit history looks like this:
$git log --pretty
15027957951b64cf874c3557a0f3547bd83b3ff6 Merge branch 'experiment'
a6b4c97498bd301d84096da251c98a07c7723e65 beginning write support
0d52aaab4479697da7686c15f77a3d64d9165190 one more thing
6d52a271eda8725415634dd79daabbc4d9b6008e Merge branch 'experiment'
0b7434d86859cc7b8c3d5e1dddfed66ff742fcbc added a commit function
4682c3261057305bdd616e23b64b0857d832627b added a todo file
166ae0c4d3f420721acbb115cc33848dfcc2121a started write support
9fceb02d0ae598e95dc970b74767f19372d61af8 updated rakefile
964f16d36dfccde844893cac5b347e7b3d44abbc commit the todo
8a5cbc430f1a9c3d00faaeffd07798508422908a updated readme
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:
$git tag -a v1.2 9fceb02
$git show v1.2
Tagger: Scott Chacon <firstname.lastname@example.org>
Date: Mon Feb 9 15:32:16 2009 -0800
Author: Magnus Chacon <email@example.com>
Date: Sun Apr 27 20:43:35 2008 -0700
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.