如何使用 git describe 匹配隐藏的 ref

Question

deriving version numbers from a git repository seems to be a good solution for matching version numbers, but my scenario is a bit different.

The version numbers I generate I'd like to create hidden refs for (so they don't make it to other clients by default). I don't want the clients to see a bunch of version churn on their fetches.

The problem is, --match only works for tags, even if you use the --all flag.

Example:

git update-ref refs/_v.master.0.1 c2897c8338e02b99644640f3afb829c04cb48439

this creates the hidden ref

git describe --all c2897c8338e02b99644640f3afb829c04cb48439
_v.master.0.1 [this shows up]

yet this doesn't return anything:

git describe --match _v* --all c2897c8338e02b99644640f3afb829c04cb48439
fatal: No names found, cannot describe anything.

I see in the documentation that --match "Only consider tags matching the given glob(7) pattern", but that seems lame, matching should be applicable to any ref type assuming other modifiers (-all --tags, etc) limit the scope of the ref types.

Any other way for me to do this? One way I thought of is to create tags on one client, and map them (at push and fetch time) to hidden refs to/from the origin, but that seems like a lot of extra work. Is the ref matching I mention above available from the API if not the client?

thanks in advance!

Answer 1

You will have to check that with Git 2.14.x/2.15 (Q4 2017)

" git describe --match <pattern> " has been taught to play well with the " --all " option.

See commit 6d68b2a (20 Sep 2017) by Max Kirillov ( max630 ) .
^{(Merged by Junio C Hamano -- gitster -- in commit 8c1bc7c , 29 Sep 2017)}

describe : teach --match to handle branches and remotes

When git describe uses --match , it matches only tags, basically ignoring the --all argument even when it is specified.

Fix it by also matching branch name and $remote_name/$remote_branch_name , for remote-tracking references, with the specified patterns.
Update documentation accordingly and add tests.

It also deals with negative patterns:

For example, suppose you wish to find the first official release tag that contains a certain commit. If we assume that official release tags are of the form " v* " and pre-release candidates include " *rc* " in their name, we can now find the first release tag that introduces the commit abcdef :

git describe --contains --match="v*" --exclude="*rc*" abcd

---

Note that Git 2.16.x/2.17 (Q1 2018) will restore the proper output for " git describe --all ".
See commit 1bba001 (11 Dec 2017) by Daniel Knittl-Frank ( knittl ) .
^{(Merged by Junio C Hamano -- gitster -- in commit fac64e0 , 23 Jan 2018)}

describe : prepend " tags/ " when describing tags with embedded name

The man page of the " git describe " command explains the expected output when using the --all option, ie the full reference path is shown, including heads/ or tags/ prefix.

When 212945d ("Teach git-describe to verify annotated tag names before output", Feb 28, 2008, Git v1.5.5-rc0) made Git favor the embedded name of annotated tags, it accidentally changed the output format when the --all flag is given, only printing the tag's name without the prefix.

Check if --all was specified and re-add the " tags/ " prefix for this special case to fix the regression.

---

When " git describe C " finds an annotated tag with tagname A to be the best name to explain commit C , and the tag is stored in a " wrong " place in the refs/tags hierarchy, eg refs/tags/B , the command gave a warning message but used A (not B ) to describe C .
If C is exactly at the tag, the describe output would be " A ", but " git rev-parse A^0 " would not be equal as " git rev-parse C^0 ".

The behavior of the command has been changed with Git 2.27 (Q2 2020), to use the "long" form ie A-0-gOBJECTNAME , which is correctly interpreted by rev-parse .

See commit ff165f0 (20 Feb 2020) by Junio C Hamano ( gitster ) .
^{(Merged by Junio C Hamano -- gitster -- in commit 0f0625a , 27 Mar 2020)}

describe : force long format for a name based on a mislocated tag

^{Helped-by: Matheus Tavares
Helped-by: Jeff King}

An annotated tag has two names :

• where it sits in the refs/tags hierarchy and
• the tagname recorded in the " tag " field in the object itself.

They usually should match.

Since 212945d4 ("Teach git describe to verify annotated tag names before output", 2008-02-28, Git v1.5.5-rc0 -- merge ), a commit described using an annotated tag bases its name on the tagname from the object.

While this was a deliberate design decision to make it easier to converse about tags with others, even if the tags happen to be fetched to a different name than it was given by its creator, it had one downside.

The output from " git describe ", at least in the modern Git, should be usable as an object name to name the exact commit given to the " git describe " command.

Using the tagname, when two names differ, breaks this property, when describing a commit that is directly pointed at by such a tag.

An annotated tag Bob made as " v1.0 " may sit at " refs/tags/v1.0-bob " in the ref hierarchy, and output from " git describe v1.0-bob^0 " would say " v1.0 ", but there may not be any tag at " refs/tags/v1.0 " locally or there may be another tag that points at a different object.

Note that this won't be a problem if a commit being described is not directly pointed at by such a mislocated tag.

In the example in the previous paragraph, describing a commit whose parent is v1.0-bob would result in " v1.0 " (ie the tagname taken from the tag object) followed by " -1-gXXXXX " where XXXXX is the abbreviated object name, and a string that ends with " -g " followed by a hexadecimal string is an object name for the object whose name begins with hexadecimal string (as long as it is unique), so it does not matter if the leading part is " v1.0 " or " v1.0-bob ".

Show the name in the long format, ie with " -0-gXXXXX " suffix, when the name we give is based on a mislocated annotated tag to ensure that the output can be used as the object name for the object originally given to the command to fix the issue.

While at it, remove an overly cautious dead code to protect against an annotated tag object without the tagname.

Such a tag is filtered out much earlier in the codeflow, and will not reach this part of the code.