Is there a standard naming convention for git tags? [closed]

Question

I've seen a lot of projects using v1.2.3 as the naming convention for tags in git. I've also seen some use 1.2.3. Is there an officially endorsed style, or are there any good arguments for using either?

Transgression

With 43 upvotes and counting, I am wondering if this very valuable question could be reworded and reopened, with some answer integrating all the points in a nice summary and being at the top? @PeterEisentraut's seems to be the most complete; whereas the accepted answer ATM seems a bit misleading. (I think I will be using v1.2.3 for tags myself, after reading all the points.) – Misuse

SO is for fixing code. Best practices appear to belong on softwareengineering.stackexchange.com or codereview.stackexchange.com – Febrifugal

Take a peek at semver.org (semantic versioning), that should give you some ideas. – Pannikin

my experience tells me to use a slightly different scheme. 1. subdirectory: a Git tag should at least start with v/as this groups tags in a namespace. 2. ideally, a tag should also contain an acronym that uniquely identifies the app. e.g. v/myapp/1.0. This makes git repository merging easier: in case apps would be merged, tags will not collide in the tag namespace. – Disciplinarian

There is another subtle reason to prefer and promtoe a v prefix in tags: this forces the version to be recognized always as a string by tools, libraries and languages that may otherwise treat 1.10 as a float number and consider it as being really 1.1 which is completely off version-wise. At scale a v prefix has proved for me to be a good way to avoid version "mojibake"-like damages. Then tools that really need the true version can easily strip the leading v. – Alwitt

