<commit_before>---
layout: post
title: tagging
category: beginner
---

Tagging in Git is a great way to denote specific release versions of your code, or perhaps if you need a way to refer to exactly one commit in your history for some reason. This post is going to over the right (and wrong) ways to use @git tag@.

Probably the best way to describe a tag is a post-it note that refers to one commit. It contains a name, so something like @v1.0.0@ or @production@, and a message too if you want. "Git for Computer Scientists":http://eagain.net/articles/git-for-computer-scientists/ visualizes a tag like so:

p=. !http://eagain.net/articles/git-for-computer-scientists/git-storage.6.png!

So, how does one create a tag? Just @git tag v1.0.0@ right? WRONG. You *usually* don't want to do that. In fact, some suggest that this command "does the wrong thing by default":http://www.rockstarprogrammer.org/post/2008/oct/16/git-tag-does-wrong-thing-default/. Without arguments, @git tag@ creates a "lightweight" tag that is "basically a branch that never moves":http://book.git-scm.com/3_git_tag.html. Lightweight tags are still useful though, perhaps for marking a known good (or bad) version, or a bunch of commits you may need to use in the future. Nevertheless, you probably don't want to push these kinds of tags.

Normally, you want to at least pass the @-a@ option to create an unsigned tag, or sign the tag with your GPG key via the @-s@ or @-u <key-id>@ options. Once this has been done you can then use @git describe@ to figure out how many commits you've created since the last tag or the given tag. "Git-fu":http://gitfu.wordpress.com/ has a "great tutorial":http://gitfu.wordpress.com/2008/05/25/git-describe-great-another-way-to-refer-to-commits/ on how to use this command (and it deserves a tip of its own for the future too!).

So let's make a new tag and see how we can refer to it even after commits have been made, then we'll push it to a remote. It's a lot easier than you think.

<pre>
$ git tag -a v1.0.0 -m "Creating the first official version."

$ git show v1.0.0 
  tag v1.0.0
  Tagger: <NAME> <<EMAIL>>
  Date:   Tue Feb 3 20:37:45 2009 -0500

  Creating the first official version.
  commit a8d1b55c5d4bdec843d9942cabf1b678bc1d4eed
  Merge: 00b9675... 1b487b8...
  Author: <NAME> <<EMAIL>>
  Date:   Sun Nov 30 00:41:08 2008 -0500

      Merge branch 'master' of <EMAIL>:qrush/config

$ git describe --tags
  v1.0.0

$ touch test
$ git add test
$ git commit -am "Adding test files"
  Created commit a7aafb8: Adding test files
   0 files changed, 0 insertions(+), 0 deletions(-)
    create mode 100644 test

$ git describe --tags
  v1.0.0-1-ga7aafb8

$ git push --tags
  Counting objects: 40, done.
  Compressing objects: 100% (37/37), done.
  Writing objects: 100% (40/40), 29.32 KiB, done.
  Total 40 (delta 15), reused 9 (delta 2)
  To <EMAIL>:qrush/config.git
   * [new tag]         v1.0.0 -> v1.0.0
</pre>

The second describe command shows us that we're one commit ahead of where the last tag was done. This is an easy way to figure out how much work has been done since the last commit. Also, the @--tags@ option was used to push here, but just the one tag could have been pushed with @git push origin : v1.0.0@. On GitHub (or on your remote) you should see the tag pushed up:

p=. !/images/tag.png!<commit_msg>Remove spurious colon in git push command<commit_after>---
layout: post
title: tagging
category: beginner
---

Tagging in Git is a great way to denote specific release versions of your code, or perhaps if you need a way to refer to exactly one commit in your history for some reason. This post is going to over the right (and wrong) ways to use @git tag@.

Probably the best way to describe a tag is a post-it note that refers to one commit. It contains a name, so something like @v1.0.0@ or @production@, and a message too if you want. "Git for Computer Scientists":http://eagain.net/articles/git-for-computer-scientists/ visualizes a tag like so:

p=. !http://eagain.net/articles/git-for-computer-scientists/git-storage.6.png!

So, how does one create a tag? Just @git tag v1.0.0@ right? WRONG. You *usually* don't want to do that. In fact, some suggest that this command "does the wrong thing by default":http://www.rockstarprogrammer.org/post/2008/oct/16/git-tag-does-wrong-thing-default/. Without arguments, @git tag@ creates a "lightweight" tag that is "basically a branch that never moves":http://book.git-scm.com/3_git_tag.html. Lightweight tags are still useful though, perhaps for marking a known good (or bad) version, or a bunch of commits you may need to use in the future. Nevertheless, you probably don't want to push these kinds of tags.

Normally, you want to at least pass the @-a@ option to create an unsigned tag, or sign the tag with your GPG key via the @-s@ or @-u <key-id>@ options. Once this has been done you can then use @git describe@ to figure out how many commits you've created since the last tag or the given tag. "Git-fu":http://gitfu.wordpress.com/ has a "great tutorial":http://gitfu.wordpress.com/2008/05/25/git-describe-great-another-way-to-refer-to-commits/ on how to use this command (and it deserves a tip of its own for the future too!).

So let's make a new tag and see how we can refer to it even after commits have been made, then we'll push it to a remote. It's a lot easier than you think.

<pre>
$ git tag -a v1.0.0 -m "Creating the first official version."

$ git show v1.0.0 
  tag v1.0.0
  Tagger: <NAME> <<EMAIL>>
  Date:   Tue Feb 3 20:37:45 2009 -0500

  Creating the first official version.
  commit a8d1b55c5d4bdec843d9942cabf1b678bc1d4eed
  Merge: 00b9675... 1b487b8...
  Author: <NAME> <<EMAIL>>
  Date:   Sun Nov 30 00:41:08 2008 -0500

      Merge branch 'master' of git@github.com:qrush/config

$ git describe --tags
  v1.0.0

$ touch test
$ git add test
$ git commit -am "Adding test files"
  Created commit a7aafb8: Adding test files
   0 files changed, 0 insertions(+), 0 deletions(-)
    create mode 100644 test

$ git describe --tags
  v1.0.0-1-ga7aafb8

$ git push --tags
  Counting objects: 40, done.
  Compressing objects: 100% (37/37), done.
  Writing objects: 100% (40/40), 29.32 KiB, done.
  Total 40 (delta 15), reused 9 (delta 2)
  To <EMAIL>:qrush/config.git
   * [new tag]         v1.0.0 -> v1.0.0
</pre>

The second describe command shows us that we're one commit ahead of where the last tag was done. This is an easy way to figure out how much work has been done since the last commit. Also, the @--tags@ option was used to push here, but just the one tag could have been pushed with @git push origin v1.0.0@. On GitHub (or on your remote) you should see the tag pushed up:

p=. !/images/tag.png!
{'fraction_non_alphanumeric': 0.09697601668404589, 'fraction_numerical': 0.043795620437956206, 'mean_word_length': 3.509066487575554, 'pattern_counts': {'":': 10, '<': 24, '<?xml version=': 0, '>': 26, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 1, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5648711', 'n_tokens_mistral': 2351, 'n_tokens_neox': 2103, 'n_words': 1001}