Skip to content

Tag

Jump to bottom
Eric Bouchut edited this page Feb 8, 2021 · 13 revisions

Tag

A git tag is kind of a bookmark that references a specific commit. A good rule of thumb is not to use the same name for a tag and a branch.

List Local Tags

This list the tags available locally.

git tag -l

1.8.2.1
1.8.2.10
1.8.2.11
1.8.2.12
1.8.2.2

List Local Tags ordered by name (and version number)

List existing tags sorted by name but this time takes into account version numbers for the sort. For instance 1.8.2.2 is before 1.8.2.10.

git tag -l | sort -V

1.8.2.1
1.8.2.2
1.8.2.10
1.8.2.11
1.8.2.12

ℹ️ This is so useful that I created the handy git alias git tags for this:

git config --global alias.tags '!git tag -l | sort -V'

List Remote Tags

Here is how to list the tags available on the remote origin.

git ls-remote --tags origin

04ca0b7cb8681dddd7948e12c93cad29e171e4c1        refs/tags/1.2.0
f8f8719f39db720b40b2274c393306e4027d6c1f        refs/tags/1.2.0^{}
743511e577466368fafe874f2375b8e4c4aab087        refs/tags/1.2.1
b3ea6f6bee3c530479a67e04b62859d866263a71        refs/tags/1.2.1^{}
6d47c806039ca54c9a37c324e4a6b826e241153d        refs/tags/1.3.0
00432c2fa059b24fdbf30b59fd4304a161ffb4d5        refs/tags/1.3.0^{}

ℹ️ Here is a handy global git alias to list remote tags.

git config --global alias.tags-remote '!git ls-remote --tags origin | grep -v "\^{}"'

Once defined you can use it in whatever git repository of your local machine while logged in with the same user, like so:

git tags-remote | grep '1\.01\.16-RC1'

072ee8aac0894283e311ac740f31284cb7e796df        refs/tags/1.10.16-RC1

List all the tags containing a commit

The below command searches for and list the name of the tags containing the commit with SHA-1 123456:

git tag --contains 123456

List the tags on this commit (if any) and all its descendants. The list can be quite long for a repository with a big history.

List the tag nearest to a commit

List the name of the tag either associated with the commit with the SHA-1 123456 or any of its descendants (more recent commits).

git describe --tags --contains 123456
    my_tag~1

The tag v1.0 is on the child commit of 123456. This what the ~1 after the tag stands for.

What is the most recent tag?

git fetch
git describe --tags --abbrev=0

⚠️ Only displays the most recent local tag accessible through HEAD (the tip of the current branch).

ℹ️ If you do this quite frequently, you may benefit from creating the lasttag alias, like this.

git config --global alias.lasttag "describe --tags --abbrev=0"

From now on, you can use git lasttag to get the same result.

To get the name of the most recent tag reachable from a branch that is not the current one, simply append the name of the branch to the lasttag sub command, like so:

# Assuming we are not on the branch master
git fetch
git lasttag master

Previous tag

What is the remote tag before the latest one that is reachable from the current branch or HEAD if in detached-head (ie. you checked out a specific commit and are not on a branch).

ℹ️ Create a global git alias named previous-tag like so.

git config --global alias.previous-tag '!git describe --abbrev=0 --tags \'$(git rev-list --tags --skip=1 --max-count=1) \\' '

You can then use it in whatever git repository on this machine while logged in as your user, like so:

git previous-tag
1.10.5

Show the tag message

List the tags along with the associated message (the first 99 lines)

git tag -ln99

Create a tag

Here is how to create a tag named inception to make it reference the commit with the SHA1 1337. Depending on whether or not you want to track who created it use the -a option.

  • Create a anonymous tags (no way to know who created it and when), aka. lightweight tag
git tag  inception 1337
  • Create an annotated tag A tag created with the -a option will remember who created it (name, e-mail) and when (creation date).
git tag -a inception 1337

If you want to add a description when creating a tag use the -m option like so.

git tag  -m "The very beginning..." inception 1337

When using the -a option, the tag contains the creation date, creator name and e-mail.

Local tags are not pushed by default to remote repositories when doing git push.

Difference between a lightweight/anonymous and a annotated tag

TODO

Delete a local tag

Here is how to remove the local tag inception. Make sure you also remove the local tag with the same name.

git tag -d inception

Make sure this tag has not been pushed to any remote repository, or else you instead need to do either:

  • create a new tag instead of removing the existing one
git tag -a -m "The correct inception tag."  inception2
  • remove the tag inception (if you really want to go this route) and notify anyone working with the remote that they need to delete the inceptiontag before fetching the new one like so:
# See: man git-tag  # section "DISCUSSION"
git tag -d inception
get fetch origin  tag inception

Delete a remote tag

Here is how to remove the tag inception from the remote origin.

git push --delete origin inception

If the above does not work because the version of git does not support it, use instead:

git push origin :inception

This basically says push noting (on the left side of the colon sign :) to the remote tag named inception (on the right side of the colon sign (: ), in other words, remove it.

If there is a branch with the same name as a tag, this command will fail. Then we need to tell git to remove the tag not the branch like so:

git push origin --delete tags/inception

Push a tag to a remote

Here is how to push the local tag named inception to the remote origin.

git push origin inception

If the tag and a branch have the same name the command will fail with this error git push fails with error: src refspec inception matches more than one.. In this case, you need to be explicit and tell git that you want to push the tag:

git push origin  tag  inception

Push all tags to a remote

Here is how to push all local tags to the remote  origin.

git push --tags origin

Push both commits and tags to a remote

From git 1.8.3 onwards, you can use the option --follow-tags to push both a branch/ref and only the annotated tags reachable from this ref.

git push --follow-tags  origin  my_branch

This pushes to the remote origin both:

  • the branch my_branch
  • only the annotated tags reachable from my_branch and present in .git/refs/tags (which is no longer the case after launching git gc which moves them to .git/packed-refs).

In order to make this a default every time you push to a remote, without having to specify the option --follow-tags, set the global git configuration option push.followTags to true, like so:

git config --global push.followTags true

Source: http://stackoverflow.com/a/26438076/386517

Show the Content of a File on a Tag

To view the content of the file CHANGELOG.md present in the tag named 1.0:

git show 1.0:CHANGELOG.md

Please note:

  • the presence of a colon (:) in between the tag name and the file path
  • the file path is relative to this project's root directory, that is to view the file src/main/resources/config.properties do not use a full path but a path relative to this project's directory.
Clone this wiki locally