Creating tags from the command line…

Tags allows us to store a pointer to the repository at a point in time, these are often used for “tagging” a release, but can be used for other purposes.

Note: I will use the tag name v1.0.2 here, obviously this should be replaced with the tagname you’ve used/assigned.

Listing your tags

To see what tags you currently have on a repository run

git tag

this will list all your tags.

Creating your tags

There’s a couple of ways to create your tags, the first is the annotated tag

git tag -a v1.0.2 -m "Version 1.0.2"

Here we use -a (annotate) to create a new tag and -m (add a message). When creating an annotated tag, a message is expected and so you will be prompted to enter a message if you omit -m. Annotated tags store the message (although you could specify an empty message) along with the author of the tag.

Lightweight tags are another way to tag, these tags store no data with the tag (so do not supply -a or -m), for example

git tag v1.0.2

These tags store the commit checksum and whereas you’d tend to use the annotated tag for releases (for example) the lightweight tag might be used simply to label certain commits.

We can also tag by using the commit checksum (the 6a0b83 in the example below), this example uses a lightweight tag

git tag v1.0.2 6a0b83

Pushing your tags

Ofcourse, if we’re working with others we’ll want to share our tags, so if we have a remote to push to then we can push the tag using

git push origin v1.0.2

A simple git push does not push our tags, we need to be explicit or we can use the –tags switch to push all tags.

git push origin --tags

Viewing your tag

We’ve seen that git tag will list the tags but what about showing us the annotation tag data or what the tag actually refers to, this is where we use

git show v1.0.2

If it’s an annotated tag you see the author of the tag and any message along with the last commit within that tag, for the lightweight we simply see the last commit details.

If you’ve signed your tag (see Signing tags below) you’ll also see the GPG signature attached to the tag.

Deleting your tag

To delete a tag just use the following

git tag -d v1.0.2

If you’ve pushed your tag to a remote then use the following after the local delete

git push origin :refs/tags/v1.0.2

Or use

git push origin --delete v1.0.2

Checking out a tag

We can checkout the tag just like any branch using

git checkout v1.0.2

This will put your repository into a “detached HEAD” state. You cannot commit to this tag, or to put it another way, if you commit to this tag your commits will not appear within the tag, instead they’ll only be reachab;e by the commit hash.

If you intention it to make changes to a tag then instead, you need to branch from the tag, i.e.

git checkout -b v1.0.2-branch v1.0.2

Signing tags

Tags can be signed using GPG. The purpose of this functionality is to simply ensure that the tag was created by the person we expected. I’ve not so far needed to sign a tag (or commits for that matter, which can also be signed). However there may be a time when this is useful, so let’s go through it.

To check if you have a key installed type

gpg --list-keys

If no keys exist it’ll create the folders needed for creating keys.

To generate a key key run

gpg --gen-key

This will ask for your “real name” and “email address”, followed by a pass phrase and then this will create your key. Now running gpg –list-keys should list the newly created key.

Next we need to tell git to use our key using the following

git config --global user.signingkey 123456789

where 123456789 is replaced by the pub string associated with your key (see output from gpg –list-keys).

Now we can sign our tags using

git tag -s v1.0.2 -m "Version 1.0.2"

We replace -a with -s, this is now a signed, annotated tag.

We’ll probably want to verify our tag, and we do this using

git tag -v v1.0.2

If you have the public key installed you’ll see information about the key, if not then you’ll get a verification error.