Git basics – Tagging

tagging

Like other version control systems (VCS), Git can label a commit in the repository’s history as important. Typically, people use this feature to mark release points (V1.0, V2.0, and so on). In this section, you will learn how to list existing tags, how to create and delete new tags, and what the different types of tags are.

List the tag

Listing existing tags in Git is as simple as typing Git tag (with the optional -l option –list) :

$git tag v1.0 v2.0Copy the code

This command lists the labels in alphabetical order, but the order in which they appear is not important.

Create a label

Git supports two types of tags: Lightweight and Annotated.

A lightweight tag is much like a branch that doesn’t change — it’s just a reference to a particular submission.

A tag tag is a complete object stored in a Git database that can be verified and contains the tag tag’s name, email address, date and time, plus a tag information that can be signed and verified using the GNU Privacy Guard (GPG). It is often recommended to create a footnote tag so that you have all of the above information. But if you just want to use a temporary tag, or for some reason don’t want to keep the information, then you can also use lightweight tags.

Note the label

Creating annotation tags in Git is simple. The easiest way to do this is to specify the -a option when you run the tag command:

$git tag -a v1.4 -m "My version 1.4" $git tag v0.1 v1.3 v1.4Copy the code

The -m option specifies a piece of information to be stored in the label. If you don’t specify a message for the annotation tag, Git launches the editor and asks you to enter the information.

You can see the tag information and its corresponding commit information by using the git show command:

$git show v1.4 tag v1.4 tag: Ben Straub <[email protected]> Date: Sat May 3 20:19:12 my 2014-0700 version 1.4 commit ca82a6dff817ec66f44342007202690a93763949 Author: Scott Chacon <[email protected]> Date: Mon Mar 17 21:52:11 2008 -0700 changed the version numberCopy the code

The output displays the tagger’s information, the date and time of the tagging, the footnote information, and then the specific submission information.

Lightweight tag

Another way to label submissions is to use lightweight tags. The lightweight tag essentially stores the submitted checksum in a file — no additional information is saved. To create a lightweight label, do not use the -a, -s, or -m options, just provide the label name:

$git tag v0.1 v1.3 v1.4 v1.4 $git tag v1.5Copy the code

At this point, if you run Git show on a tag, you won’t see additional tag information. The command simply displays the commit information:

$git show v1.4 - lw commit ca82a6dff817ec66f44342007202690a93763949 Author: Scott Chacon < [email protected] > Date: Mon Mar 17 21:52:11 2008 -0700 changed the version numberCopy the code

Post labeling

You can also tag past submissions. Suppose the commit history looks like this:

$ git log --pretty=oneline 15027957951b64cf874c3557a0f3547bd83b3ff6 Merge branch 'experiment' a6b4c97498bd301d84096da251c98a07c7723e65 beginning write support 0d52aaab4479697da7686c15f77a3d64d9165190 one more thing  6d52a271eda8725415634dd79daabbc4d9b6008e Merge branch 'experiment' 0b7434d86859cc7b8c3d5e1dddfed66ff742fcbc added a commit function 4682c3261057305bdd616e23b64b0857d832627b added a todo file 166ae0c4d3f420721acbb115cc33848dfcc2121a started write support 9fceb02d0ae598e95dc970b74767f19372d61af8 updated rakefile 964f16d36dfccde844893cac5b347e7b3d44abbc  commit the todo 8a5cbc430f1a9c3d00faaeffd07798508422908a updated readmeCopy the code

Now, suppose that in V1.2 you forgot to label the project, i.e., “updated RakeFile” is submitted. You can fill in the label later. To label that submission, you need to specify the checksum (or partial checksum) of the submission at the end of the command:

$git tag -a v1.29fceb02Copy the code

You can see that you’ve tagged that submission:

$git tag v0.1 v1.2 v1.3 v1.4 v1.4-lw v1.5 $git show v1.2 tag v1.2: Scott Chacon <[email protected]> Date: 15:32:16 Mon Feb 9, 2009-0800 version 1.2 commit 9 fceb02d0ae598e95dc970b74767f19372d61af8 Author: Magnus Chacon <[email protected]> Date: Sun Apr 27 20:43:35 2008 -0700 updated rakefile ...Copy the code

Shared label

By default, git push does not transfer tags to remote repository servers. After creating the tag you must explicitly push the tag to the shared server. This process is similar to sharing remote branches — you can run Git push Origin

.

$git push origin v1.5 Counting objects: 14, done. Delta compression using up to 8 threads. 100% (12/12), done. Writing objects: 100% (14/14) and 2.05 KiB | 0 bytes/s, done. Total 14 (3) delta, Reused zero (0) delta To [email protected]: schacon/simplegit git * [new tag] v1.5 - > v1.5Copy the code

If you want to push many tags at once, you can also use git push with the –tags option. This will transfer all labels that are not on the remote warehouse server there.

$ git push origin --tags Counting objects: 1, done. Writing objects: 100% (1/1), 160 bytes | 0 bytes/s, done. Total 1 (delta 0), Reused zero (0) delta To [email protected]: schacon/simplegit git * [new tag] v1.4 - > v1.4 * [new tag] v1.4 - lw - > v1.4 - lwCopy the code

Now, when other people clone or pull from the warehouse, they can get your tags, too.

Remove the label

Git tag -d

to delete a tag from your local repository, use git tag -d

. For example, you can use the following command to remove a lightweight label:

$git tag -d v1.4-Lw Deleted tag 'v1.4-LW' (was e7d5add)Copy the code

Git push

:refs/tags/< tagName > Note that the above command does not remove this tag from any remote repository. You must update your remote repository with git push

:refs/tags/

:

The first variant is git push

:refs/tags/

:

$ git push origin :refs/tags/v1.4-lw
To /[email protected]:schacon/simplegit.git
 - [deleted]         v1.4-lw
Copy the code

The idea is to push the empty value before the colon to the remote label name, effectively removing it.

The second, more intuitive way to remove remote tags is:

$ git push origin --delete <tagname>
Copy the code

Check out the tag

Detached HEAD If you want to see what version of a file a tag points to, you can use the git checkout command, although this will leave your repository in a “detached HEAD” state — a state that has some unpleasant side effects:

$git checkout 2.0.0 Note Checking out '2.0.0'. You are in 'detached HEAD' state. You can look around, make experimental changes and commit them, and you can discard any commits you make in this state without impacting any branches by performing another checkout. If  you want to create a new branch to retain commits you create, you may do so (now or later) by using -b with the checkout command again. Example: git checkout -b <new-branch> HEAD is now at 99ada87... Merge pull Request #89 from Schacon/Appendix -final $git checkout 2.0-beta-0.1 Previous HEAD position was 99ada87... Merge pull request #89 from schacon/appendix-final HEAD is now at df3f601... add atlas.json and cover imageCopy the code

In the “split head pointer” state, if you make some changes and commit them, the label will not change, but your new commit will not belong to any branch and will not be accessible except through the exact commit hash. Therefore, if you need to make changes, such as fixing bugs in an older version, then you usually need to create a new branch:

$git checkout -b version2 v2.0.0 Switched to a new branch 'version2'Copy the code

If another commit is made after this, the version2 branch will move forward because of this change, and it will be slightly different from the V2.0.0 tag, so be careful.