If you are releasing software with Git, you are bound to deal with tags as the tag describes the different software releases in the repository. There are two types of tags, a lightweight tag and an annotated tag. The lightweight tag is very similar to a branch, since it is just a named reference like refs/tags/version123, which points to the commit hash of the commit you are tagging; whereas if it were a branch, it would be refs/heads/version123. The difference is the branch moves forward when you work and commit to it. The tag should always point to the same commit hash.
Before we start, you must go to the chapter5 directory, where we made the original clone for this chapter.
We should start by tagging the commit that is ten commits behind origin/stable-2.3 and is not a merge. In order to find that commit, we will use the git log command.
For the git log command, we are using the --no-merges option, which will show commits that only have one parent. The --oneline option we have used before tells Git to limit the output to one line per commit.
Find the commit as follows:
$ git log -11 --no-merges --oneline origin/stable-2.3 49ec6c1 Prepare 2.3.2-SNAPSHOT builds 63dcece JGit v2.3.1.201302201838-r 3b41fcb Accept Change-Id even if footer contains not well-formed entries 5d7b722 Fix false positives in hashing used by PathFilterGroup 9a5f4b4 Prepare post 2.3.0.201302130906 builds 19d6cad JGit v2.3.0.201302130906 3f8ac55 Replace explicit version by property where possible 1c4ee41 Add better documentation to DirCacheCheckout e9cf705 Prepare post 2.3rc1 builds ea060dd JGit v2.3.0.201302060400-rc1 60d538f Add getConflictingNames to RefDatabase
Now that we have found the 60d538f commit, we should make it a lightweight tag:
- Use the
git tagcommand to give a meaningful release name:$ git tag 'v2.3.0.201302061315rc1' ea060dd - Since there is no output, it is a success; to see whether the tag is available, use the
git tagcommand:$ git tag -l "v2.3.0.2*" v2.3.0.201302061315rc1 v2.3.0.201302130906
- We are using the
git tagcommand with-las a flag, since we want to list the tags and not tag the currentHEAD. Some repositories have a lot of tags, so to prevent the list from being too long, you can specify which tags you want to list and use a*wildcard as I have used. Our tag is available, but all it really says is that we have a tag in the repository with the namev2.3.0.201302061315rc1, and if you are usinggit show v2.3.0.201302061315rc1, you will see that the output is the same asgit show ea060dd:$ git show v2.3.0.201302061315rc1 commit ea060dd8e74ab588ca55a4fb3ff15dd17343aa88 Author: Matthias Sohn <[email protected]> Date: Wed Feb 6 13:15:01 2013 +0100 JGit v2.3.0.201302060400-rc1 Change-Id: Id1f1d174375f7399cee4c2eb23368d4dbb4c384a Signed-off-by: Matthias Sohn <[email protected]> diff --git a/org.eclipse.jgit.ant.test/META-INF/MANIFEST.MF b/org.eclipse.jgit.a $ git show ea060dd commit ea060dd8e74ab588ca55a4fb3ff15dd17343aa88 Author: Matthias Sohn <[email protected]> Date: Wed Feb 6 13:15:01 2013 +0100 JGit v2.3.0.201302060400-rc1 Change-Id: Id1f1d174375f7399cee4c2eb23368d4dbb4c384a Signed-off-by: Matthias Sohn <[email protected]> diff --git a/org.eclipse.jgit.ant.test/META-INF/MANIFEST.MF b/org.eclipse.jgit.a
- There will also be a lot of file diff information in the output but it is exactly the same output. So, in order to add more information, we should use an annotated tag. An annotated tag is a tag where you have to add some information to the tag. To create an annotated tag, we use the
--annotatetag for thegit tagcommand:git tag --annotate -m "Release Maturity rate 97%" 'v2.3.0.201409022257rc2' 1c4ee41 - The
-mflag is the same as--message, as I wanted to give the tag a message. If you leave out the-mflag, Git will open the configured editor and you can write a full release note into the annotation of the tag. We can check the tag information withgit show:$ git show 'v2.3.0.201409022257rc2' tag v2.3.0.201409022257rc2 Tagger: Rasmus Voss <[email protected]> Date: Sun Feb 9 22:58:28 2014 +0100 Release Maturity rate 97% commit 1c4ee41dc093266c19d4452879afe5c0f7f387f4 Author: Christian Halstrick [email protected]
- We can actually see the tag name and information we added with the
-mflag. With the lightweight tag, we don't see anything about the tag from the output. We actually don't even see the tag name when using Git show on a lightweight tag.
Tags are very powerful as they can add valuable information to the repository, and since tags should be considered official releases in the repository, we should be very careful with them.
Naturally, you can push the tags to a remote area, and contributors to the repository would fetch those tags. This is where you have to be careful. With a legacy version control system, you can go back in time and just change the release, and since these legacy systems are all based on a centralized server where you have to be connected in order to work, changing a release is not that bad, since not so many people use the release or have even downloaded the release. But it is different in Git. If you change a tag that you have already pushed to point to another commit hash, then those developers who have already fetched the tag will not get the new tag unless the delete the tag locally.
- To prove the dangers of not getting new tag, we will try to delete a tag and recreate it to point to another commit hash:
$ git tag -d v1.3.0.201202121842-rc4 Deleted tag 'v1.3.0.201202121842-rc4' (was d1e8804)
- Now that we have deleted the tag, we are ready to recreate the tag again to point to
HEAD:$ git tag -a -m "Local created tag" v1.3.0.201202121842-rc4 - We have recreated the tag and it points to
HEADbecause we did not specify a commit hash at the end of the command. Now, executegit fetchto see whether you can get the tag overwritten from the remote repository:$ git fetch - Since there is no output, the tag was probably not overwritten. Let us verify with
git show:$ git show v1.3.0.201202121842-rc4 tag v1.3.0.201202121842-rc4 Tagger: Rasmus Voss <[email protected]> Date: Sun Feb 9 23:17:18 2014 +0100 Local created tag commit 1c4ee41dc093266c19d4452879afe5c0f7f387f4
- As you can see from the output, it is still our locally created tag. To get the tag from the remote again, we need to delete the local tag and do a Git fetch. To delete a tag, you need to apply the
-dflag:$ git tag -d v1.3.0.201202121842-rc4 Deleted tag 'v1.3.0.201202121842-rc4' (was 28be24b) $ git fetch From https://git.eclipse.org/r/jgit/jgit * [new tag] v1.3.0.201202121842-rc4 -> v1.3.0.201202121842-rc4
- As you can see, Git has fetched the tag from the server again. We can verify with
git show:$ git show v1.3.0.201202121842-rc4 tag v1.3.0.201202121842-rc4 Tagger: Matthias Sohn <[email protected]> Date: Mon Feb 13 00:57:56 2012 +0100 JGit 1.3.0.201202121842-rc4 -----BEGIN PGP SIGNATURE----- Version: GnuPG/MacGPG2 v2.0.14 (Darwin) iF4EABEIAAYFAk84UhMACgkQWwXM3hQMKHbwewD/VD62MWCVfLCYUIEz20C4Iywx 4OOl5TedaLFwIOS55HcA/ipDh6NWFvJdWK3Enm2krjegUNmd9zXT+0pNjtlJ+Pyi =LRoe -----END PGP SIGNATURE----- commit 53917539f822afa12caaa55db8f57c29570532f3
- So, as you can see, we have the correct tag again, but it should also be a warning that once you push a tag to a remote repository, you should never change it, since the developers who are fetching from the repository may never know unless they clone again or delete the tags locally and fetch them again.
In this chapter, we learned how you can tag your commits and add notes to them. This is a powerful method to store additional information after the commit has been committed and published to a shared repository. But before you actually publish your commit, you have the chance to add the most valuable information for a commit. The commit message is where you must specify what you are doing and sometimes why you are doing it.
If you are solving a bug, you should list the bug ID; if you are using a special method to solve the problem, it is recommended that you describe why you have used this awesome technique to solve the problem. So when people look back on your commits, they can also learn a few things on why different decisions were made.