describe: teach describe negative pattern matches

Teach git-describe the `--exclude` option which will allow specifying
a glob pattern of tags to ignore. This can be combined with the
`--match` patterns to enable more flexibility in determining which tags
to consider.

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*" abcdef

Add documentation, tests, and completion for this change.

Signed-off-by: Jacob Keller <jacob.keller@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt
index 7ad41e2f6adee9a0bdce74b0a8987614afcc90b3..8755f3af7bcd16b564fdd01563e36d3cc4103c07 100644 (file)
--- a/Documentation/git-describe.txt
+++ b/Documentation/git-describe.txt
@@ -88,6 +88,16 @@ OPTIONS
        patterns will be considered. Use `--no-match` to clear and reset the
        list of patterns.
 
+--exclude <pattern>::
+       Do not consider tags matching the given `glob(7)` pattern, excluding
+       the "refs/tags/" prefix. This can be used to narrow the tag space and
+       find only tags matching some meaningful criteria. If given multiple
+       times, a list of patterns will be accumulated and tags matching any
+       of the patterns will be excluded. When combined with --match a tag will
+       be considered when it matches at least one --match pattern and does not
+       match any of the --exclude patterns. Use `--no-exclude` to clear and
+       reset the list of patterns.
+
 --always::
        Show uniquely abbreviated commit object as fallback.
 

diff --git a/builtin/describe.c b/builtin/describe.c
index 5cc9e9abe798e19705167a7459bb41945f7d617c..6769446e1f57537879fd1b411f83ba7393bad338 100644 (file)
--- a/builtin/describe.c
+++ b/builtin/describe.c
@@ -29,6 +29,7 @@ static int max_candidates = 10;
 static struct hashmap names;
 static int have_util;
 static struct string_list patterns = STRING_LIST_INIT_NODUP;
+static struct string_list exclude_patterns = STRING_LIST_INIT_NODUP;
 static int always;
 static const char *dirty;
 
@@ -129,6 +130,22 @@ static int get_name(const char *path, const struct object_id *oid, int flag, voi
        if (!all && !is_tag)
                return 0;
 
+       /*
+        * If we're given exclude patterns, first exclude any tag which match
+        * any of the exclude pattern.
+        */
+       if (exclude_patterns.nr) {
+               struct string_list_item *item;
+
+               if (!is_tag)
+                       return 0;
+
+               for_each_string_list_item(item, &exclude_patterns) {
+                       if (!wildmatch(item->string, path + 10, 0, NULL))
+                               return 0;
+               }
+       }
+
        /*
         * If we're given patterns, accept only tags which match at least one
         * pattern.
@@ -421,6 +438,8 @@ int cmd_describe(int argc, const char **argv, const char *prefix)
                            N_("consider <n> most recent tags (default: 10)")),
                OPT_STRING_LIST(0, "match", &patterns, N_("pattern"),
                           N_("only consider tags matching <pattern>")),
+               OPT_STRING_LIST(0, "exclude", &exclude_patterns, N_("pattern"),
+                          N_("do not consider tags matching <pattern>")),
                OPT_BOOL(0, "always",        &always,
                        N_("show abbreviated commit object as fallback")),
                {OPTION_STRING, 0, "dirty",  &dirty, N_("mark"),
@@ -458,6 +477,8 @@ int cmd_describe(int argc, const char **argv, const char *prefix)
                        argv_array_push(&args, "--tags");
                        for_each_string_list_item(item, &patterns)
                                argv_array_pushf(&args, "--refs=refs/tags/%s", item->string);
+                       for_each_string_list_item(item, &exclude_patterns)
+                               argv_array_pushf(&args, "--exclude=refs/tags/%s", item->string);
                }
                if (argc)
                        argv_array_pushv(&args, argv);

diff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash
index 21016bf8dfe87572fb53a05488ba05bb3c08ed97..21c2b4315b1ee7df2e53c48529eeddd99955e4c9 100644 (file)
--- a/contrib/completion/git-completion.bash
+++ b/contrib/completion/git-completion.bash
@@ -1198,6 +1198,7 @@ _git_describe ()
                __gitcomp "
                        --all --tags --contains --abbrev= --candidates=
                        --exact-match --debug --long --match --always
+                       --exclude
                        "
                return
        esac

diff --git a/t/t6120-describe.sh b/t/t6120-describe.sh
index 9e5db9b87a1faef912adaf460fc2d0ea7f375f50..167491fd5b0d0c5ed3744c51cd0f05723c9f964b 100755 (executable)
--- a/t/t6120-describe.sh
+++ b/t/t6120-describe.sh
@@ -218,6 +218,14 @@ test_expect_success 'describe --contains and --match' '
        test_cmp expect actual
 '
 
+test_expect_success 'describe --exclude' '
+       echo "c~1" >expect &&
+       tagged_commit=$(git rev-parse "refs/tags/A^0") &&
+       test_must_fail git describe --contains --match="B" $tagged_commit &&
+       git describe --contains --match="?" --exclude="A" $tagged_commit >actual &&
+       test_cmp expect actual
+'
+
 test_expect_success 'describe --contains and --no-match' '
        echo "A^0" >expect &&
        tagged_commit=$(git rev-parse "refs/tags/A^0") &&