Using Git describe without tags

Question

I have a repository that gives me only a hash when I run git describe. I did not know until today that it does this because of the --always option (which is what I was using) since that repository has no tags. I have another repository with lots of tags.

How can I use git describe to exclude tags and just give me a hash? I want to have all of the other functionality of git describe in case I need to use the other features, such as dirty marking; I just want to exclude tags. Is this possible, or are tags the central feature of describe?

The help page does seem to indicate that, but I just want to be sure. I use this in an Ant build.xml file, so I'm trying to keep this simple.

Answer 1

As I did not find any pre-existing "best practice" for automatically naming git revisions where no manual tags have been issued yet, I kind of came up with my own one:

In such a case I manually assign either a tag name "0" or "0.YYYYMMDDzhhmmss" for the initial (oldest) commit in the branch.

I prefer the first variant if I am confident that no one will merge that branch into an unrelated branch, thus producing multiple "initial" commits which need disambiguation.

In the latter case, I prefer the timestamp-based tag name. (The "z" is literal and shall be a hint that this represents a UTC ("zulu") time stamp rather than local time. I chose a lower case "z" rather than an upper case "Z" because the lower-case variant can easier be visually distinguished from the decimal digits sourrounding it because of its different letter height in most fonts.)

Most of the time, however, people just fork a repository and add their own commits on top of this. In this case, there are no multiple initial commits, and a timestamp-based tag name would be overkill. Then a tag name "0" is just fine for the first commit.

Anyway, after manually adding the tag, "git describe --tags" displays something like this

0-12-gb762572

or this

0.202305150z40100-12-gb762572

for the 13th unnamed commit - which looks pretty OK IMO.

Answer 2

Yes, but it's not necessarily a good idea. There is a --all option, which will search branch names—or in fact, all references—as well, but if you use that, you might also need --long.

Description

The central feature of git describe output is that it starts with a name that is (or should be) human-readable:

v1.2.3

To this, Git will, if necessary, add a suffix indicating that the current (or requested) commit is not quite the one named by this string. The suffix tells both you and Git how much to deviate from the tag. If there is no suffix, the tag itself names the commit. Since tags never¹ move, if we have that name, we are guaranteed² to find the correct commit using that name.

With a repository with no tags and no --always:

$ git describe
fatal: No names found, cannot describe anything.

If we add --all, however, we might get this:

$ git describe --all
heads/master

This is a human-readable name, but there is a problem with it: it does not uniquely identify one particular commit, because branch names do move. Once I make a new commit in this repository, refs/heads/master now names a different commit.

Since the usual intent of one of these outputs from git describe is to provide a human-readable but exact-commit-specifying ID, a branch name, which is never that exact, is not necessarily a good thing.

You can add --long:

$ git describe --all --long
heads/master-0-g2cbd83f

This now uses the -g... suffix to specify a prefix of the actual hash ID. Now Git can verify that master itself has not moved, or if it has, you can use the 2cbd83f string to find the commit.

---

¹Well, hardly ever. See the git-tag documentation on when and why and why not to move a tag.

²Guaranteed to the extent that tags have not moved, anyway.

Answer 3

Since the usual intent of one of these outputs from git describe is to provide a human-readable but exact-commit-specifying ID

That is what official git describe --long does have to do, according to Git 2.20

See commit 55f6bce, commit 6271d94, commit c263279 (19 Sep 2018) by Frederick Eaton (``).
^{(Merged by Junio C Hamano -- gitster -- in commit fb468f0, 16 Oct 2018)}

git-describe.1: clarify that "human readable" is also git-readable

The caption uses the term "human readable", but the DESCRIPTION did not explain this in context.

The man page now includes:

The result is a "human-readable" object name which can also be used to identify the commit to other git commands.

Answer 4

An easy way to do this is to combine --always with the -exclude option, using a glob pattern of *, to exclude all tags from consideration. Since it won't find any non-excluded tags, describe will fall back to just the abbreviated sha1 plus optionally "-dirty" and so on.

$ git describe --always --dirty --abbrev=5 
2018.02-rc1-58-gca0e6
$ git describe --always --dirty --abbrev=5 --exclude '*'
ca0e6