Re: [PATCH] doc: format.notes specify a ref under refs/notes/ hierarchy

[Junio C Hamano <gitster@pobox.com>]

Patrick Steinhardt <ps@pks.im> writes:

> On Fri, Dec 15, 2023 at 02:28:00PM -0800, Junio C Hamano wrote:
>> There is no 'ref/notes/' hierarchy.  '[format] notes = foo' uses notes
>> that are found in 'refs/notes/foo'.
>> 
>> Signed-off-by: Junio C Hamano <gitster@pobox.com>
>> ---
>>  * According to my eyeballing "git grep refs/ Documentation" result,
>>    this was the only remaining mention of "ref/" in Documentation/
>>    hierarchy that misspells "refs/".
>
> This made me look for additional instances where we were referring to
> "ref/". Turns out it's only a very limited set, see the below diff.

Yup, I did the same grep, but I tend to avoid churning what we
published long ago (and kept in Documentation/RelNotes/), my patches
only covered documents that are still relevant.

> the translation changes with a big grain of salt though,

Hopefully pinging Jiang would be sufficient to ask help from the
French, Chinese, and Taiwaneese translation teams.

> diff --git a/po/fr.po b/po/fr.po
> index ee2e610ef1..744550b056 100644
> --- a/po/fr.po
> +++ b/po/fr.po
> @@ -19773,7 +19773,7 @@ msgid ""
>  "Neither worked, so we gave up. You must fully qualify the ref."
>  msgstr ""
>  "La destination que vous avez fournie n'est pas un nom de référence complète\n"
> -"(c'est-à-dire commençant par \"ref/\"). Essai d'approximation par :\n"
> +"(c'est-à-dire commençant par \"refs/\"). Essai d'approximation par :\n"
>  "\n"
>  "- Recherche d'une référence qui correspond à '%s' sur le serveur distant.\n"
>  "- Vérification si la <source> en cours de poussée ('%s')\n"
> diff --git a/po/zh_CN.po b/po/zh_CN.po
> index 86402725b2..eb47e8f9b7 100644
> --- a/po/zh_CN.po
> +++ b/po/zh_CN.po
> @@ -13224,8 +13224,8 @@ msgid ""
>  msgid_plural ""
>  "Note: Some branches outside the refs/remotes/ hierarchy were not removed;\n"
>  "to delete them, use:"
> -msgstr[0] "注意：ref/remotes 层级之外的一个分支未被移除。要删除它，使用："
> -msgstr[1] "注意：ref/remotes 层级之外的一些分支未被移除。要删除它们，使用："
> +msgstr[0] "注意：refs/remotes 层级之外的一个分支未被移除。要删除它，使用："
> +msgstr[1] "注意：refs/remotes 层级之外的一些分支未被移除。要删除它们，使用："
>  
>  #: builtin/remote.c
>  #, c-format
> diff --git a/po/zh_TW.po b/po/zh_TW.po
> index f777a0596f..b2a79cdd93 100644
> --- a/po/zh_TW.po
> +++ b/po/zh_TW.po
> @@ -13109,7 +13109,7 @@ msgid ""
>  msgid_plural ""
>  "Note: Some branches outside the refs/remotes/ hierarchy were not removed;\n"
>  "to delete them, use:"
> -msgstr[0] "注意：ref/remotes 層級之外的一個分支未被移除。要刪除它，使用："
> +msgstr[0] "注意：refs/remotes 層級之外的一個分支未被移除。要刪除它，使用："
>  
>  #: builtin/remote.c
>  #, c-format

> Also, the test is
> interesting because it would fail even if we didn't pass an invalid atom
> to git-for-each-ref(1).

It is interesting but not surprising.  It is not an error to use ref
patterns that do not match any ref.  It is a mere pattern to filtering
what are in refs/ for the ones to be output.

> diff --git a/t/t6300-for-each-ref.sh b/t/t6300-for-each-ref.sh
> index 54e2281259..e68f7bec8e 100755
> --- a/t/t6300-for-each-ref.sh
> +++ b/t/t6300-for-each-ref.sh
> @@ -841,7 +841,7 @@ test_expect_success 'err on bad describe atom arg' '
>  		EOF
>  		test_must_fail git for-each-ref \
>  			--format="%(describe:tags,qux=1,abbrev=14)" \
> -			ref/heads/master 2>actual &&
> +			refs/heads/master 2>actual &&
>  		test_cmp expect actual
>  	)
>  '

The "for-each-ref" family's "--format" string is first parsed and
sanity-checked before it is applied.  The bogus ref pattern may not
yield any ref to apply the format string, but we do not optimize out
the parsing and checking, even though we could, as it would be
optimizing for a wrong case.  So regardless of the ref pattern at
the end of the command line does not make a difference to the
outcome of this test.