Chapter 10

Version Tagging

Most projects use numbers or names to identify software versions, such as 1.7.3.2 or “gingerbread.” In Git you can use tags.

Creating A Tag

> git tag 1.2.3.4 master -m "Freshly built."

> git push origin 1.2.3.4

Using the --tags option with the push command will also push the tags for the transferred branch.

> git push --tags

If you use GnuPG (Gnu Privacy Guard), you can provide tags with a digital signature by using the -s option. The prerequisite is that you have entered a default email address in Git and the email address must also be a registered user ID in GnuPG.

> git tag 1.2.3.4 master -s -m "Signed."

Attention! If you create a tag with the -m, -a, -s or -u option, Git will create a tag as a separate object in the repository. This object will contain information about the user and the time it was created. Without these options, Git will only create a so-called lightweight tag that only recognizes the commit hash.

Which Tags Are There?

If you call the tag command without parameters, you will see the list of all tags. This can be a long list, and you can use the -l option with a pattern like 1.2.* to reduce the output.

> git tag -l 1.2.*

1.2.0.0      Beginning.
  ...
1.2.3.3      New build.
1.2.3.4      Recently built.

Printing the Tag Hashes

The show-ref command with the --tags option lists the commit hashes of the tag objects. You can use the -dereference option to also print the hash of the commit objects, marked with ^{}.

> git show-ref --dereference --tags

...

f63cd7181787c9973788a97648796468cec474aa refs/tags/1.2.3.3
cef89bbd7121aac3cc38fe3a342045c9401bd6b9 refs/tags/1.2.3.3^{} 
4a0228bdd0ab5e0180422c82bf706c42671a81af refs/tags/1.2.3.4 
cef89bbd7121aac3cc38fe3a342045c9401bd6b9 refs/tags/1.2.3.4^{} 

Adding Tags to the Log Output

Using the --decorate option with the log command prints the tags and branches of each commit.

> git log --oneline --decorate 

cef89bb (HEAD, tag: 1.2.3.4) Again, everything rebuilt. 
9d4caed Merge branch 'Other'.
dcd1c6c Changed.
cce1a68 (tag: 1.2.3.3) Something changed 

In What Version Is It in?

Often the question arises whether a particular feature or bug fix is already included in the version that has been installed by a customer. If the commit is known, the question is easy to answer. The --contains option of the tag command lists all the tags in the history that contains the commit.

> git tag --contains f63cd71

1.2.3.3
1.2.3.4

Attention! The result can be misleading if some commits have been copied. For example, if versions are put together through cherry-picking, it is tricky to figure out whether the change is included. You could log for a particular tag after the commit comment search.

> git log --oneline 1.2.3.3 | grep "a comment." 

However, this only works if you have added comments that identify the changes, either by using a meaningful description or a ticket ID from the bug tracking system. This is another good reason to avoid copying commits.

How to Change A Tag?

It is best not to change it. In Git, a tag is provided as a permanent marker for a version. As long as you have not transferred it with a push to another repository, you can change a tag by recreating it with the --force option. If the tag is already widespread, it can cause confusion if a second variant is circulated.

When Do I Need A Floating Tag?

If you need a movable marker, say for the status, which is currently installed in production, just take a branch.

Summary

• Create a tag: This is done with the tag command.
• Push: The push command only transfers tags that you specify explicitly, for example git push origin 1.2.3.4, unless you use the --tags option.
• Pull and fetch: The pull and fetch commands fetch all the tags from the affected branches automatically, unless you use --no-tags.
• Show all tags: This can be done with git tag -l.
• Show tags in the log: You can use git log --decorate.
• Shared commit in tag: To inquire if a tag contains a commit, use the tag command with the --contains option.
• Floating tags do not exist: In Git tags are permanent markers that you should not alter after they were created. If you need to change a tag, you just take a branch.