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:
git tag
command to give a meaningful release name:$ git tag 'v2.3.0.201302061315rc1' ea060dd
git tag
command:$ git tag -l "v2.3.0.2*" v2.3.0.201302061315rc1 v2.3.0.201302130906
git tag
command with -l
as a flag, since we want to list the tags and not tag the current HEAD
. 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 name v2.3.0.201302061315rc1
, and if you are using git show v2.3.0.201302061315rc1
, you will see that the output is the same as git 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
--annotate
tag for the git tag
command:git tag --annotate -m "Release Maturity rate 97%" 'v2.3.0.201409022257rc2' 1c4ee41
-m
flag is the same as --message
, as I wanted to give the tag a message. If you leave out the -m
flag, 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 with git 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]
-m
flag. 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.
$ git tag -d v1.3.0.201202121842-rc4 Deleted tag 'v1.3.0.201202121842-rc4' (was d1e8804)
HEAD
:$ git tag -a -m "Local created tag" v1.3.0.201202121842-rc4
HEAD
because we did not specify a commit hash at the end of the command. Now, execute git fetch
to see whether you can get the tag overwritten from the remote repository:$ git fetch
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
-d
flag:$ 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
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
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.