Teach git-describe --exact-match to avoid expensive tag searches
Sometimes scripts want (or need) the annotated tag name that exactly
matches a specific commit, or no tag at all. In such cases it can be
difficult to determine if the output of `git describe $commit` is a
real tag name or a tag+abbreviated commit. A common idiom is to run
git-describe twice:
if test $(git describe $commit) = $(git describe --abbrev=0 $commit)
...
but this is a huge waste of time if the caller is just going to pick a
different method to describe $commit or abort because it is not exactly
an annotated tag.
Setting the maximum number of candidates to 0 allows the caller to ask
for only a tag that directly points at the supplied commit, or to have
git-describe abort if no such item exists.
Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt
index 1c3dfb4..fbb40a2 100644
--- a/Documentation/git-describe.txt
+++ b/Documentation/git-describe.txt
@@ -45,6 +45,11 @@
candidates to describe the input committish consider
up to <n> candidates. Increasing <n> above 10 will take
slightly longer but may produce a more accurate result.
+ An <n> of 0 will cause only exact matches to be output.
+
+--exact-match::
+ Only output exact matches (a tag directly references the
+ supplied commit). This is a synonym for --candidates=0.
--debug::
Verbosely display information about the searching strategy
