git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [PATCH] describe: limit default ref iteration to tags

From
Tamir Duberstein <tamird@gmail.com>
Date
Jun 8, 2026, 15:46 UTC
Message-ID
<CAJ-ks9nPJVM0ik=yua9f2TSKkQWUWEUkZHZBQcdRq3P+3aA3iA@mail.gmail.com>
In-Reply-To
<aiZoYE8koq1UKlWq@pks.im>
On Sun, Jun 7, 2026 at 11:59 PM Patrick Steinhardt <ps@pks.im> wrote:
Show 46 quoted lines
>
> On Sun, Jun 07, 2026 at 04:51:53PM -0400, Tamir Duberstein wrote:
> > Unless --all is given, get_name() rejects every ref outside refs/tags/.
> > The rejection happens only after the ref backend has enumerated the ref,
> > so repositories with many other refs spend most of a simple describe
> > invocation visiting refs which cannot affect its result.
>
> Right. The relevant block is this one:
>
>         if (skip_prefix(ref->name, "refs/tags/", &path_to_match)) {
>                 is_tag = 1;
>         } else if (all) {
>                 if ((exclude_patterns.nr || patterns.nr) &&
>                     !skip_prefix(ref->name, "refs/heads/", &path_to_match) &&
>                     !skip_prefix(ref->name, "refs/remotes/", &path_to_match)) {
>                         /* Only accept reference of known type if there are match/exclude patterns */
>                         return 0;
>                 }
>         } else {
>                 /* Reject anything outside refs/tags/ unless --all */
>                 return 0;
>         }
>
> So we really only use tags unless "--all" is given.
>
> > Commit 8a5a1884e9 (Avoid accessing non-tag refs in git-describe unless
> > --all is requested, 2008-02-24) moved this rejection before object
> > lookup, but left iteration unscoped. Pass the existing refs/tags/
> > restriction to the iterator unless --all is given so the backend can
> > avoid unrelated refs.
> >
> > On a checkout with 124,357 refs, of which 330 were tags, I ran the
> > following command with the parent and patched binaries:
> >
> >     hyperfine --warmup 3 --runs 15 \
> >         'git describe --always --long --abbrev=40 HEAD'
> >
> > The results were:
> >
> >              parent       this commit
> >   elapsed    196.2 ms      63.3 ms
> >   user        69.5 ms      48.0 ms
> >   system     123.0 ms      12.0 ms
>
> It's a bit curious that you don't post the hyperfine(1) results as-is
> here.
Agreed, will include that in v2. For reference:
        Benchmark 1: parent
          Time (mean ± σ):     171.7 ms ±  18.5 ms    [User: 23.9 ms,
System: 133.6 ms]
          Range (min … max):   142.3 ms … 198.3 ms    15 runs
        Benchmark 2: this commit
          Time (mean ± σ):       9.9 ms ±   1.1 ms    [User: 3.3 ms,
System: 4.7 ms]
          Range (min … max):     8.8 ms …  13.1 ms    15 runs
Show 26 quoted lines
>
> > The wall-time standard deviations were 13.2 ms and 2.6 ms, respectively,
> > for a 3.10x speedup.
>
> Makes sense that this would result in a sizeable speedup, depending of
> course on the shape of the existing refs in the repository.
>
> > diff --git a/builtin/describe.c b/builtin/describe.c
> > index 1c47d7c0b7..3532c8ff22 100644
> > --- a/builtin/describe.c
> > +++ b/builtin/describe.c
> > @@ -740,6 +740,9 @@ int cmd_describe(int argc,
> >               return ret;
> >       }
> >
> > +     if (!all)
> > +             for_each_ref_opts.prefix = "refs/tags/";
> > +
> >       hashmap_init(&names, commit_name_neq, NULL, 0);
> >       refs_for_each_ref_ext(get_main_ref_store(the_repository),
> >                             get_name, NULL, &for_each_ref_opts);
>
> Another performance optimization that we could do here is to wire up the
> exclude patterns via `for_each_ref_opts.exclude_patterns`. But that's
> outside the scope of this patch series, and also much less likely to
> help many use cases out there.
I tried this and have a separate patch prepared.

The patterns cannot be passed through verbatim: `git describe --exclude=foo` excludes the exact name `foo`, while the refs API would treat `foo` as a directory prefix and also skip `foo/*`. The patch therefore passes only patterns consisting of a literal prefix followed by trailing asterisks, adds back the applicable ref namespace, and retains the existing callback filtering.

With 30,000 packed remote-tracking refs under an excluded prefix, the perf test invokes `git describe` ten times per run:

```
                                  master           patched
describe excluding many refs   0.16(0.07+0.05)  0.12(0.04+0.05)
```

That is a 25% wall-time reduction, with user CPU falling from 0.07 to 0.04 seconds.

I also tested a larger checkout with 62,170 refs under `refs/remotes/origin/`:

``` git describe --all --exact-match --exclude='origin/*' HEAD ```

This improved from 176.7 ms to 161.3 ms, or about 10%. Startup work unrelated to ref iteration dominates more of that repository's runtime.

Show 16 quoted lines
>
> > diff --git a/t/perf/p6100-describe.sh b/t/perf/p6100-describe.sh
> > index 069f91ce49..dfcaf59e90 100755
> > --- a/t/perf/p6100-describe.sh
> > +++ b/t/perf/p6100-describe.sh
> > @@ -5,6 +5,12 @@ test_description='performance of git-describe'
> >
> >  test_perf_default_repo
> >
> > +test_lazy_prereq PERF_REFFILES '
> > +     test "$(git rev-parse --show-ref-format)" = files
> > +'
> > +
> > +ref_count=10000
>
> Let's not declare this variable outside of tests.
Done in v2.
Show 17 quoted lines
>
> > @@ -27,4 +33,18 @@ test_perf 'describe HEAD with one tag' '
> >       git describe --match=new HEAD
> >  '
> >
> > +test_expect_success PERF_REFFILES 'set up many unrelated refs' '
> > +     git tag -m tip tip HEAD &&
> > +     for i in $(test_seq $ref_count)
> > +     do
> > +             printf "create refs/heads/describe-perf/%05d HEAD\n" $i ||
> > +             return 1
> > +     done >instructions &&
> > +     git update-ref --stdin <instructions
> > +'
>
> Why is this limited to the "files" backend, only? The logic should work
> for both backends as-is.
You're right, fixed in v2.
>
> Thanks!
Thanks for the quick review!
Previous: Patrick SteinhardtNext: Junio C Hamano
Message 3 of 5 in “describe: limit default ref iteration to tags”
  1. describe: limit default ref iteration to tagsTamir Duberstein, Jun 7, 2026
  2. Patrick SteinhardtJun 8, 2026
  3. Tamir DubersteinJun 8, 2026
  4. Junio C HamanoJun 8, 2026
  5. Tamir DubersteinJun 8, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.