{"thread":{"id":"61579","subject":"[PATCH 0/3] Branches are branches and not heads","startedAt":"2024-06-03T20:05:45Z","lastAt":"2024-06-14T22:48:09Z","messageCount":22,"participants":["Junio C Hamano","Rubén Justo","Eric Sunshine","Patrick Steinhardt","Elijah Newren"],"isPatch":true,"patchVersion":1,"patchTotal":3},"messages":[{"id":"496172","messageId":"20240603200539.1473345-1-gitster@pobox.com","threadId":"61579","inReplyTo":null,"subject":"[PATCH 0/3] Branches are branches and not heads","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-06-03T20:05:36Z","receivedAt":"2024-06-03T20:05:45Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Back when Git started, we used the word \"head\" to mean the tip of\npossibly multiple histories, and that is where the name of the\nhierarchy .git/refs/heads/ came from. But these days we call these\nentities \"branches\" in human terms, and \"head\" is still used to\nrefer to the tip of the history each of these branches represent.\n\nWhen asking \"git ls-remote\" or \"git show-ref\" to limit their output\nto branches (as opposed to showing any ref), we use \"--heads\" for\nhistorical reasons, but give the option a more human friendly name\n\"--branches\", and demote \"--heads\" to the status of a deprecated\nsynonym. This would eventually allow us to remove them at the\nbreaking version boundary.\n\nJunio C Hamano (3):\n refs: call branches branches\n ls-remote: introduce --branches and deprecate --heads\n show-ref: introduce --branches and deprecate --heads\n\n Documentation/git-ls-remote.txt | 12 +++++++-----\n Documentation/git-show-ref.txt | 18 ++++++++++--------\n builtin/ls-remote.c | 25 ++++++++++++++++++++++---\n builtin/show-ref.c | 33 ++++++++++++++++++++++++++-------\n connect.c | 4 ++--\n remote.h | 2 +-\n t/t1403-show-ref.sh | 22 ++++++++++++++--------\n t/t5512-ls-remote.sh | 30 +++++++++++++++++++++++++-----\n 8 files changed, 107 insertions(+), 39 deletions(-)\n\n-- \n2.45.2-404-g9eaef5822c\n\n"},{"id":"496173","messageId":"20240603200539.1473345-2-gitster@pobox.com","threadId":"61579","inReplyTo":"20240603200539.1473345-1-gitster@pobox.com","subject":"[PATCH 1/3] refs: call branches branches","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-06-03T20:05:37Z","receivedAt":"2024-06-03T20:05:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"These things in refs/heads/ hierarchy are called \"branches\" in human\nparlance. Replace REF_HEADS with REF_BRANCHES to make it clearer.\n\nNo end-user visible change intended at this step.\n\nSigned-off-by: Junio C Hamano \n---\n builtin/ls-remote.c | 6 +++---\n connect.c | 4 ++--\n remote.h | 2 +-\n 3 files changed, 6 insertions(+), 6 deletions(-)\n\ndiff --git a/builtin/ls-remote.c b/builtin/ls-remote.c\nindex e8d65ebbdc..9838de69c0 100644\n--- a/builtin/ls-remote.c\n+++ b/builtin/ls-remote.c\n@@ -9,7 +9,7 @@\n #include \"wildmatch.h\"\n \n static const char * const ls_remote_usage[] = {\n-\tN_(\"git ls-remote [--heads] [--tags] [--refs] [--upload-pack=]\\n\"\n+\tN_(\"git ls-remote [--branches] [--tags] [--refs] [--upload-pack=]\\n\"\n \t \" [-q | --quiet] [--exit-code] [--get-url] [--sort=]\\n\"\n \t \" [--symref] [ [...]]\"),\n \tNULL\n@@ -68,7 +68,7 @@ int cmd_ls_remote(int argc, const char **argv, const char *prefix)\n \t\t\t N_(\"path of git-upload-pack on the remote host\"),\n \t\t\t PARSE_OPT_HIDDEN },\n \t\tOPT_BIT('t', \"tags\", &flags, N_(\"limit to tags\"), REF_TAGS),\n-\t\tOPT_BIT('h', \"heads\", &flags, N_(\"limit to heads\"), REF_HEADS),\n+\t\tOPT_BIT('h', \"heads\", &flags, N_(\"limit to heads\"), REF_BRANCHES),\n \t\tOPT_BIT(0, \"refs\", &flags, N_(\"do not show peeled tags\"), REF_NORMAL),\n \t\tOPT_BOOL(0, \"get-url\", &get_url,\n \t\t\t N_(\"take url..insteadOf into account\")),\n@@ -100,7 +100,7 @@ int cmd_ls_remote(int argc, const char **argv, const char *prefix)\n \n \tif (flags & REF_TAGS)\n \t\tstrvec_push(&transport_options.ref_prefixes, \"refs/tags/\");\n-\tif (flags & REF_HEADS)\n+\tif (flags & REF_BRANCHES)\n \t\tstrvec_push(&transport_options.ref_prefixes, \"refs/heads/\");\n \n \tremote = remote_get(dest);\ndiff --git a/connect.c b/connect.c\nindex 0d77737a53..cf84e631e9 100644\n--- a/connect.c\n+++ b/connect.c\n@@ -38,8 +38,8 @@ static int check_ref(const char *name, unsigned int flags)\n \t\t\t\t\t\t\t REFNAME_ALLOW_ONELEVEL))\n \t\treturn 0;\n \n-\t/* REF_HEADS means that we want regular branch heads */\n-\tif ((flags & REF_HEADS) && starts_with(name, \"heads/\"))\n+\t/* REF_BRANCHES means that we want regular branch heads */\n+\tif ((flags & REF_BRANCHES) && starts_with(name, \"heads/\"))\n \t\treturn 1;\n \n \t/* REF_TAGS means that we want tags */\ndiff --git a/remote.h b/remote.h\nindex dfd4837e60..02e330f42c 100644\n--- a/remote.h\n+++ b/remote.h\n@@ -200,7 +200,7 @@ struct ref {\n };\n \n #define REF_NORMAL\t(1u << 0)\n-#define REF_HEADS\t(1u << 1)\n+#define REF_BRANCHES\t(1u << 1)\n #define REF_TAGS\t(1u << 2)\n \n struct ref *find_ref_by_name(const struct ref *list, const char *name);\n-- \n2.45.2-404-g9eaef5822c\n\n"},{"id":"496174","messageId":"20240603200539.1473345-3-gitster@pobox.com","threadId":"61579","inReplyTo":"20240603200539.1473345-1-gitster@pobox.com","subject":"[PATCH 2/3] ls-remote: introduce --branches and deprecate --heads","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-06-03T20:05:38Z","receivedAt":"2024-06-03T20:05:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"We call the tips of branches \"heads\", but this command calls the\noption to show only branches \"--heads\", which confuses the branches\nthemselves and the tips of branches.\n\nStraighten the terminology by introducing \"--branches\" option that\nlimits the output to branches, and deprecate \"--heads\" option used\nthat way.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/git-ls-remote.txt | 12 +++++++-----\n builtin/ls-remote.c | 21 ++++++++++++++++++++-\n t/t5512-ls-remote.sh | 30 +++++++++++++++++++++++++-----\n 3 files changed, 52 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt\nindex 1c4f696ab5..76c86c3ce4 100644\n--- a/Documentation/git-ls-remote.txt\n+++ b/Documentation/git-ls-remote.txt\n@@ -9,7 +9,7 @@ git-ls-remote - List references in a remote repository\n SYNOPSIS\n --------\n [verse]\n-'git ls-remote' [--heads] [--tags] [--refs] [--upload-pack=]\n+'git ls-remote' [--branches] [--tags] [--refs] [--upload-pack=]\n \t [-q | --quiet] [--exit-code] [--get-url] [--sort=]\n \t [--symref] [ [...]]\n \n@@ -21,14 +21,16 @@ commit IDs.\n \n OPTIONS\n -------\n--h::\n---heads::\n+-b::\n+--branches::\n -t::\n --tags::\n-\tLimit to only refs/heads and refs/tags, respectively.\n+\tLimit to only local branches and local tags, respectively.\n \tThese options are _not_ mutually exclusive; when given\n \tboth, references stored in refs/heads and refs/tags are\n-\tdisplayed. Note that `git ls-remote -h` used without\n+\tdisplayed. Note that `--heads` and `-h` are deprecated\n+\tsynonyms for `--branches` and `-b` and may be removed in\n+\tthe future. Also note that `git ls-remote -h` used without\n \tanything else on the command line gives help, consistent\n \twith other git subcommands.\n \ndiff --git a/builtin/ls-remote.c b/builtin/ls-remote.c\nindex 9838de69c0..95fbb8b7b5 100644\n--- a/builtin/ls-remote.c\n+++ b/builtin/ls-remote.c\n@@ -38,6 +38,20 @@ static int tail_match(const char **pattern, const char *path)\n \treturn 0;\n }\n \n+static int heads_callback(const struct option *opt, const char *arg, int unset)\n+{\n+\tunsigned *flags = opt->value;\n+\n+\tif (unset) {\n+\t\twarning(_(\"'--no-heads' is deprecated; use '--no-branches' instead\"));\n+\t\t*flags &= ~REF_BRANCHES;\n+\t} else {\n+\t\twarning(_(\"'--heads' is deprecated; use '--branches' instead\"));\n+\t\t*flags |= REF_BRANCHES;\n+\t}\n+\treturn 0;\n+}\n+\n int cmd_ls_remote(int argc, const char **argv, const char *prefix)\n {\n \tconst char *dest = NULL;\n@@ -68,7 +82,12 @@ int cmd_ls_remote(int argc, const char **argv, const char *prefix)\n \t\t\t N_(\"path of git-upload-pack on the remote host\"),\n \t\t\t PARSE_OPT_HIDDEN },\n \t\tOPT_BIT('t', \"tags\", &flags, N_(\"limit to tags\"), REF_TAGS),\n-\t\tOPT_BIT('h', \"heads\", &flags, N_(\"limit to heads\"), REF_BRANCHES),\n+\t\tOPT_BIT('b', \"branches\", &flags, N_(\"limit to branches\"), REF_BRANCHES),\n+\t\tOPT_CALLBACK_F('h', \"heads\", &flags,\n+\t\t\t NULL,\n+\t\t\t N_(\"deprecated synonym for --branches\"),\n+\t\t\t PARSE_OPT_NOARG|PARSE_OPT_HIDDEN,\n+\t\t\t &heads_callback),\n \t\tOPT_BIT(0, \"refs\", &flags, N_(\"do not show peeled tags\"), REF_NORMAL),\n \t\tOPT_BOOL(0, \"get-url\", &get_url,\n \t\t\t N_(\"take url..insteadOf into account\")),\ndiff --git a/t/t5512-ls-remote.sh b/t/t5512-ls-remote.sh\nindex 5dbe107ce8..b9950ca361 100755\n--- a/t/t5512-ls-remote.sh\n+++ b/t/t5512-ls-remote.sh\n@@ -47,6 +47,7 @@ test_expect_success setup '\n \tgit show-ref -d\t>refs &&\n \tsed -e \"s/ /\t/\" refs >>expected.all &&\n \n+\tgrep refs/heads/ expected.all >expected.branches &&\n \tgit remote add self \"$(pwd)/.git\" &&\n \tgit remote add self2 \".\"\n '\n@@ -71,6 +72,25 @@ test_expect_success 'ls-remote self' '\n \ttest_cmp expected.all actual\n '\n \n+test_expect_success 'ls-remote --branches self' '\n+\tgit ls-remote --branches self >actual &&\n+\ttest_cmp expected.branches actual &&\n+\tgit ls-remote -b self >actual &&\n+\ttest_cmp expected.branches actual\n+'\n+\n+test_expect_success 'ls-remote -h is deprecated' '\n+\tgit ls-remote -h self >actual 2>warning &&\n+\ttest_cmp expected.branches actual &&\n+\ttest_grep deprecated warning\n+'\n+\n+test_expect_success 'ls-remote --heads is deprecated' '\n+\tgit ls-remote --heads self >actual 2>warning &&\n+\ttest_cmp expected.branches actual &&\n+\ttest_grep deprecated warning\n+'\n+\n test_expect_success 'ls-remote --sort=\"version:refname\" --tags self' '\n \tgenerate_references \\\n \t\trefs/tags/mark \\\n@@ -275,7 +295,7 @@ test_expect_success 'ls-remote with filtered symref (refname)' '\n \ttest_cmp expect actual\n '\n \n-test_expect_success 'ls-remote with filtered symref (--heads)' '\n+test_expect_success 'ls-remote with filtered symref (--branches)' '\n \tgit symbolic-ref refs/heads/foo refs/tags/mark &&\n \tcat >expect.v2 <<-EOF &&\n \tref: refs/tags/mark\trefs/heads/foo\n@@ -283,9 +303,9 @@ test_expect_success 'ls-remote with filtered symref (--heads)' '\n \t$rev\trefs/heads/main\n \tEOF\n \tgrep -v \"^ref: refs/tags/\" expect.v0 &&\n-\tgit -c protocol.version=0 ls-remote --symref --heads . >actual.v0 &&\n+\tgit -c protocol.version=0 ls-remote --symref --branches . >actual.v0 &&\n \ttest_cmp expect.v0 actual.v0 &&\n-\tgit -c protocol.version=2 ls-remote --symref --heads . >actual.v2 &&\n+\tgit -c protocol.version=2 ls-remote --symref --branches . >actual.v2 &&\n \ttest_cmp expect.v2 actual.v2\n '\n \n@@ -335,9 +355,9 @@ test_expect_success 'ls-remote patterns work with all protocol versions' '\n test_expect_success 'ls-remote prefixes work with all protocol versions' '\n \tgit for-each-ref --format=\"%(objectname)\t%(refname)\" \\\n \t\trefs/heads/ refs/tags/ >expect &&\n-\tgit -c protocol.version=0 ls-remote --heads --tags . >actual.v0 &&\n+\tgit -c protocol.version=0 ls-remote --branches --tags . >actual.v0 &&\n \ttest_cmp expect actual.v0 &&\n-\tgit -c protocol.version=2 ls-remote --heads --tags . >actual.v2 &&\n+\tgit -c protocol.version=2 ls-remote --branches --tags . >actual.v2 &&\n \ttest_cmp expect actual.v2\n '\n \n-- \n2.45.2-404-g9eaef5822c\n\n"},{"id":"496175","messageId":"20240603200539.1473345-4-gitster@pobox.com","threadId":"61579","inReplyTo":"20240603200539.1473345-1-gitster@pobox.com","subject":"[PATCH 3/3] show-ref: introduce --branches and deprecate --heads","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-06-03T20:05:39Z","receivedAt":"2024-06-03T20:05:53Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"We call the tips of branches \"heads\", but this command calls the\noption to show only branches \"--heads\", which confuses the branches\nthemselves and the tips of branches.\n\nStraighten the terminology by introducing \"--branches\" option that\nlimits the output to branches, and deprecate \"--heads\" option used\nthat way.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/git-show-ref.txt | 18 ++++++++++--------\n builtin/show-ref.c | 33 ++++++++++++++++++++++++++-------\n t/t1403-show-ref.sh | 22 ++++++++++++++--------\n 3 files changed, 50 insertions(+), 23 deletions(-)\n\ndiff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt\nindex ba75747005..616d919655 100644\n--- a/Documentation/git-show-ref.txt\n+++ b/Documentation/git-show-ref.txt\n@@ -9,8 +9,8 @@ SYNOPSIS\n --------\n [verse]\n 'git show-ref' [--head] [-d | --dereference]\n-\t [-s | --hash[=]] [--abbrev[=]] [--tags]\n-\t [--heads] [--] [...]\n+\t [-s | --hash[=]] [--abbrev[=]] [--branches] [--tags]\n+\t [--] [...]\n 'git show-ref' --verify [-q | --quiet] [-d | --dereference]\n \t [-s | --hash[=]] [--abbrev[=]]\n \t [--] [...]\n@@ -45,12 +45,14 @@ OPTIONS\n \n \tShow the HEAD reference, even if it would normally be filtered out.\n \n---heads::\n+--branches::\n --tags::\n \n-\tLimit to \"refs/heads\" and \"refs/tags\", respectively. These options\n+\tLimit to local branches and local tags, respectively. These options\n \tare not mutually exclusive; when given both, references stored in\n-\t\"refs/heads\" and \"refs/tags\" are displayed.\n+\t\"refs/heads\" and \"refs/tags\" are displayed. Note that `--heads`\n+\tis a deprecated synonym for `--branches` and may be removed\n+\tin the future.\n \n -d::\n --dereference::\n@@ -139,7 +141,7 @@ When using `--hash` (and not `--dereference`), the output is in the format:\n For example,\n \n -----------------------------------------------------------------------------\n-$ git show-ref --heads --hash\n+$ git show-ref --branches --hash\n 2e3ba0114a1f52b47df29743d6915d056be13278\n 185008ae97960c8d551adcd9e23565194651b5d1\n 03adf42c988195b50e1a1935ba5fcbc39b2b029b\n@@ -183,8 +185,8 @@ to check whether a particular branch exists or not (notice how we don't\n actually want to show any results, and we want to use the full refname for it\n in order to not trigger the problem with ambiguous partial matches).\n \n-To show only tags, or only proper branch heads, use `--tags` and/or `--heads`\n-respectively (using both means that it shows tags and heads, but not other\n+To show only tags, or only proper branch heads, use `--tags` and/or `--branches`\n+respectively (using both means that it shows tags and branches, but not other\n random references under the refs/ subdirectory).\n \n To do automatic tag object dereferencing, use the `-d` or `--dereference`\ndiff --git a/builtin/show-ref.c b/builtin/show-ref.c\nindex 1c15421e60..6b69daeb66 100644\n--- a/builtin/show-ref.c\n+++ b/builtin/show-ref.c\n@@ -11,8 +11,8 @@\n \n static const char * const show_ref_usage[] = {\n \tN_(\"git show-ref [--head] [-d | --dereference]\\n\"\n-\t \" [-s | --hash[=]] [--abbrev[=]] [--tags]\\n\"\n-\t \" [--heads] [--] [...]\"),\n+\t \" [-s | --hash[=]] [--abbrev[=]] [--branches] [--tags]\\n\"\n+\t \" [--] [...]\"),\n \tN_(\"git show-ref --verify [-q | --quiet] [-d | --dereference]\\n\"\n \t \" [-s | --hash[=]] [--abbrev[=]]\\n\"\n \t \" [--] [...]\"),\n@@ -188,7 +188,7 @@ static int cmd_show_ref__verify(const struct show_one_options *show_one_opts,\n \n struct patterns_options {\n \tint show_head;\n-\tint heads_only;\n+\tint branches_only;\n \tint tags_only;\n };\n \n@@ -206,8 +206,8 @@ static int cmd_show_ref__patterns(const struct patterns_options *opts,\n \n \tif (opts->show_head)\n \t\thead_ref(show_ref, &show_ref_data);\n-\tif (opts->heads_only || opts->tags_only) {\n-\t\tif (opts->heads_only)\n+\tif (opts->branches_only || opts->tags_only) {\n+\t\tif (opts->branches_only)\n \t\t\tfor_each_fullref_in(\"refs/heads/\", show_ref, &show_ref_data);\n \t\tif (opts->tags_only)\n \t\t\tfor_each_fullref_in(\"refs/tags/\", show_ref, &show_ref_data);\n@@ -279,6 +279,20 @@ static int exclude_existing_callback(const struct option *opt, const char *arg,\n \treturn 0;\n }\n \n+static int heads_callback(const struct option *opt, const char *arg, int unset)\n+{\n+\tint *branches_only = opt->value;\n+\n+\tif (unset) {\n+\t\twarning(_(\"'--no-heads' is deprecated; use '--no-branches' instead\"));\n+\t\t*branches_only = 0;\n+\t} else {\n+\t\twarning(_(\"'--heads' is deprecated; use '--branches' instead\"));\n+\t\t*branches_only = 1;\n+\t}\n+\treturn 0;\n+}\n+\n int cmd_show_ref(int argc, const char **argv, const char *prefix)\n {\n \tstruct exclude_existing_options exclude_existing_opts = {0};\n@@ -286,8 +300,13 @@ int cmd_show_ref(int argc, const char **argv, const char *prefix)\n \tstruct show_one_options show_one_opts = {0};\n \tint verify = 0, exists = 0;\n \tconst struct option show_ref_options[] = {\n-\t\tOPT_BOOL(0, \"tags\", &patterns_opts.tags_only, N_(\"only show tags (can be combined with heads)\")),\n-\t\tOPT_BOOL(0, \"heads\", &patterns_opts.heads_only, N_(\"only show heads (can be combined with tags)\")),\n+\t\tOPT_BOOL(0, \"tags\", &patterns_opts.tags_only, N_(\"only show tags (can be combined with branches)\")),\n+\t\tOPT_BOOL(0, \"branches\", &patterns_opts.branches_only, N_(\"only show branches (can be combined with tags)\")),\n+\t\tOPT_CALLBACK_F(0, \"heads\", &patterns_opts.branches_only,\n+\t\t\t NULL,\n+\t\t\t N_(\"deprecated synonym for --branches)\"),\n+\t\t\t PARSE_OPT_NOARG|PARSE_OPT_HIDDEN,\n+\t\t\t &heads_callback),\n \t\tOPT_BOOL(0, \"exists\", &exists, N_(\"check for reference existence without resolving\")),\n \t\tOPT_BOOL(0, \"verify\", &verify, N_(\"stricter reference checking, \"\n \t\t\t \"requires exact ref path\")),\ndiff --git a/t/t1403-show-ref.sh b/t/t1403-show-ref.sh\nindex 33fb7a38ff..b72ed70435 100755\n--- a/t/t1403-show-ref.sh\n+++ b/t/t1403-show-ref.sh\n@@ -121,13 +121,13 @@ test_expect_success 'show-ref -d' '\n \n '\n \n-test_expect_success 'show-ref --heads, --tags, --head, pattern' '\n+test_expect_success 'show-ref --branches, --tags, --head, pattern' '\n \tfor branch in B main side\n \tdo\n \t\techo $(git rev-parse refs/heads/$branch) refs/heads/$branch || return 1\n-\tdone >expect.heads &&\n-\tgit show-ref --heads >actual &&\n-\ttest_cmp expect.heads actual &&\n+\tdone >expect.branches &&\n+\tgit show-ref --branches >actual &&\n+\ttest_cmp expect.branches actual &&\n \n \tfor tag in A B C\n \tdo\n@@ -136,15 +136,15 @@ test_expect_success 'show-ref --heads, --tags, --head, pattern' '\n \tgit show-ref --tags >actual &&\n \ttest_cmp expect.tags actual &&\n \n-\tcat expect.heads expect.tags >expect &&\n-\tgit show-ref --heads --tags >actual &&\n+\tcat expect.branches expect.tags >expect &&\n+\tgit show-ref --branches --tags >actual &&\n \ttest_cmp expect actual &&\n \n \t{\n \t\techo $(git rev-parse HEAD) HEAD &&\n-\t\tcat expect.heads expect.tags\n+\t\tcat expect.branches expect.tags\n \t} >expect &&\n-\tgit show-ref --heads --tags --head >actual &&\n+\tgit show-ref --branches --tags --head >actual &&\n \ttest_cmp expect actual &&\n \n \t{\n@@ -165,6 +165,12 @@ test_expect_success 'show-ref --heads, --tags, --head, pattern' '\n \ttest_cmp expect actual\n '\n \n+test_expect_success 'show-ref --heads is deprecated' '\n+\tgit show-ref --heads >actual 2>warning &&\n+\ttest_grep deprecated warning &&\n+\ttest_cmp expect.branches actual\n+'\n+\n test_expect_success 'show-ref --verify HEAD' '\n \techo $(git rev-parse HEAD) HEAD >expect &&\n \tgit show-ref --verify HEAD >actual &&\n-- \n2.45.2-404-g9eaef5822c\n\n"},{"id":"496185","messageId":"aa9ff9a4-d504-45c7-8b4e-9744bf0b93aa@gmail.com","threadId":"61579","inReplyTo":"20240603200539.1473345-3-gitster@pobox.com","subject":"Re: [PATCH 2/3] ls-remote: introduce --branches and deprecate --heads","fromName":"Rubén Justo","fromEmail":"rjusto@gmail.com","sentAt":"2024-06-03T21:30:47Z","receivedAt":"2024-06-03T21:30:50Z","isPatch":true,"sender":{"key":"rjusto@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5685487?v=4"},"body":"On Mon, Jun 03, 2024 at 01:05:38PM -0700, Junio C Hamano wrote:\n> We call the tips of branches \"heads\", but this command calls the\n> option to show only branches \"--heads\", which confuses the branches\n> themselves and the tips of branches.\n> \n> Straighten the terminology by introducing \"--branches\" option that\n> limits the output to branches, and deprecate \"--heads\" option used\n> that way.\n> \n> Signed-off-by: Junio C Hamano \n> ---\n> Documentation/git-ls-remote.txt | 12 +++++++-----\n> builtin/ls-remote.c | 21 ++++++++++++++++++++-\n> t/t5512-ls-remote.sh | 30 +++++++++++++++++++++++++-----\n> 3 files changed, 52 insertions(+), 11 deletions(-)\n> \n> diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt\n> index 1c4f696ab5..76c86c3ce4 100644\n> --- a/Documentation/git-ls-remote.txt\n> +++ b/Documentation/git-ls-remote.txt\n> @@ -9,7 +9,7 @@ git-ls-remote - List references in a remote repository\n> SYNOPSIS\n> --------\n> [verse]\n> -'git ls-remote' [--heads] [--tags] [--refs] [--upload-pack=]\n> +'git ls-remote' [--branches] [--tags] [--refs] [--upload-pack=]\n> \t [-q | --quiet] [--exit-code] [--get-url] [--sort=]\n> \t [--symref] [ [...]]\n> \n> @@ -21,14 +21,16 @@ commit IDs.\n> \n> OPTIONS\n> -------\n> --h::\n> ---heads::\n> +-b::\n\nPerhaps we can avoid this 'single-letter' option, due to we're no giving\nthe same abbreviation for '--branches' in other places.\n\n> +--branches::\n> -t::\n> --tags::\n> -\tLimit to only refs/heads and refs/tags, respectively.\n> +\tLimit to only local branches and local tags, respectively.\n> \tThese options are _not_ mutually exclusive; when given\n> \tboth, references stored in refs/heads and refs/tags are\n> -\tdisplayed. Note that `git ls-remote -h` used without\n> +\tdisplayed. Note that `--heads` and `-h` are deprecated\n> +\tsynonyms for `--branches` and `-b` and may be removed in\n> +\tthe future. Also note that `git ls-remote -h` used without\n> \tanything else on the command line gives help, consistent\n> \twith other git subcommands.\n> \n> diff --git a/builtin/ls-remote.c b/builtin/ls-remote.c\n> index 9838de69c0..95fbb8b7b5 100644\n> --- a/builtin/ls-remote.c\n> +++ b/builtin/ls-remote.c\n> @@ -38,6 +38,20 @@ static int tail_match(const char **pattern, const char *path)\n> \treturn 0;\n> }\n> \n> +static int heads_callback(const struct option *opt, const char *arg, int unset)\n> +{\n> +\tunsigned *flags = opt->value;\n> +\n> +\tif (unset) {\n> +\t\twarning(_(\"'--no-heads' is deprecated; use '--no-branches' instead\"));\n\nI wonder if this would be better: \n\n\twarning(_(\"'%s' is deprecated; use '%s' instead\"), '--no-heads', '--no-branches');\n\n> +\t\t*flags &= ~REF_BRANCHES;\n> +\t} else {\n> +\t\twarning(_(\"'--heads' is deprecated; use '--branches' instead\"));\n> +\t\t*flags |= REF_BRANCHES;\n> +\t}\n> +\treturn 0;\n> +}\n> +\n> int cmd_ls_remote(int argc, const char **argv, const char *prefix)\n> {\n> \tconst char *dest = NULL;\n> @@ -68,7 +82,12 @@ int cmd_ls_remote(int argc, const char **argv, const char *prefix)\n> \t\t\t N_(\"path of git-upload-pack on the remote host\"),\n> \t\t\t PARSE_OPT_HIDDEN },\n> \t\tOPT_BIT('t', \"tags\", &flags, N_(\"limit to tags\"), REF_TAGS),\n> -\t\tOPT_BIT('h', \"heads\", &flags, N_(\"limit to heads\"), REF_BRANCHES),\n> +\t\tOPT_BIT('b', \"branches\", &flags, N_(\"limit to branches\"), REF_BRANCHES),\n> +\t\tOPT_CALLBACK_F('h', \"heads\", &flags,\n> +\t\t\t NULL,\n> +\t\t\t N_(\"deprecated synonym for --branches\"),\n> +\t\t\t PARSE_OPT_NOARG|PARSE_OPT_HIDDEN,\n> +\t\t\t &heads_callback),\n> \t\tOPT_BIT(0, \"refs\", &flags, N_(\"do not show peeled tags\"), REF_NORMAL),\n> \t\tOPT_BOOL(0, \"get-url\", &get_url,\n> \t\t\t N_(\"take url..insteadOf into account\")),\n> diff --git a/t/t5512-ls-remote.sh b/t/t5512-ls-remote.sh\n> index 5dbe107ce8..b9950ca361 100755\n> --- a/t/t5512-ls-remote.sh\n> +++ b/t/t5512-ls-remote.sh\n> @@ -47,6 +47,7 @@ test_expect_success setup '\n> \tgit show-ref -d\t>refs &&\n> \tsed -e \"s/ /\t/\" refs >>expected.all &&\n> \n> +\tgrep refs/heads/ expected.all >expected.branches &&\n> \tgit remote add self \"$(pwd)/.git\" &&\n> \tgit remote add self2 \".\"\n> '\n> @@ -71,6 +72,25 @@ test_expect_success 'ls-remote self' '\n> \ttest_cmp expected.all actual\n> '\n> \n> +test_expect_success 'ls-remote --branches self' '\n> +\tgit ls-remote --branches self >actual &&\n> +\ttest_cmp expected.branches actual &&\n> +\tgit ls-remote -b self >actual &&\n> +\ttest_cmp expected.branches actual\n> +'\n> +\n> +test_expect_success 'ls-remote -h is deprecated' '\n> +\tgit ls-remote -h self >actual 2>warning &&\n> +\ttest_cmp expected.branches actual &&\n> +\ttest_grep deprecated warning\n> +'\n> +\n> +test_expect_success 'ls-remote --heads is deprecated' '\n> +\tgit ls-remote --heads self >actual 2>warning &&\n> +\ttest_cmp expected.branches actual &&\n> +\ttest_grep deprecated warning\n> +'\n> +\n> test_expect_success 'ls-remote --sort=\"version:refname\" --tags self' '\n> \tgenerate_references \\\n> \t\trefs/tags/mark \\\n> @@ -275,7 +295,7 @@ test_expect_success 'ls-remote with filtered symref (refname)' '\n> \ttest_cmp expect actual\n> '\n> \n> -test_expect_success 'ls-remote with filtered symref (--heads)' '\n> +test_expect_success 'ls-remote with filtered symref (--branches)' '\n> \tgit symbolic-ref refs/heads/foo refs/tags/mark &&\n> \tcat >expect.v2 <<-EOF &&\n> \tref: refs/tags/mark\trefs/heads/foo\n> @@ -283,9 +303,9 @@ test_expect_success 'ls-remote with filtered symref (--heads)' '\n> \t$rev\trefs/heads/main\n> \tEOF\n> \tgrep -v \"^ref: refs/tags/\" expect.v0 &&\n> -\tgit -c protocol.version=0 ls-remote --symref --heads . >actual.v0 &&\n> +\tgit -c protocol.version=0 ls-remote --symref --branches . >actual.v0 &&\n> \ttest_cmp expect.v0 actual.v0 &&\n> -\tgit -c protocol.version=2 ls-remote --symref --heads . >actual.v2 &&\n> +\tgit -c protocol.version=2 ls-remote --symref --branches . >actual.v2 &&\n> \ttest_cmp expect.v2 actual.v2\n> '\n> \n> @@ -335,9 +355,9 @@ test_expect_success 'ls-remote patterns work with all protocol versions' '\n> test_expect_success 'ls-remote prefixes work with all protocol versions' '\n> \tgit for-each-ref --format=\"%(objectname)\t%(refname)\" \\\n> \t\trefs/heads/ refs/tags/ >expect &&\n> -\tgit -c protocol.version=0 ls-remote --heads --tags . >actual.v0 &&\n> +\tgit -c protocol.version=0 ls-remote --branches --tags . >actual.v0 &&\n> \ttest_cmp expect actual.v0 &&\n> -\tgit -c protocol.version=2 ls-remote --heads --tags . >actual.v2 &&\n> +\tgit -c protocol.version=2 ls-remote --branches --tags . >actual.v2 &&\n> \ttest_cmp expect actual.v2\n> '\n> \n> -- \n> 2.45.2-404-g9eaef5822c\n> \n"},{"id":"496186","messageId":"511c8bf6-9dea-4bac-9f9b-fd400bbad7b3@gmail.com","threadId":"61579","inReplyTo":"20240603200539.1473345-1-gitster@pobox.com","subject":"Re: [PATCH 0/3] Branches are branches and not heads","fromName":"Rubén Justo","fromEmail":"rjusto@gmail.com","sentAt":"2024-06-03T21:32:18Z","receivedAt":"2024-06-03T21:32:20Z","isPatch":true,"sender":{"key":"rjusto@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5685487?v=4"},"body":"On Mon, Jun 03, 2024 at 01:05:36PM -0700, Junio C Hamano wrote:\n> Back when Git started, we used the word \"head\" to mean the tip of\n> possibly multiple histories, and that is where the name of the\n> hierarchy .git/refs/heads/ came from. But these days we call these\n> entities \"branches\" in human terms, and \"head\" is still used to refer\n> to the tip of the history each of these branches represent.\n> \n> When asking \"git ls-remote\" or \"git show-ref\" to limit their output to\n> branches (as opposed to showing any ref), we use \"--heads\" for\n> historical reasons, but give the option a more human friendly name\n> \"--branches\", and demote \"--heads\" to the status of a deprecated\n> synonym. This would eventually allow us to remove them at the\n> breaking version boundary.\n\nAll of this sounds like a very sensible step, to me.\n\nI've left a couple of nits; none important. \n\nThanks.\n\n> \n> Junio C Hamano (3):\n> refs: call branches branches\n> ls-remote: introduce --branches and deprecate --heads\n> show-ref: introduce --branches and deprecate --heads\n> \n> Documentation/git-ls-remote.txt | 12 +++++++-----\n> Documentation/git-show-ref.txt | 18 ++++++++++--------\n> builtin/ls-remote.c | 25 ++++++++++++++++++++++---\n> builtin/show-ref.c | 33 ++++++++++++++++++++++++++-------\n> connect.c | 4 ++--\n> remote.h | 2 +-\n> t/t1403-show-ref.sh | 22 ++++++++++++++--------\n> t/t5512-ls-remote.sh | 30 +++++++++++++++++++++++++-----\n> 8 files changed, 107 insertions(+), 39 deletions(-)\n> \n> -- \n> 2.45.2-404-g9eaef5822c\n> \n"},{"id":"496187","messageId":"CAPig+cQ-kacp_4UoPPOOaZ6k6fa0cDNCYowdc1S7qJ1XteaMuQ@mail.gmail.com","threadId":"61579","inReplyTo":"20240603200539.1473345-2-gitster@pobox.com","subject":"Re: [PATCH 1/3] refs: call branches branches","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2024-06-03T21:32:08Z","receivedAt":"2024-06-03T21:32:21Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Mon, Jun 3, 2024 at 4:05 PM Junio C Hamano wrote:\n> These things in refs/heads/ hierarchy are called \"branches\" in human\n> parlance. Replace REF_HEADS with REF_BRANCHES to make it clearer.\n>\n> No end-user visible change intended at this step.\n>\n> Signed-off-by: Junio C Hamano \n> ---\n> diff --git a/builtin/ls-remote.c b/builtin/ls-remote.c\n> @@ -9,7 +9,7 @@\n> static const char * const ls_remote_usage[] = {\n> - N_(\"git ls-remote [--heads] [--tags] [--refs] [--upload-pack=]\\n\"\n> + N_(\"git ls-remote [--branches] [--tags] [--refs] [--upload-pack=]\\n\"\n> \" [-q | --quiet] [--exit-code] [--get-url] [--sort=]\\n\"\n> \" [--symref] [ [...]]\"),\n> NULL\n\nThis change belongs in patch [2/3], doesn't it, not [1/3]?\n"},{"id":"496189","messageId":"CAPig+cQGtgaz3czkg+Faj+CL_-TD0BdbEc1hg6eJuq_yZmvg9w@mail.gmail.com","threadId":"61579","inReplyTo":"aa9ff9a4-d504-45c7-8b4e-9744bf0b93aa@gmail.com","subject":"Re: [PATCH 2/3] ls-remote: introduce --branches and deprecate --heads","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2024-06-03T21:42:25Z","receivedAt":"2024-06-03T21:42:37Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Mon, Jun 3, 2024 at 5:30 PM Rubén Justo wrote:\n> On Mon, Jun 03, 2024 at 01:05:38PM -0700, Junio C Hamano wrote:\n> > + if (unset) {\n> > + warning(_(\"'--no-heads' is deprecated; use '--no-branches' instead\"));\n>\n> I wonder if this would be better:\n>\n> warning(_(\"'%s' is deprecated; use '%s' instead\"), '--no-heads', '--no-branches');\n\nUnless there is a concrete plan to free up --heads to mean something\nelse in the future, I wonder why we need to warn about this at all,\nespecially since retaining the deprecated --heads alias in perpetuity\nis effectively zero-cost for the Git maintainers, whereas adding this\nwarning potentially punishes users by making them do extra work for no\nobvious reason.\n"},{"id":"496190","messageId":"xmqqzfs11yv4.fsf@gitster.g","threadId":"61579","inReplyTo":"CAPig+cQGtgaz3czkg+Faj+CL_-TD0BdbEc1hg6eJuq_yZmvg9w@mail.gmail.com","subject":"Re: [PATCH 2/3] ls-remote: introduce --branches and deprecate --heads","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-06-03T21:48:47Z","receivedAt":"2024-06-03T21:48:52Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Eric Sunshine writes:\n\n> Unless there is a concrete plan to free up --heads to mean something\n> else in the future, I wonder why we need to warn about this at all,\n\nThere is no plan to repurpose \"--heads\", but this is primarily to\nmake sure \"-h\" cannot mean anything but \"please give me a short\nhelp\".\n\n"},{"id":"496208","messageId":"Zl7Ina9Uldi1jyMd@framework","threadId":"61579","inReplyTo":"511c8bf6-9dea-4bac-9f9b-fd400bbad7b3@gmail.com","subject":"Re: [PATCH 0/3] Branches are branches and not heads","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-06-04T07:56:13Z","receivedAt":"2024-06-04T07:56:20Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Mon, Jun 03, 2024 at 11:32:18PM +0200, Rubén Justo wrote:\n> On Mon, Jun 03, 2024 at 01:05:36PM -0700, Junio C Hamano wrote:\n> > Back when Git started, we used the word \"head\" to mean the tip of\n> > possibly multiple histories, and that is where the name of the\n> > hierarchy .git/refs/heads/ came from. But these days we call these\n> > entities \"branches\" in human terms, and \"head\" is still used to refer\n> > to the tip of the history each of these branches represent.\n> > \n> > When asking \"git ls-remote\" or \"git show-ref\" to limit their output to\n> > branches (as opposed to showing any ref), we use \"--heads\" for\n> > historical reasons, but give the option a more human friendly name\n> > \"--branches\", and demote \"--heads\" to the status of a deprecated\n> > synonym. This would eventually allow us to remove them at the\n> > breaking version boundary.\n> \n> All of this sounds like a very sensible step, to me.\n> \n> I've left a couple of nits; none important. \n\nAgreed, I like the direction of this patch series very much. I've got\nnothing to add on top of what has already been said.\n\nThanks!\n\nPatrick\n"},{"id":"496313","messageId":"20240604220145.3260714-1-gitster@pobox.com","threadId":"61579","inReplyTo":"20240603200539.1473345-1-gitster@pobox.com","subject":"[PATCH v2 0/3] Branches are branches and not heads","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-06-04T22:01:42Z","receivedAt":"2024-06-04T22:01:49Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"tl;dr for those who did read v1: v2 does not warn when deprecated\nvariants are used.\n----------------------\n\nBack when Git started, we used the word \"head\" to mean the tip of\npossibly multiple histories, and that is where the name of the\nhierarchy .git/refs/heads/ came from. But these days we call these\nentities \"branches\" in human terms, and \"head\" is still used to\nrefer to the tip of the history each of these branches represent.\n\nWhen asking \"git ls-remote\" or \"git show-ref\" to limit their output\nto branches (as opposed to showing any ref), we use \"--heads\" for\nhistorical reasons, but give the option a more human friendly name\n\"--branches\", and demote \"--heads\" to the status of a deprecated\nsynonym. \n\nWe do not plan to remove \"--heads\" or \"-h\" yet, but we may want to\ndo so at the Git 3.0 boundary, in which case we will need to start\nadvertising upcoming removal with an extra warning when they are\nused. But let's not start annoying users for now.\n\nJunio C Hamano (3):\n refs: call branches branches\n ls-remote: introduce --branches and deprecate --heads\n show-ref: introduce --branches and deprecate --heads\n\n Documentation/git-ls-remote.txt | 12 +++++++-----\n Documentation/git-show-ref.txt | 18 ++++++++++--------\n builtin/ls-remote.c | 9 ++++++---\n builtin/show-ref.c | 16 +++++++++-------\n connect.c | 4 ++--\n remote.h | 2 +-\n t/t1403-show-ref.sh | 24 ++++++++++++++++--------\n t/t5512-ls-remote.sh | 32 +++++++++++++++++++++++++++-----\n 8 files changed, 78 insertions(+), 39 deletions(-)\n\nRange-diff against v1:\n1: 2c551ed37b = 1: 2c551ed37b refs: call branches branches\n2: f88fe89ff7 ! 2: 5549e98042 ls-remote: introduce --branches and deprecate --heads\n @@ Commit message\n limits the output to branches, and deprecate \"--heads\" option used\n that way.\n \n + We do not plan to remove \"--heads\" or \"-h\" yet; we may want to do so\n + at Git 3.0, in which case, we may need to start advertising upcoming\n + removal with an extra warning when they are used.\n +\n Signed-off-by: Junio C Hamano \n \n ## Documentation/git-ls-remote.txt ##\n @@ builtin/ls-remote.c\n \t \" [-q | --quiet] [--exit-code] [--get-url] [--sort=]\\n\"\n \t \" [--symref] [ [...]]\"),\n \tNULL\n -@@ builtin/ls-remote.c: static int tail_match(const char **pattern, const char *path)\n - \treturn 0;\n - }\n - \n -+static int heads_callback(const struct option *opt, const char *arg, int unset)\n -+{\n -+\tunsigned *flags = opt->value;\n -+\n -+\tif (unset) {\n -+\t\twarning(_(\"'--no-heads' is deprecated; use '--no-branches' instead\"));\n -+\t\t*flags &= ~REF_BRANCHES;\n -+\t} else {\n -+\t\twarning(_(\"'--heads' is deprecated; use '--branches' instead\"));\n -+\t\t*flags |= REF_BRANCHES;\n -+\t}\n -+\treturn 0;\n -+}\n -+\n - int cmd_ls_remote(int argc, const char **argv, const char *prefix)\n - {\n - \tconst char *dest = NULL;\n @@ builtin/ls-remote.c: int cmd_ls_remote(int argc, const char **argv, const char *prefix)\n \t\t\t N_(\"path of git-upload-pack on the remote host\"),\n \t\t\t PARSE_OPT_HIDDEN },\n \t\tOPT_BIT('t', \"tags\", &flags, N_(\"limit to tags\"), REF_TAGS),\n -\t\tOPT_BIT('h', \"heads\", &flags, N_(\"limit to heads\"), REF_BRANCHES),\n +\t\tOPT_BIT('b', \"branches\", &flags, N_(\"limit to branches\"), REF_BRANCHES),\n -+\t\tOPT_CALLBACK_F('h', \"heads\", &flags,\n -+\t\t\t NULL,\n -+\t\t\t N_(\"deprecated synonym for --branches\"),\n -+\t\t\t PARSE_OPT_NOARG|PARSE_OPT_HIDDEN,\n -+\t\t\t &heads_callback),\n ++\t\tOPT_BIT_F('h', \"heads\", &flags,\n ++\t\t\t N_(\"deprecated synonym for --branches\"), REF_BRANCHES,\n ++\t\t\t PARSE_OPT_HIDDEN),\n \t\tOPT_BIT(0, \"refs\", &flags, N_(\"do not show peeled tags\"), REF_NORMAL),\n \t\tOPT_BOOL(0, \"get-url\", &get_url,\n \t\t\t N_(\"take url..insteadOf into account\")),\n @@ t/t5512-ls-remote.sh: test_expect_success 'ls-remote self' '\n +\ttest_cmp expected.branches actual\n +'\n +\n -+test_expect_success 'ls-remote -h is deprecated' '\n ++test_expect_success 'ls-remote -h is deprecated w/o warning' '\n +\tgit ls-remote -h self >actual 2>warning &&\n +\ttest_cmp expected.branches actual &&\n -+\ttest_grep deprecated warning\n ++\ttest_grep ! deprecated warning\n +'\n +\n -+test_expect_success 'ls-remote --heads is deprecated' '\n ++test_expect_success 'ls-remote --heads is deprecated and hidden w/o warning' '\n ++\ttest_expect_code 129 git ls-remote -h >short-help &&\n ++\ttest_grep ! -e --head short-help &&\n +\tgit ls-remote --heads self >actual 2>warning &&\n +\ttest_cmp expected.branches actual &&\n -+\ttest_grep deprecated warning\n ++\ttest_grep ! deprecated warning\n +'\n +\n test_expect_success 'ls-remote --sort=\"version:refname\" --tags self' '\n3: 295554edfc ! 3: 9022743a32 show-ref: introduce --branches and deprecate --heads\n @@ Commit message\n limits the output to branches, and deprecate \"--heads\" option used\n that way.\n \n + We do not plan to remove \"--heads\" or \"-h\" yet; we may want to do so\n + at Git 3.0, in which case, we may need to start advertising upcoming\n + removal with an extra warning when they are used.\n +\n Signed-off-by: Junio C Hamano \n \n ## Documentation/git-show-ref.txt ##\n @@ builtin/show-ref.c: static int cmd_show_ref__patterns(const struct patterns_opti\n \t\t\tfor_each_fullref_in(\"refs/heads/\", show_ref, &show_ref_data);\n \t\tif (opts->tags_only)\n \t\t\tfor_each_fullref_in(\"refs/tags/\", show_ref, &show_ref_data);\n -@@ builtin/show-ref.c: static int exclude_existing_callback(const struct option *opt, const char *arg,\n - \treturn 0;\n - }\n - \n -+static int heads_callback(const struct option *opt, const char *arg, int unset)\n -+{\n -+\tint *branches_only = opt->value;\n -+\n -+\tif (unset) {\n -+\t\twarning(_(\"'--no-heads' is deprecated; use '--no-branches' instead\"));\n -+\t\t*branches_only = 0;\n -+\t} else {\n -+\t\twarning(_(\"'--heads' is deprecated; use '--branches' instead\"));\n -+\t\t*branches_only = 1;\n -+\t}\n -+\treturn 0;\n -+}\n -+\n - int cmd_show_ref(int argc, const char **argv, const char *prefix)\n - {\n - \tstruct exclude_existing_options exclude_existing_opts = {0};\n @@ builtin/show-ref.c: int cmd_show_ref(int argc, const char **argv, const char *prefix)\n \tstruct show_one_options show_one_opts = {0};\n \tint verify = 0, exists = 0;\n @@ builtin/show-ref.c: int cmd_show_ref(int argc, const char **argv, const char *pr\n -\t\tOPT_BOOL(0, \"heads\", &patterns_opts.heads_only, N_(\"only show heads (can be combined with tags)\")),\n +\t\tOPT_BOOL(0, \"tags\", &patterns_opts.tags_only, N_(\"only show tags (can be combined with branches)\")),\n +\t\tOPT_BOOL(0, \"branches\", &patterns_opts.branches_only, N_(\"only show branches (can be combined with tags)\")),\n -+\t\tOPT_CALLBACK_F(0, \"heads\", &patterns_opts.branches_only,\n -+\t\t\t NULL,\n -+\t\t\t N_(\"deprecated synonym for --branches)\"),\n -+\t\t\t PARSE_OPT_NOARG|PARSE_OPT_HIDDEN,\n -+\t\t\t &heads_callback),\n ++\t\tOPT_HIDDEN_BOOL(0, \"heads\", &patterns_opts.branches_only,\n ++\t\t\t\tN_(\"deprecated synonym for --branches\")),\n \t\tOPT_BOOL(0, \"exists\", &exists, N_(\"check for reference existence without resolving\")),\n \t\tOPT_BOOL(0, \"verify\", &verify, N_(\"stricter reference checking, \"\n \t\t\t \"requires exact ref path\")),\n @@ t/t1403-show-ref.sh: test_expect_success 'show-ref --heads, --tags, --head, patt\n \ttest_cmp expect actual\n '\n \n -+test_expect_success 'show-ref --heads is deprecated' '\n ++test_expect_success 'show-ref --heads is deprecated and hidden' '\n ++\ttest_expect_code 129 git show-ref -h >short-help &&\n ++\ttest_grep ! -e --heads short-help &&\n +\tgit show-ref --heads >actual 2>warning &&\n -+\ttest_grep deprecated warning &&\n ++\ttest_grep ! deprecated warning &&\n +\ttest_cmp expect.branches actual\n +'\n +\n-- \n2.45.2-409-g7b0defb391\n\n"},{"id":"496314","messageId":"20240604220145.3260714-2-gitster@pobox.com","threadId":"61579","inReplyTo":"20240604220145.3260714-1-gitster@pobox.com","subject":"[PATCH v2 1/3] refs: call branches branches","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-06-04T22:01:43Z","receivedAt":"2024-06-04T22:01:52Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"These things in refs/heads/ hierarchy are called \"branches\" in human\nparlance. Replace REF_HEADS with REF_BRANCHES to make it clearer.\n\nNo end-user visible change intended at this step.\n\nSigned-off-by: Junio C Hamano \n---\n builtin/ls-remote.c | 4 ++--\n connect.c | 4 ++--\n remote.h | 2 +-\n 3 files changed, 5 insertions(+), 5 deletions(-)\n\ndiff --git a/builtin/ls-remote.c b/builtin/ls-remote.c\nindex e8d65ebbdc..65fb22a8a2 100644\n--- a/builtin/ls-remote.c\n+++ b/builtin/ls-remote.c\n@@ -68,7 +68,7 @@ int cmd_ls_remote(int argc, const char **argv, const char *prefix)\n \t\t\t N_(\"path of git-upload-pack on the remote host\"),\n \t\t\t PARSE_OPT_HIDDEN },\n \t\tOPT_BIT('t', \"tags\", &flags, N_(\"limit to tags\"), REF_TAGS),\n-\t\tOPT_BIT('h', \"heads\", &flags, N_(\"limit to heads\"), REF_HEADS),\n+\t\tOPT_BIT('h', \"heads\", &flags, N_(\"limit to heads\"), REF_BRANCHES),\n \t\tOPT_BIT(0, \"refs\", &flags, N_(\"do not show peeled tags\"), REF_NORMAL),\n \t\tOPT_BOOL(0, \"get-url\", &get_url,\n \t\t\t N_(\"take url..insteadOf into account\")),\n@@ -100,7 +100,7 @@ int cmd_ls_remote(int argc, const char **argv, const char *prefix)\n \n \tif (flags & REF_TAGS)\n \t\tstrvec_push(&transport_options.ref_prefixes, \"refs/tags/\");\n-\tif (flags & REF_HEADS)\n+\tif (flags & REF_BRANCHES)\n \t\tstrvec_push(&transport_options.ref_prefixes, \"refs/heads/\");\n \n \tremote = remote_get(dest);\ndiff --git a/connect.c b/connect.c\nindex 0d77737a53..cf84e631e9 100644\n--- a/connect.c\n+++ b/connect.c\n@@ -38,8 +38,8 @@ static int check_ref(const char *name, unsigned int flags)\n \t\t\t\t\t\t\t REFNAME_ALLOW_ONELEVEL))\n \t\treturn 0;\n \n-\t/* REF_HEADS means that we want regular branch heads */\n-\tif ((flags & REF_HEADS) && starts_with(name, \"heads/\"))\n+\t/* REF_BRANCHES means that we want regular branch heads */\n+\tif ((flags & REF_BRANCHES) && starts_with(name, \"heads/\"))\n \t\treturn 1;\n \n \t/* REF_TAGS means that we want tags */\ndiff --git a/remote.h b/remote.h\nindex dfd4837e60..02e330f42c 100644\n--- a/remote.h\n+++ b/remote.h\n@@ -200,7 +200,7 @@ struct ref {\n };\n \n #define REF_NORMAL\t(1u << 0)\n-#define REF_HEADS\t(1u << 1)\n+#define REF_BRANCHES\t(1u << 1)\n #define REF_TAGS\t(1u << 2)\n \n struct ref *find_ref_by_name(const struct ref *list, const char *name);\n-- \n2.45.2-409-g7b0defb391\n\n"},{"id":"496315","messageId":"20240604220145.3260714-3-gitster@pobox.com","threadId":"61579","inReplyTo":"20240604220145.3260714-1-gitster@pobox.com","subject":"[PATCH v2 2/3] ls-remote: introduce --branches and deprecate --heads","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-06-04T22:01:44Z","receivedAt":"2024-06-04T22:01:54Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"We call the tips of branches \"heads\", but this command calls the\noption to show only branches \"--heads\", which confuses the branches\nthemselves and the tips of branches.\n\nStraighten the terminology by introducing \"--branches\" option that\nlimits the output to branches, and deprecate \"--heads\" option used\nthat way.\n\nWe do not plan to remove \"--heads\" or \"-h\" yet; we may want to do so\nat Git 3.0, in which case, we may need to start advertising upcoming\nremoval with an extra warning when they are used.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/git-ls-remote.txt | 12 +++++++-----\n builtin/ls-remote.c | 7 +++++--\n t/t5512-ls-remote.sh | 32 +++++++++++++++++++++++++++-----\n 3 files changed, 39 insertions(+), 12 deletions(-)\n\ndiff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt\nindex 1c4f696ab5..76c86c3ce4 100644\n--- a/Documentation/git-ls-remote.txt\n+++ b/Documentation/git-ls-remote.txt\n@@ -9,7 +9,7 @@ git-ls-remote - List references in a remote repository\n SYNOPSIS\n --------\n [verse]\n-'git ls-remote' [--heads] [--tags] [--refs] [--upload-pack=]\n+'git ls-remote' [--branches] [--tags] [--refs] [--upload-pack=]\n \t [-q | --quiet] [--exit-code] [--get-url] [--sort=]\n \t [--symref] [ [...]]\n \n@@ -21,14 +21,16 @@ commit IDs.\n \n OPTIONS\n -------\n--h::\n---heads::\n+-b::\n+--branches::\n -t::\n --tags::\n-\tLimit to only refs/heads and refs/tags, respectively.\n+\tLimit to only local branches and local tags, respectively.\n \tThese options are _not_ mutually exclusive; when given\n \tboth, references stored in refs/heads and refs/tags are\n-\tdisplayed. Note that `git ls-remote -h` used without\n+\tdisplayed. Note that `--heads` and `-h` are deprecated\n+\tsynonyms for `--branches` and `-b` and may be removed in\n+\tthe future. Also note that `git ls-remote -h` used without\n \tanything else on the command line gives help, consistent\n \twith other git subcommands.\n \ndiff --git a/builtin/ls-remote.c b/builtin/ls-remote.c\nindex 65fb22a8a2..69841ed49f 100644\n--- a/builtin/ls-remote.c\n+++ b/builtin/ls-remote.c\n@@ -9,7 +9,7 @@\n #include \"wildmatch.h\"\n \n static const char * const ls_remote_usage[] = {\n-\tN_(\"git ls-remote [--heads] [--tags] [--refs] [--upload-pack=]\\n\"\n+\tN_(\"git ls-remote [--branches] [--tags] [--refs] [--upload-pack=]\\n\"\n \t \" [-q | --quiet] [--exit-code] [--get-url] [--sort=]\\n\"\n \t \" [--symref] [ [...]]\"),\n \tNULL\n@@ -68,7 +68,10 @@ int cmd_ls_remote(int argc, const char **argv, const char *prefix)\n \t\t\t N_(\"path of git-upload-pack on the remote host\"),\n \t\t\t PARSE_OPT_HIDDEN },\n \t\tOPT_BIT('t', \"tags\", &flags, N_(\"limit to tags\"), REF_TAGS),\n-\t\tOPT_BIT('h', \"heads\", &flags, N_(\"limit to heads\"), REF_BRANCHES),\n+\t\tOPT_BIT('b', \"branches\", &flags, N_(\"limit to branches\"), REF_BRANCHES),\n+\t\tOPT_BIT_F('h', \"heads\", &flags,\n+\t\t\t N_(\"deprecated synonym for --branches\"), REF_BRANCHES,\n+\t\t\t PARSE_OPT_HIDDEN),\n \t\tOPT_BIT(0, \"refs\", &flags, N_(\"do not show peeled tags\"), REF_NORMAL),\n \t\tOPT_BOOL(0, \"get-url\", &get_url,\n \t\t\t N_(\"take url..insteadOf into account\")),\ndiff --git a/t/t5512-ls-remote.sh b/t/t5512-ls-remote.sh\nindex 5dbe107ce8..42e77eb5a9 100755\n--- a/t/t5512-ls-remote.sh\n+++ b/t/t5512-ls-remote.sh\n@@ -47,6 +47,7 @@ test_expect_success setup '\n \tgit show-ref -d\t>refs &&\n \tsed -e \"s/ /\t/\" refs >>expected.all &&\n \n+\tgrep refs/heads/ expected.all >expected.branches &&\n \tgit remote add self \"$(pwd)/.git\" &&\n \tgit remote add self2 \".\"\n '\n@@ -71,6 +72,27 @@ test_expect_success 'ls-remote self' '\n \ttest_cmp expected.all actual\n '\n \n+test_expect_success 'ls-remote --branches self' '\n+\tgit ls-remote --branches self >actual &&\n+\ttest_cmp expected.branches actual &&\n+\tgit ls-remote -b self >actual &&\n+\ttest_cmp expected.branches actual\n+'\n+\n+test_expect_success 'ls-remote -h is deprecated w/o warning' '\n+\tgit ls-remote -h self >actual 2>warning &&\n+\ttest_cmp expected.branches actual &&\n+\ttest_grep ! deprecated warning\n+'\n+\n+test_expect_success 'ls-remote --heads is deprecated and hidden w/o warning' '\n+\ttest_expect_code 129 git ls-remote -h >short-help &&\n+\ttest_grep ! -e --head short-help &&\n+\tgit ls-remote --heads self >actual 2>warning &&\n+\ttest_cmp expected.branches actual &&\n+\ttest_grep ! deprecated warning\n+'\n+\n test_expect_success 'ls-remote --sort=\"version:refname\" --tags self' '\n \tgenerate_references \\\n \t\trefs/tags/mark \\\n@@ -275,7 +297,7 @@ test_expect_success 'ls-remote with filtered symref (refname)' '\n \ttest_cmp expect actual\n '\n \n-test_expect_success 'ls-remote with filtered symref (--heads)' '\n+test_expect_success 'ls-remote with filtered symref (--branches)' '\n \tgit symbolic-ref refs/heads/foo refs/tags/mark &&\n \tcat >expect.v2 <<-EOF &&\n \tref: refs/tags/mark\trefs/heads/foo\n@@ -283,9 +305,9 @@ test_expect_success 'ls-remote with filtered symref (--heads)' '\n \t$rev\trefs/heads/main\n \tEOF\n \tgrep -v \"^ref: refs/tags/\" expect.v0 &&\n-\tgit -c protocol.version=0 ls-remote --symref --heads . >actual.v0 &&\n+\tgit -c protocol.version=0 ls-remote --symref --branches . >actual.v0 &&\n \ttest_cmp expect.v0 actual.v0 &&\n-\tgit -c protocol.version=2 ls-remote --symref --heads . >actual.v2 &&\n+\tgit -c protocol.version=2 ls-remote --symref --branches . >actual.v2 &&\n \ttest_cmp expect.v2 actual.v2\n '\n \n@@ -335,9 +357,9 @@ test_expect_success 'ls-remote patterns work with all protocol versions' '\n test_expect_success 'ls-remote prefixes work with all protocol versions' '\n \tgit for-each-ref --format=\"%(objectname)\t%(refname)\" \\\n \t\trefs/heads/ refs/tags/ >expect &&\n-\tgit -c protocol.version=0 ls-remote --heads --tags . >actual.v0 &&\n+\tgit -c protocol.version=0 ls-remote --branches --tags . >actual.v0 &&\n \ttest_cmp expect actual.v0 &&\n-\tgit -c protocol.version=2 ls-remote --heads --tags . >actual.v2 &&\n+\tgit -c protocol.version=2 ls-remote --branches --tags . >actual.v2 &&\n \ttest_cmp expect actual.v2\n '\n \n-- \n2.45.2-409-g7b0defb391\n\n"},{"id":"496316","messageId":"20240604220145.3260714-4-gitster@pobox.com","threadId":"61579","inReplyTo":"20240604220145.3260714-1-gitster@pobox.com","subject":"[PATCH v2 3/3] show-ref: introduce --branches and deprecate --heads","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-06-04T22:01:45Z","receivedAt":"2024-06-04T22:01:57Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"We call the tips of branches \"heads\", but this command calls the\noption to show only branches \"--heads\", which confuses the branches\nthemselves and the tips of branches.\n\nStraighten the terminology by introducing \"--branches\" option that\nlimits the output to branches, and deprecate \"--heads\" option used\nthat way.\n\nWe do not plan to remove \"--heads\" or \"-h\" yet; we may want to do so\nat Git 3.0, in which case, we may need to start advertising upcoming\nremoval with an extra warning when they are used.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/git-show-ref.txt | 18 ++++++++++--------\n builtin/show-ref.c | 16 +++++++++-------\n t/t1403-show-ref.sh | 24 ++++++++++++++++--------\n 3 files changed, 35 insertions(+), 23 deletions(-)\n\ndiff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt\nindex ba75747005..616d919655 100644\n--- a/Documentation/git-show-ref.txt\n+++ b/Documentation/git-show-ref.txt\n@@ -9,8 +9,8 @@ SYNOPSIS\n --------\n [verse]\n 'git show-ref' [--head] [-d | --dereference]\n-\t [-s | --hash[=]] [--abbrev[=]] [--tags]\n-\t [--heads] [--] [...]\n+\t [-s | --hash[=]] [--abbrev[=]] [--branches] [--tags]\n+\t [--] [...]\n 'git show-ref' --verify [-q | --quiet] [-d | --dereference]\n \t [-s | --hash[=]] [--abbrev[=]]\n \t [--] [...]\n@@ -45,12 +45,14 @@ OPTIONS\n \n \tShow the HEAD reference, even if it would normally be filtered out.\n \n---heads::\n+--branches::\n --tags::\n \n-\tLimit to \"refs/heads\" and \"refs/tags\", respectively. These options\n+\tLimit to local branches and local tags, respectively. These options\n \tare not mutually exclusive; when given both, references stored in\n-\t\"refs/heads\" and \"refs/tags\" are displayed.\n+\t\"refs/heads\" and \"refs/tags\" are displayed. Note that `--heads`\n+\tis a deprecated synonym for `--branches` and may be removed\n+\tin the future.\n \n -d::\n --dereference::\n@@ -139,7 +141,7 @@ When using `--hash` (and not `--dereference`), the output is in the format:\n For example,\n \n -----------------------------------------------------------------------------\n-$ git show-ref --heads --hash\n+$ git show-ref --branches --hash\n 2e3ba0114a1f52b47df29743d6915d056be13278\n 185008ae97960c8d551adcd9e23565194651b5d1\n 03adf42c988195b50e1a1935ba5fcbc39b2b029b\n@@ -183,8 +185,8 @@ to check whether a particular branch exists or not (notice how we don't\n actually want to show any results, and we want to use the full refname for it\n in order to not trigger the problem with ambiguous partial matches).\n \n-To show only tags, or only proper branch heads, use `--tags` and/or `--heads`\n-respectively (using both means that it shows tags and heads, but not other\n+To show only tags, or only proper branch heads, use `--tags` and/or `--branches`\n+respectively (using both means that it shows tags and branches, but not other\n random references under the refs/ subdirectory).\n \n To do automatic tag object dereferencing, use the `-d` or `--dereference`\ndiff --git a/builtin/show-ref.c b/builtin/show-ref.c\nindex 1c15421e60..f634bc3e44 100644\n--- a/builtin/show-ref.c\n+++ b/builtin/show-ref.c\n@@ -11,8 +11,8 @@\n \n static const char * const show_ref_usage[] = {\n \tN_(\"git show-ref [--head] [-d | --dereference]\\n\"\n-\t \" [-s | --hash[=]] [--abbrev[=]] [--tags]\\n\"\n-\t \" [--heads] [--] [...]\"),\n+\t \" [-s | --hash[=]] [--abbrev[=]] [--branches] [--tags]\\n\"\n+\t \" [--] [...]\"),\n \tN_(\"git show-ref --verify [-q | --quiet] [-d | --dereference]\\n\"\n \t \" [-s | --hash[=]] [--abbrev[=]]\\n\"\n \t \" [--] [...]\"),\n@@ -188,7 +188,7 @@ static int cmd_show_ref__verify(const struct show_one_options *show_one_opts,\n \n struct patterns_options {\n \tint show_head;\n-\tint heads_only;\n+\tint branches_only;\n \tint tags_only;\n };\n \n@@ -206,8 +206,8 @@ static int cmd_show_ref__patterns(const struct patterns_options *opts,\n \n \tif (opts->show_head)\n \t\thead_ref(show_ref, &show_ref_data);\n-\tif (opts->heads_only || opts->tags_only) {\n-\t\tif (opts->heads_only)\n+\tif (opts->branches_only || opts->tags_only) {\n+\t\tif (opts->branches_only)\n \t\t\tfor_each_fullref_in(\"refs/heads/\", show_ref, &show_ref_data);\n \t\tif (opts->tags_only)\n \t\t\tfor_each_fullref_in(\"refs/tags/\", show_ref, &show_ref_data);\n@@ -286,8 +286,10 @@ int cmd_show_ref(int argc, const char **argv, const char *prefix)\n \tstruct show_one_options show_one_opts = {0};\n \tint verify = 0, exists = 0;\n \tconst struct option show_ref_options[] = {\n-\t\tOPT_BOOL(0, \"tags\", &patterns_opts.tags_only, N_(\"only show tags (can be combined with heads)\")),\n-\t\tOPT_BOOL(0, \"heads\", &patterns_opts.heads_only, N_(\"only show heads (can be combined with tags)\")),\n+\t\tOPT_BOOL(0, \"tags\", &patterns_opts.tags_only, N_(\"only show tags (can be combined with branches)\")),\n+\t\tOPT_BOOL(0, \"branches\", &patterns_opts.branches_only, N_(\"only show branches (can be combined with tags)\")),\n+\t\tOPT_HIDDEN_BOOL(0, \"heads\", &patterns_opts.branches_only,\n+\t\t\t\tN_(\"deprecated synonym for --branches\")),\n \t\tOPT_BOOL(0, \"exists\", &exists, N_(\"check for reference existence without resolving\")),\n \t\tOPT_BOOL(0, \"verify\", &verify, N_(\"stricter reference checking, \"\n \t\t\t \"requires exact ref path\")),\ndiff --git a/t/t1403-show-ref.sh b/t/t1403-show-ref.sh\nindex 33fb7a38ff..403f6b8f7d 100755\n--- a/t/t1403-show-ref.sh\n+++ b/t/t1403-show-ref.sh\n@@ -121,13 +121,13 @@ test_expect_success 'show-ref -d' '\n \n '\n \n-test_expect_success 'show-ref --heads, --tags, --head, pattern' '\n+test_expect_success 'show-ref --branches, --tags, --head, pattern' '\n \tfor branch in B main side\n \tdo\n \t\techo $(git rev-parse refs/heads/$branch) refs/heads/$branch || return 1\n-\tdone >expect.heads &&\n-\tgit show-ref --heads >actual &&\n-\ttest_cmp expect.heads actual &&\n+\tdone >expect.branches &&\n+\tgit show-ref --branches >actual &&\n+\ttest_cmp expect.branches actual &&\n \n \tfor tag in A B C\n \tdo\n@@ -136,15 +136,15 @@ test_expect_success 'show-ref --heads, --tags, --head, pattern' '\n \tgit show-ref --tags >actual &&\n \ttest_cmp expect.tags actual &&\n \n-\tcat expect.heads expect.tags >expect &&\n-\tgit show-ref --heads --tags >actual &&\n+\tcat expect.branches expect.tags >expect &&\n+\tgit show-ref --branches --tags >actual &&\n \ttest_cmp expect actual &&\n \n \t{\n \t\techo $(git rev-parse HEAD) HEAD &&\n-\t\tcat expect.heads expect.tags\n+\t\tcat expect.branches expect.tags\n \t} >expect &&\n-\tgit show-ref --heads --tags --head >actual &&\n+\tgit show-ref --branches --tags --head >actual &&\n \ttest_cmp expect actual &&\n \n \t{\n@@ -165,6 +165,14 @@ test_expect_success 'show-ref --heads, --tags, --head, pattern' '\n \ttest_cmp expect actual\n '\n \n+test_expect_success 'show-ref --heads is deprecated and hidden' '\n+\ttest_expect_code 129 git show-ref -h >short-help &&\n+\ttest_grep ! -e --heads short-help &&\n+\tgit show-ref --heads >actual 2>warning &&\n+\ttest_grep ! deprecated warning &&\n+\ttest_cmp expect.branches actual\n+'\n+\n test_expect_success 'show-ref --verify HEAD' '\n \techo $(git rev-parse HEAD) HEAD >expect &&\n \tgit show-ref --verify HEAD >actual &&\n-- \n2.45.2-409-g7b0defb391\n\n"},{"id":"496473","messageId":"ZmGDuThKIbexY-xa@tanuki","threadId":"61579","inReplyTo":"20240604220145.3260714-3-gitster@pobox.com","subject":"Re: [PATCH v2 2/3] ls-remote: introduce --branches and deprecate --heads","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-06-06T09:39:05Z","receivedAt":"2024-06-06T09:39:10Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Tue, Jun 04, 2024 at 03:01:44PM -0700, Junio C Hamano wrote:\n> diff --git a/builtin/ls-remote.c b/builtin/ls-remote.c\n> index 65fb22a8a2..69841ed49f 100644\n> --- a/builtin/ls-remote.c\n> +++ b/builtin/ls-remote.c\n> @@ -9,7 +9,7 @@\n> #include \"wildmatch.h\"\n> \n> static const char * const ls_remote_usage[] = {\n> -\tN_(\"git ls-remote [--heads] [--tags] [--refs] [--upload-pack=]\\n\"\n> +\tN_(\"git ls-remote [--branches] [--tags] [--refs] [--upload-pack=]\\n\"\n> \t \" [-q | --quiet] [--exit-code] [--get-url] [--sort=]\\n\"\n> \t \" [--symref] [ [...]]\"),\n> \tNULL\n> @@ -68,7 +68,10 @@ int cmd_ls_remote(int argc, const char **argv, const char *prefix)\n> \t\t\t N_(\"path of git-upload-pack on the remote host\"),\n> \t\t\t PARSE_OPT_HIDDEN },\n> \t\tOPT_BIT('t', \"tags\", &flags, N_(\"limit to tags\"), REF_TAGS),\n> -\t\tOPT_BIT('h', \"heads\", &flags, N_(\"limit to heads\"), REF_BRANCHES),\n> +\t\tOPT_BIT('b', \"branches\", &flags, N_(\"limit to branches\"), REF_BRANCHES),\n> +\t\tOPT_BIT_F('h', \"heads\", &flags,\n> +\t\t\t N_(\"deprecated synonym for --branches\"), REF_BRANCHES,\n> +\t\t\t PARSE_OPT_HIDDEN),\n> \t\tOPT_BIT(0, \"refs\", &flags, N_(\"do not show peeled tags\"), REF_NORMAL),\n> \t\tOPT_BOOL(0, \"get-url\", &get_url,\n> \t\t\t N_(\"take url..insteadOf into account\")),\n> diff --git a/t/t5512-ls-remote.sh b/t/t5512-ls-remote.sh\n> index 5dbe107ce8..42e77eb5a9 100755\n> --- a/t/t5512-ls-remote.sh\n> +++ b/t/t5512-ls-remote.sh\n> @@ -47,6 +47,7 @@ test_expect_success setup '\n> \tgit show-ref -d\t>refs &&\n> \tsed -e \"s/ /\t/\" refs >>expected.all &&\n> \n> +\tgrep refs/heads/ expected.all >expected.branches &&\n> \tgit remote add self \"$(pwd)/.git\" &&\n> \tgit remote add self2 \".\"\n> '\n> @@ -71,6 +72,27 @@ test_expect_success 'ls-remote self' '\n> \ttest_cmp expected.all actual\n> '\n> \n> +test_expect_success 'ls-remote --branches self' '\n> +\tgit ls-remote --branches self >actual &&\n> +\ttest_cmp expected.branches actual &&\n> +\tgit ls-remote -b self >actual &&\n> +\ttest_cmp expected.branches actual\n> +'\n> +\n> +test_expect_success 'ls-remote -h is deprecated w/o warning' '\n> +\tgit ls-remote -h self >actual 2>warning &&\n> +\ttest_cmp expected.branches actual &&\n> +\ttest_grep ! deprecated warning\n> +'\n\nIt is a bit funny to grep for something that wasn't ever there. But I\ndon't mind it much as we may eventually want to introduce such a\ndeprecation warning if we ever decide to go through with the\ndeprecation.\n\nPatrick\n"},{"id":"496474","messageId":"ZmGDvtZKHdkVD6qL@tanuki","threadId":"61579","inReplyTo":"20240604220145.3260714-1-gitster@pobox.com","subject":"Re: [PATCH v2 0/3] Branches are branches and not heads","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-06-06T09:39:10Z","receivedAt":"2024-06-06T09:39:14Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Tue, Jun 04, 2024 at 03:01:42PM -0700, Junio C Hamano wrote:\n> tl;dr for those who did read v1: v2 does not warn when deprecated\n> variants are used.\n> ----------------------\n> \n> Back when Git started, we used the word \"head\" to mean the tip of\n> possibly multiple histories, and that is where the name of the\n> hierarchy .git/refs/heads/ came from. But these days we call these\n> entities \"branches\" in human terms, and \"head\" is still used to\n> refer to the tip of the history each of these branches represent.\n> \n> When asking \"git ls-remote\" or \"git show-ref\" to limit their output\n> to branches (as opposed to showing any ref), we use \"--heads\" for\n> historical reasons, but give the option a more human friendly name\n> \"--branches\", and demote \"--heads\" to the status of a deprecated\n> synonym. \n> \n> We do not plan to remove \"--heads\" or \"-h\" yet, but we may want to\n> do so at the Git 3.0 boundary, in which case we will need to start\n> advertising upcoming removal with an extra warning when they are\n> used. But let's not start annoying users for now.\n\nThis version looks good to me, thanks!\n\nPatrick\n"},{"id":"496525","messageId":"xmqqa5jyp0al.fsf@gitster.g","threadId":"61579","inReplyTo":"ZmGDuThKIbexY-xa@tanuki","subject":"Re: [PATCH v2 2/3] ls-remote: introduce --branches and deprecate --heads","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-06-06T15:18:26Z","receivedAt":"2024-06-06T15:18:31Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt writes:\n\n>> +test_expect_success 'ls-remote -h is deprecated w/o warning' '\n>> +\tgit ls-remote -h self >actual 2>warning &&\n>> +\ttest_cmp expected.branches actual &&\n>> +\ttest_grep ! deprecated warning\n>> +'\n>\n> It is a bit funny to grep for something that wasn't ever there. But I\n> don't mind it much as we may eventually want to introduce such a\n> deprecation warning if we ever decide to go through with the\n> deprecation.\n\nIt is indeed funny. We thought about adding and then made a\nconscious decision not to add a deprecation warning, so this\ntestpiece serves as a documentation of the status quo, and a\nback-pointer for readers to blame back to the message of the\ncommit that introduced this one, which clearly says the lack\nof warning is something we may want to reconsider later.\n\nSo, this should be fine (the same for 3/3).\n\nThanks.\n\n"},{"id":"497193","messageId":"CABPp-BH3ZozGnDueK=J4QvZMYZkS13Gk+0rhe+Dywqbx1F30DA@mail.gmail.com","threadId":"61579","inReplyTo":"20240604220145.3260714-4-gitster@pobox.com","subject":"Re: [PATCH v2 3/3] show-ref: introduce --branches and deprecate --heads","fromName":"Elijah Newren","fromEmail":"newren@gmail.com","sentAt":"2024-06-14T19:32:27Z","receivedAt":"2024-06-14T19:32:39Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"On Tue, Jun 4, 2024 at 10:02 PM Junio C Hamano wrote:\n>\n> We call the tips of branches \"heads\", but this command calls the\n> option to show only branches \"--heads\", which confuses the branches\n> themselves and the tips of branches.\n>\n> Straighten the terminology by introducing \"--branches\" option that\n> limits the output to branches, and deprecate \"--heads\" option used\n> that way.\n>\n> We do not plan to remove \"--heads\" or \"-h\" yet; we may want to do so\n> at Git 3.0, in which case, we may need to start advertising upcoming\n> removal with an extra warning when they are used.\n>\n> Signed-off-by: Junio C Hamano \n> ---\n> Documentation/git-show-ref.txt | 18 ++++++++++--------\n> builtin/show-ref.c | 16 +++++++++-------\n> t/t1403-show-ref.sh | 24 ++++++++++++++++--------\n> 3 files changed, 35 insertions(+), 23 deletions(-)\n>\n> diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt\n> index ba75747005..616d919655 100644\n> --- a/Documentation/git-show-ref.txt\n> +++ b/Documentation/git-show-ref.txt\n> @@ -9,8 +9,8 @@ SYNOPSIS\n> --------\n> [verse]\n> 'git show-ref' [--head] [-d | --dereference]\n> - [-s | --hash[=]] [--abbrev[=]] [--tags]\n> - [--heads] [--] [...]\n> + [-s | --hash[=]] [--abbrev[=]] [--branches] [--tags]\n> + [--] [...]\n> 'git show-ref' --verify [-q | --quiet] [-d | --dereference]\n> [-s | --hash[=]] [--abbrev[=]]\n> [--] [...]\n> @@ -45,12 +45,14 @@ OPTIONS\n>\n> Show the HEAD reference, even if it would normally be filtered out.\n>\n> ---heads::\n> +--branches::\n> --tags::\n>\n> - Limit to \"refs/heads\" and \"refs/tags\", respectively. These options\n> + Limit to local branches and local tags, respectively. These options\n> are not mutually exclusive; when given both, references stored in\n> - \"refs/heads\" and \"refs/tags\" are displayed.\n> + \"refs/heads\" and \"refs/tags\" are displayed. Note that `--heads`\n> + is a deprecated synonym for `--branches` and may be removed\n> + in the future.\n>\n> -d::\n> --dereference::\n> @@ -139,7 +141,7 @@ When using `--hash` (and not `--dereference`), the output is in the format:\n> For example,\n>\n> -----------------------------------------------------------------------------\n> -$ git show-ref --heads --hash\n> +$ git show-ref --branches --hash\n> 2e3ba0114a1f52b47df29743d6915d056be13278\n> 185008ae97960c8d551adcd9e23565194651b5d1\n> 03adf42c988195b50e1a1935ba5fcbc39b2b029b\n> @@ -183,8 +185,8 @@ to check whether a particular branch exists or not (notice how we don't\n> actually want to show any results, and we want to use the full refname for it\n> in order to not trigger the problem with ambiguous partial matches).\n>\n> -To show only tags, or only proper branch heads, use `--tags` and/or `--heads`\n> -respectively (using both means that it shows tags and heads, but not other\n> +To show only tags, or only proper branch heads, use `--tags` and/or `--branches`\n> +respectively (using both means that it shows tags and branches, but not other\n> random references under the refs/ subdirectory).\n>\n> To do automatic tag object dereferencing, use the `-d` or `--dereference`\n> diff --git a/builtin/show-ref.c b/builtin/show-ref.c\n> index 1c15421e60..f634bc3e44 100644\n> --- a/builtin/show-ref.c\n> +++ b/builtin/show-ref.c\n> @@ -11,8 +11,8 @@\n>\n> static const char * const show_ref_usage[] = {\n> N_(\"git show-ref [--head] [-d | --dereference]\\n\"\n> - \" [-s | --hash[=]] [--abbrev[=]] [--tags]\\n\"\n> - \" [--heads] [--] [...]\"),\n> + \" [-s | --hash[=]] [--abbrev[=]] [--branches] [--tags]\\n\"\n> + \" [--] [...]\"),\n> N_(\"git show-ref --verify [-q | --quiet] [-d | --dereference]\\n\"\n> \" [-s | --hash[=]] [--abbrev[=]]\\n\"\n> \" [--] [...]\"),\n> @@ -188,7 +188,7 @@ static int cmd_show_ref__verify(const struct show_one_options *show_one_opts,\n>\n> struct patterns_options {\n> int show_head;\n> - int heads_only;\n> + int branches_only;\n> int tags_only;\n> };\n>\n> @@ -206,8 +206,8 @@ static int cmd_show_ref__patterns(const struct patterns_options *opts,\n>\n> if (opts->show_head)\n> head_ref(show_ref, &show_ref_data);\n> - if (opts->heads_only || opts->tags_only) {\n> - if (opts->heads_only)\n> + if (opts->branches_only || opts->tags_only) {\n> + if (opts->branches_only)\n> for_each_fullref_in(\"refs/heads/\", show_ref, &show_ref_data);\n> if (opts->tags_only)\n> for_each_fullref_in(\"refs/tags/\", show_ref, &show_ref_data);\n> @@ -286,8 +286,10 @@ int cmd_show_ref(int argc, const char **argv, const char *prefix)\n> struct show_one_options show_one_opts = {0};\n> int verify = 0, exists = 0;\n> const struct option show_ref_options[] = {\n> - OPT_BOOL(0, \"tags\", &patterns_opts.tags_only, N_(\"only show tags (can be combined with heads)\")),\n> - OPT_BOOL(0, \"heads\", &patterns_opts.heads_only, N_(\"only show heads (can be combined with tags)\")),\n> + OPT_BOOL(0, \"tags\", &patterns_opts.tags_only, N_(\"only show tags (can be combined with branches)\")),\n> + OPT_BOOL(0, \"branches\", &patterns_opts.branches_only, N_(\"only show branches (can be combined with tags)\")),\n> + OPT_HIDDEN_BOOL(0, \"heads\", &patterns_opts.branches_only,\n> + N_(\"deprecated synonym for --branches\")),\n> OPT_BOOL(0, \"exists\", &exists, N_(\"check for reference existence without resolving\")),\n> OPT_BOOL(0, \"verify\", &verify, N_(\"stricter reference checking, \"\n> \"requires exact ref path\")),\n> diff --git a/t/t1403-show-ref.sh b/t/t1403-show-ref.sh\n> index 33fb7a38ff..403f6b8f7d 100755\n> --- a/t/t1403-show-ref.sh\n> +++ b/t/t1403-show-ref.sh\n> @@ -121,13 +121,13 @@ test_expect_success 'show-ref -d' '\n>\n> '\n>\n> -test_expect_success 'show-ref --heads, --tags, --head, pattern' '\n> +test_expect_success 'show-ref --branches, --tags, --head, pattern' '\n> for branch in B main side\n> do\n> echo $(git rev-parse refs/heads/$branch) refs/heads/$branch || return 1\n> - done >expect.heads &&\n> - git show-ref --heads >actual &&\n> - test_cmp expect.heads actual &&\n> + done >expect.branches &&\n> + git show-ref --branches >actual &&\n> + test_cmp expect.branches actual &&\n>\n> for tag in A B C\n> do\n> @@ -136,15 +136,15 @@ test_expect_success 'show-ref --heads, --tags, --head, pattern' '\n> git show-ref --tags >actual &&\n> test_cmp expect.tags actual &&\n>\n> - cat expect.heads expect.tags >expect &&\n> - git show-ref --heads --tags >actual &&\n> + cat expect.branches expect.tags >expect &&\n> + git show-ref --branches --tags >actual &&\n> test_cmp expect actual &&\n>\n> {\n> echo $(git rev-parse HEAD) HEAD &&\n> - cat expect.heads expect.tags\n> + cat expect.branches expect.tags\n> } >expect &&\n> - git show-ref --heads --tags --head >actual &&\n> + git show-ref --branches --tags --head >actual &&\n> test_cmp expect actual &&\n>\n> {\n> @@ -165,6 +165,14 @@ test_expect_success 'show-ref --heads, --tags, --head, pattern' '\n> test_cmp expect actual\n> '\n>\n> +test_expect_success 'show-ref --heads is deprecated and hidden' '\n> + test_expect_code 129 git show-ref -h >short-help &&\n> + test_grep ! -e --heads short-help &&\n> + git show-ref --heads >actual 2>warning &&\n> + test_grep ! deprecated warning &&\n> + test_cmp expect.branches actual\n> +'\n> +\n> test_expect_success 'show-ref --verify HEAD' '\n> echo $(git rev-parse HEAD) HEAD >expect &&\n> git show-ref --verify HEAD >actual &&\n> --\n> 2.45.2-409-g7b0defb391\n\nIf we are renaming --heads to --branches, should --head also be renamed?\n\nOther than that question, this patch and series looks good to me.\n"},{"id":"497200","messageId":"xmqq7cerdxv4.fsf@gitster.g","threadId":"61579","inReplyTo":"CABPp-BH3ZozGnDueK=J4QvZMYZkS13Gk+0rhe+Dywqbx1F30DA@mail.gmail.com","subject":"Re: [PATCH v2 3/3] show-ref: introduce --branches and deprecate --heads","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-06-14T21:21:19Z","receivedAt":"2024-06-14T21:21:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Elijah Newren writes:\n\n> If we are renaming --heads to --branches, should --head also be renamed?\n\nI do not think so. It is specifically about HEAD (the thing that\nlives above refs/ hierarchy, historically implemented as a file\nwhose name is \"HEAD\" that is directly inside $GIT_DIR).\n\nThanks.\n"},{"id":"497202","messageId":"CABPp-BEM4fqU9s7_dxgi_twe_T169mGjZN9-CJRLU5cjnUi8WQ@mail.gmail.com","threadId":"61579","inReplyTo":"xmqq7cerdxv4.fsf@gitster.g","subject":"Re: [PATCH v2 3/3] show-ref: introduce --branches and deprecate --heads","fromName":"Elijah Newren","fromEmail":"newren@gmail.com","sentAt":"2024-06-14T21:34:26Z","receivedAt":"2024-06-14T21:34:39Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"On Fri, Jun 14, 2024 at 9:21 PM Junio C Hamano wrote:\n>\n> Elijah Newren writes:\n>\n> > If we are renaming --heads to --branches, should --head also be renamed?\n>\n> I do not think so. It is specifically about HEAD (the thing that\n> lives above refs/ hierarchy, historically implemented as a file\n> whose name is \"HEAD\" that is directly inside $GIT_DIR).\n>\n> Thanks.\n\nI'm fine if we don't want to rename it, but I don't quite follow this\nparticular rationale. The logic you use here seems to be about\ninternal details (\"it's the file named HEAD\") and ignores what users\nmight refer to it as (\"current branch\"), whereas --branches ignored\nthe internal details (\"the files under refs/heads/\") and instead\nconcentrates on what users might refer to them as (\"branches\") and\nused that as the rationale for renaming.\n\nThat said, I've almost never seen users use --head (and haven't used\nit myself), whereas asking for heads/branches is much more common, and\nI'm very happy with the change from --heads to --branches. Also, even\nif we do agree --head should be renamed, I'd be fine with punting it\nto later in order to get this improvement in now...it just seemed like\na small inconsistency that I thought was worth pointing out.\n"},{"id":"497203","messageId":"CABPp-BEZhR8T56bwxpi+_uGG8w7nms+7HtCR45S4oVjPom9Stg@mail.gmail.com","threadId":"61579","inReplyTo":"CABPp-BEM4fqU9s7_dxgi_twe_T169mGjZN9-CJRLU5cjnUi8WQ@mail.gmail.com","subject":"Re: [PATCH v2 3/3] show-ref: introduce --branches and deprecate --heads","fromName":"Elijah Newren","fromEmail":"newren@gmail.com","sentAt":"2024-06-14T21:42:17Z","receivedAt":"2024-06-14T21:42:29Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"On Fri, Jun 14, 2024 at 9:34 PM Elijah Newren wrote:\n>\n> On Fri, Jun 14, 2024 at 9:21 PM Junio C Hamano wrote:\n> >\n> > Elijah Newren writes:\n> >\n> > > If we are renaming --heads to --branches, should --head also be renamed?\n> >\n> > I do not think so. It is specifically about HEAD (the thing that\n> > lives above refs/ hierarchy, historically implemented as a file\n> > whose name is \"HEAD\" that is directly inside $GIT_DIR).\n> >\n> > Thanks.\n>\n> I'm fine if we don't want to rename it, but I don't quite follow this\n> particular rationale. The logic you use here seems to be about\n> internal details (\"it's the file named HEAD\") and ignores what users\n> might refer to it as (\"current branch\"), whereas --branches ignored\n> the internal details (\"the files under refs/heads/\") and instead\n> concentrates on what users might refer to them as (\"branches\") and\n> used that as the rationale for renaming.\n>\n> That said, I've almost never seen users use --head (and haven't used\n> it myself), whereas asking for heads/branches is much more common, and\n> I'm very happy with the change from --heads to --branches. Also, even\n> if we do agree --head should be renamed, I'd be fine with punting it\n> to later in order to get this improvement in now...it just seemed like\n> a small inconsistency that I thought was worth pointing out.\n\n...or maybe my argument breaks down because `HEAD` is more prominent\nand tends to be used by users more (`git reset --hard HEAD`, `git\ncheckout HEAD~1`), and thus there's an argument it already is somewhat\naligned with user terminology?\n"},{"id":"497204","messageId":"xmqq5xubcfco.fsf@gitster.g","threadId":"61579","inReplyTo":"CABPp-BEZhR8T56bwxpi+_uGG8w7nms+7HtCR45S4oVjPom9Stg@mail.gmail.com","subject":"Re: [PATCH v2 3/3] show-ref: introduce --branches and deprecate --heads","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-06-14T22:46:31Z","receivedAt":"2024-06-14T22:48:09Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Elijah Newren writes:\n\n> ...or maybe my argument breaks down because `HEAD` is more prominent\n> and tends to be used by users more (`git reset --hard HEAD`, `git\n> checkout HEAD~1`), and thus there's an argument it already is somewhat\n> aligned with user terminology?\n\nYeah, you are correct to say that HEAD is a lot more prominent than\n\"refs/heads/\". \"git branch --list\" does not expose the\n\"refs/heads/\" part (but \"git for-each-ref\" does), but you'd see HEAD\nin many places (e.g. \"git show -s \" gives the --decorate\noutput that says \"HEAD -> master\" etc.).\n\nOf course we _could_ plan to rename \"HEAD\" to something else, like\n\"CURRENT\" and deal with the fallout, and then rename \"refs/heads/\"\nto \"refs/branches/\", but for what cost to achieve what benefit? The\ntradeoff does not look all that good to me.\n\nSo I'd say renaming --heads to --branches would probably be a good\nplace to stop, at least for now.\n"}]}