Answering is blocked. But no answer have important information: You must avoid the characters '~', '^', ':', '\', '?', '[', and '*', and the sequences ".." and "@{" which have special meaning to revparse. Also it must not contain whiteSpaces. This is correct validation of tag name. I'm not sure that this is full validation, but... at least this is some basic information about the topic. – Teutonic

Answer 1

Version 1.0.0 of Semantic Versioning, by Tom Preston-Werner of GitHub fame, had a sub-specification addressing this:

Tagging Specification (SemVerTag)

This sub-specification SHOULD be used if you use a version control system (Git, Mercurial, SVN, etc) to store your code. Using this system allows automated tools to inspect your package and determine SemVer compliance and released versions.

1. When tagging releases in a version control system, the tag for a version MUST be "vX.Y.Z" e.g. "v3.1.0".

However, after discussion this was removed, and is no longer present in the latest version of the SemVer spec (2.0.0 at the time of writing). A later discussion thread in the same place went into greater depth, and resulted in a new Is "v1.2.3" a semantic version? being added to the FAQ in SemVer's master branch, although at the time of writing (over 2 years later) this change is still not present in the officially released spec.

Aceae

Thanks - That's very close. I wish he would have qualified why the v should be there though. – Transgression

I see someone else had the same thought: github.com/mojombo/semver.org/issues/unreads#issue/1 – Transgression

@Transgression @mojombo == Tom Preston-Werner – Aceae

Updated link: github.com/mojombo/semver.org/issues/1 – Vitebsk

Semantic Versioning 1.0.0 uses format "v1.2.3". Semantic Versioning 2.0.0-rc.1 probably uses format "1.2.3". Tagging Specification (SemVerTag) article was removed from specs. More here: semver.org – Salome

This answer is done when existed old semver (version 1.0). Nowadays the prefix 'v' removed from semver v2.0. For details see post below. – Highup

sbt-release plugin for scala automatically tags code using the v.X.Y.Z convention. See: github.com/sbt/sbt-release#release-process "Tag the previous commit with v$version (eg. v1.2, v1.2.3)." – Dignity

I've just updated the answer to the current state of the SemVer project. – Benzophenone

semver.org/#is-v123-a-semantic-version – Evermore

Answer 2

There appear to be two dominating conventions (assuming you also abide by some reasonable standard for numbering the releases themselves):

• v1.2.3
• 1.2.3

The advantages of v1.2.3 are that the Git documentation (and also the Mercurial documentation) uses that format in its examples, and that several "authorities" such as the Linux kernel and Git itself use it. (The mentioned Semantic Versioning used to use it but doesn't any more.)

The advantages of 1.2.3 are that gitweb or GitHub can automatically offer a tarball or zip download of the form packagename-$tag.tar.gz (and I think it's quite established that a tarball should not be named package-v1.2.3.tar.gz). Alternatively, you can use git describe directly to generate tarball version numbers. For lightweight projects without a formal release process, these possibilities can be quite convenient. It should also be noted that Semantic Versioning is by no means the only or a universally accepted standard for version numbering. And notable projects such as GNOME as well as countless other projects do use the 1.2.3 tag naming.

I think it's probably too late to consolidate these positions. As always, be consistent and make sense.

---

Update: As mentioned in this comment, GitHub now offers a tarball name with the 'v' stripped off of the tag.

Coroneted

Regarding GitHub and tarball generation: it is not relevant anymore. They strip the 'v' off of the tag. – Weatherbeaten

Prefixing 'v' is also quite useful when sorting tags in alphabetical order. Other tags may also exist; whether officially in a master repository or to track a developer's work locally. With 'v' prefixes the release tags form their own group, instead of being scattered all over the rest of the namespace. – Prae

Updated the answer to reflect that SemVer no longer uses v. – Benzophenone

Answer 3

The reason for the preceding 'v' is historical. Older SCCS (cvs,rcs) could not distinguish between a tag identifier and a revision number. Tag identifiers were restricted to not begin with a numeric value so that revision numbers could be detected.

Sungkiang

+1: Good first answer and a name from one of my favourite books :-) Perhaps your next answer will be on a more current question, though. – Nodical

... but if this is only true for older SVCS, what if the point of this answer for a question about modern Git? – Tenancy

this is still useful in git, so you can easily distinguish version tags, from other type of tags (tags are useful for many other things) – Salt

Answer 4

Not that I know of.
But Git will not allow a tag and a branch of the same name at the same time, so if you have a branch "1.1" for 1.1 works, do not put a tag "1.1", use for instance "v1.1"

Elainaelaine

Use for branches 1.1.x. That's it. – Highup

Answer 5

I don't know of any standards. I simply choose my tag names such that I can stick a

VERSION = `git describe --tags`

in my build scripts. So, the tag naming convention actually depends on the version naming convention of the project.

Ingold

Answer 6

New package managers advice to tag versions without prefix v (like composer for PHP projects). SemVer 2.0 has nothing about tag specification. It's done intentionally due avoiding conflicts. However it's advised to add prefix v in documentation and text references. As example format v1.0.4 instead of full version 1.0.4 or ver. 1.0.4 is enough verbose and elegant in documentation.

Highup

“it's advised to …” Advised by who, and where can we see that advice in its original context? – Stile

@Stile Look how packagist or maven central parses the git repose. Preferable way is numbers only, however with v1.xx 'v' gets stripped off. I believe there are many more including debian/ubuntu. Packagist had article that they prever number tag in git and 'v' prefixed in documentation, however I can't find it now. – Highup

“Packagist had article that they prever number tag in git and 'v' prefixed in documentation […]” — So that's a preference for those projects; not advice anyone need pay much attention, it seems. – Stile

Answer 7

We use branches and tags for release-specific work followed by the actual release, respectively:

o---o-----o---o---o--- ...   master
     \   /       /
      \ /       /
       o-------o--- ...      1.6 branch

Every developer makes a mental decision about whether the work they're about to commit is applicable just to master or if it's also relevant to the branch. You can see that changes that are made to the branch are merged back on master, but some changes on master will never go on the branch (that is, those not intended for the 1.6 release, in this example).

When we're ready to release, we tag it and then merge back one last time, and we name the tag with the same name as the branch, but with an extra identifier about what particular version it is, e.g. "1.6-release" or "1.6-beta" or "1.6-rc2", et cetera.

... ------o---o---o--o---o--- ...   master
         /       /
        /       /
... ---o------(*)--- ...      1.6 branch
          1.6-release

Free

Thanks - that's a good answer for describing how you do branching, but I actually just meant if there were some specific (technical) reason for using a certain naming scheme in git. Still giving you an upvote for the nice diagrams though ;) – Transgression

Ah, gotcha! Sorry for misunderstanding your question. No, there's no specific technical reason for using a particular name, other than human communication. You can name your branches and tags pretty much whatever you like. – Free

Your release-1.6 branch is named "1.6 branch"? I thought spaces weren't supported in branch names. – Febrifugal

Answer 8

There is no one best practice I'm aware of. Here are some links:

• http://web.elctech.com/?p=79
• http://reinh.com/blog/2009/03/02/a-git-workflow-for-agile-teams.html#production-tagging

Generally, versioning (0.0.1, v0.2.1, ...) maybe hand in hand with some issue-tracking could be considered a plausible approach. (.. although I usually use v-prefixed tag names .. see also @VonC answer)

Officiant