Git Notes Tags

You might have noticed by now that Git labels commit snapshots with an unintelligible, lengthy mix of letter and numbers called a SHA-1 hash. Git's answer to human-readable version numbers is to allow commits to be "tagged". Anything can be used for a tag, but Git recommends a symantic versioning. Unfortunately, the symantic tagging system is problematic for the FDS-SMV project because either FDS or SMV might be ready for a maintenance release while the other is not. We therefore use a sequential Git revision index for commit tags (Git-r1, etc.), which we discuss below.

For Git tagging basics read the Pro Git discussion on Git Tags. Below we provide guidance on FDS-SMV-specific tagging operations.

New Tags

A new tag needs to be generated each time a bundle is published. This tag can be referenced later to checkout out the repository for the version of FDS or Smokview that was released. To list the current tags in your repo do

$ git tag
Git
Git-r1
Git-r2

The latest tag is Git-r2 so we need to create a tag named Git-r3. Use the git tag command with -a to create and annotated tag and the -m option to describe the type of bundle being released (FDS-SMV, smokeview, FDS etc).

git tag -a Git-r3 -m "tag for bundle xxx/yyy"

note git webpages say to use single quotes in above command - but this doesn't work. have to use double quotes.

The tag Git-r3 has been created but is only in your local repo. You need to push it up to the GitHub repos.

$ git push origin --tags
$ git push firemodels --tags

Resetting Tags

If you have cloned a fresh repository, you likely will not need to worry about resetting tags. However, if you get your repo onto a state where the tags are out-of-synch with the central repo, https://github.com/firemodels/fds, you will want to follow the example below to get your tags sorted out.

Keep in mind that the example below is dated and so you will probably not see exactly the same outputs from the commands you execute. Also, you may ask, why the repos get out of sync? This can happen if we push a tag for a pre-release for a certain commit, but later we decide to move the commit for release forward. If you have fetched and merged from the central repo in the mean time, you will need to reset your tags.

OK, resetting tags is a pain, but it is well worth it in the long run to stay in sync with the central repo, so bear with me. The problem with tags is that they don't just get pushed and merged and deleted like commits. You could have your own tags in your repo that are different than the tags in the central repo. But, presumably, we would all like to be in sync. So, the best way to do this is for you to delete all your tags and then do a fetch from firemodels/fds and you will get the new tag.

First, why are we doing this? The rationale is that it would be nice to have a revision number very similar to the old SVN revision number. And actually we have figured out how to do this with Git. You get it with git describe and what it gives you is the following, supposing you have a tag "v0" at your very first git commit:

v0-331-gaf9f5f7

Here the "tag" is "v0". The number 331 tells you that the commit (af9f5f7) is 331 commits past the tag v0. The "g" at the front of the hash stands for "git" too. The hash af9f5f7 is an abbreviation for the long SHA-1 has of that commit.

OK, now let's delete the tags that are out of sync. First, we will do your local tags. Cd to your repo and type

$ git tag
GITV1
Git_v0
SMV6.2.4

This will list your current tags. Now delete the ones which are out of sync. If you don't know which are out of sync, it is safe to delete them all, as the correct ones will be pulled from the central repo.

$ git tag -d GITV1
$ git tag -d Git_v0
$ git tag -d SMV6.2.4

Now you need to delete your remote tags (assuming you have forked your repo). First, list them.

$ git ls-remote --tags origin
fe56e8b40c452db31172113a0dba81f40a51c5b9 refs/tags/GITV1
6142ba415d9c366604b98e49e92095ef4783c5e9 refs/tags/GITV1^{}
26f4da7de33498a45e76ec6cc0af44e195fd796e refs/tags/Git_v0
aec04713d4e52c3cba3299e3250bab8bc37012c4 refs/tags/Git_v0^{}
09653c052e9434e5162576a7d665bd57e7fc0f51 refs/tags/SMV6.2.4
ee24231a58e7b7b1aed9457ca87438cc16776c5b refs/tags/SMV6.2.4^{}

I have no idea why you get a ^{} tag as well. But no matter, it goes away when you delete the other one. To delete the remote tags do

$ git push origin :refs/tags/GITV1
$ git push origin :refs/tags/Git_v0
$ git push origin :refs/tags/SMV6.2.4

Now, go ahead and do

$ git remote update

You should see a new tag "Git" get fetched from firemodels.

$ git show Git
tag Git
Tagger: rmcdermo <my email>
Date:   Wed Aug 5 12:04:42 2015 -0400
Initial Git revision, equivalent to SVN 23003

Now you need to push this up to your forked repo.

$ git push --tags origin

And that's it. Let me know if you have problems. Sorry for the hassle.