26 Git Basics – Tagging

The source of this book ishosted on GitHub.Patches, suggestions and comments are welcome.

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, youll learn how to list the available tags, how to create new tags, and what the different types of tags are.

Listing the available tags in Git is straightforward. Just typegit tag(with optional-lor–list):

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

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

If you want just the entire list of tags, running the commandgit tagimplicitly assumes you want a listing and provides one; the use of-lor–listin this case is optional.

If, however, youre supplying a wildcard pattern to match tag names, the use of-lor–listis mandatory.

Git supports two types of tags:lightweightandannotated.

A lightweight tag is very much like a branch that doesnt change  its just a pointer to a specific commit.

Annotated tags, however, are stored as full objects in the Git database. Theyre checksummed; contain the tagger name, email, and date; have a tagging message; and can be signed and verified with GNU Privacy Guard (GPG). Its 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 dont want to keep the other information, lightweight tags are available too.

Creating an annotated tag in Git is simple. The easiest way is to specify-awhen you run thetagcommand:

The-mspecifies a tagging message, which is stored with the tag. If you dont 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 thegit showcommand:

$ git show v1.4 tag v1.4 Tagger: Ben Straub Date: Sat May 3 20:19:12 2014 -0700 my version 1.4 commit ca82a6dff817ec66f690a93763949 Author: Scott Chacon Date: Mon Mar 17 21:52:11 2008 -0700 changed the version number

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

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, dont supply any of the-a,-s, or-moptions, just provide a tag name:

This time, if you rungit showon the tag, you dont see the extra tag information. The command just shows the commit:

$ git show v1.4-lw commit ca82a6dff817ec66f690a93763949 Author: Scott Chacon m Date: Mon Mar 17 21:52:11 2008 -0700 changed the version number

You can also tag commits after youve moved past them. Suppose your commit history looks like this:

$ git log –pretty=oneline b64cf874c3557a0f3547bd83b3ff6 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 8a5cbc430f1a9c3d00faaeffd908a 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:

You can see that youve tagged the commit:

$ git tag v0.1 v1.2 v1.3 v1.4 v1.4-lw v1.5 $ git show v1.2 tag v1.2 Tagger: Scott Chacon .com Date: Mon Feb 9 15:32:16 2009 -0800 version 1.2 commit 9fceb02d0ae598e95dc970b74767f19372d61af8 Author: Magnus Chacon .com Date: Sun Apr 27 20:43:35 2008 -0700 updated rakefile …

By default, thegit pushcommand doesnt 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 rungit push origin tagname.

$ git push origin v1.5 Counting objects: 14, done. Delta compression using up to 8 threads. Compressing objects: 100% (12/12), done. Writing objects: 100% (14/14), 2.05 KiB 0 bytes/s, done. Total 14 (delta 3), reused 0 (delta 0) To :schacon/simplegit.git * [new tag] v1.5 – v1.5

If you have a lot of tags that you want to push up at once, you can also use the–tagsoption to thegit pushcommand. This will transfer all of your tags to the remote server that are not already there.

$ git push origin –tags Counting objects: 1, done. Writing objects: 100% (1/1), 160 bytes 0 bytes/s, done. Total 1 (delta 0), reused 0 (delta 0) To :schacon/simplegit.git * [new tag] v1.4 – v1.4 * [new tag] v1.4-lw – v1.4-lw

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

If you want to view the versions of files a tag is pointing to, you can do a git checkout, though this puts your repository in detached HEAD state, which has some ill side effects:

$ git checkout 2.0.0 Note: checking out 2.0.0. You are in detached HEAD state. You can look around, make experimental changes and commit them, and you can discard any commits you make in this state without impacting any branches by performing another checkout. If you want to create a new branch to retain commits you create, you may do so (now or later) by using -b with the checkout command again. Example: git checkout -b new-branch HEAD is now at 99ada87… Merge pull request 89 from schacon/appendix-final $ git checkout 2.0-beta-0.1 Previous HEAD position was 99ada87… Merge pull request 89 from schacon/appendix-final HEAD is now at df3f601… add atlas.json and cover image

In detached HEAD state, if you make changes and then create a commit, the tag will stay the same, but your new commit wont belong to any branch and will be unreachable, except by the exact commit hash. Thus, if you need to make changes  say youre fixing a bug on an older version, for instance  you will generally want to create a branch:

If you do this and make a commit, yourversion2branch will be slightly different than yourv2.0.0tag since it will move forward with your new changes, so do be careful.

Patches, suggestions, and comments are welcome.Git is a member ofSoftware Freedom Conservancy