Git Advanced · Tags

Preface#

Continuing from the previous post, let’s look at commits from a different angle.

Tag Management#

When releasing a version, we usually create a tag in the repository. This uniquely identifies the version at the moment the tag is created. In the future, whenever you checkout a tag, you’re retrieving the historical version from that moment. So a tag is also a snapshot of the repository. Although it’s a “snapshot”, Git tags are essentially pointers to a commit (sounds like branches, right? But branches can move, tags usually don’t). That’s why creating and deleting tags is instantaneous.

Git already has commits—why introduce tags? Consider this scenario: “Please package and publish last Monday’s version; the commit id is 6a5819e....” A long random string is hard to find.

If you say instead: “Please package and publish last Monday’s version; the version is v1.2.” Then it’s easy: “OK, just find the commit by tag v1.2.”

So a tag is a meaningful name that is easy to remember, bound to a specific commit. In other words, it’s a human-friendly alias for a commit id.

Create Tags#

Tagging in Git is very simple. First, switch to the branch you want to tag:

$ git branch
* dev
	master
$ git checkout master
Switched to branch 'master'

Then run git tag <name> to create a new tag:

$ git tag v1.0

Use git tag to list all tags:

$ git tag
v1.0

By default, tags are created on the latest commit. If you forget to tag—say it’s already Friday, but you should have tagged on Monday—then find the commit id in history and tag it:

$ git log --pretty=oneline --abbrev-commit
12a631b (HEAD -> master, tag: v1.0, origin/master) merged bug fix 101
4c805e2 fix bug 101
e1e9c68 merge with no-ff
f52c633 add merge
cf810e4 conflict fixed
5dc6824 & simple
14096d0 AND simple
b17d20e branch test
d46f35e remove test.txt
b84166e add test.txt
519219b git tracks changes
e43a48b understand how stage works
1094adb append GPL
e475afc add distributed
eaadf4e wrote a readme file

For example, if you want to tag the commit add merge, its commit id is f52c633. Run:

$ git tag v0.9 f52c633

Now if you list tags again, you’ll see v0.9 and v1.0. Note: tags are sorted alphabetically, not by time. Use git show <tagname> to see tag information:

$ git show v0.9
commit f52c63349bc3c1593499807e5c8e972b82c8f286 (tag: v0.9)
Author: Michael Liao <askxuefeng@gmail.com>
Date:   Fri May 18 21:56:54 2018 +0800

		add merge

diff --git a/readme.txt b/readme.txt
...

You can also create annotated tags, using -a for the tag name and -m for the message:

$ git tag -a v0.1 -m "version 0.1 released" 1094adb

Now git show <tagname> will display the message:

$ git show v0.1
tag v0.1
Tagger: Michael Liao <askxuefeng@gmail.com>
Date:   Fri May 18 22:48:43 2018 +0800

version 0.1 released

commit 1094adb7b9b3807259d8cb349e7df1d4d6477073 (tag: v0.1)
Author: Michael Liao <askxuefeng@gmail.com>
Date:   Fri May 18 21:06:15 2018 +0800

		append GPL

diff --git a/readme.txt b/readme.txt
...

Operate on Tags#

If you created a tag by mistake, you can delete it:

$ git tag -d v0.1    # `git tag -d <tagname>` deletes a local tag
Deleted tag 'v0.1' (was f15b0dd)

Tags are created locally and won’t be pushed automatically. So it’s safe to delete wrong tags locally. To push a tag to the remote, use git push origin <tagname>:

$ git push origin v1.0   # `git push origin <tagname>` pushes a local tag
Total 0 (delta 0), reused 0 (delta 0)
To github.com:michaelliao/learngit.git
 * [new tag]         v1.0 -> v1.0

Or push all local tags that haven’t been pushed:

$ git push origin --tags      # `git push origin --tags` pushes all unpushed local tags
Total 0 (delta 0), reused 0 (delta 0)
To github.com:michaelliao/learngit.git
 * [new tag]         v0.9 -> v0.9

If a tag has already been pushed to the remote, deleting it is a bit more involved. First delete it locally:

$ git tag -d v0.9   # delete local tag
Deleted tag 'v0.9' (was f52c633)

Then delete it from the remote. The deletion is also done via push, in this format:

$ git push origin :refs/tags/v0.9    # `git push origin :refs/tags/<tagname>` deletes a remote tag
To github.com:michaelliao/learngit.git
 - [deleted]         v0.9

To verify the tag is removed from the remote, you can log into GitHub and check.