| Message ID | 20240604220145.3260714-1-gitster@pobox.com (mailing list archive) |
|---|---|
| Headers | show |
| Series | Branches are branches and not heads | expand |
On Tue, Jun 04, 2024 at 03:01:42PM -0700, Junio C Hamano wrote: > tl;dr for those who did read v1: v2 does not warn when deprecated > variants are used. > ---------------------- > > Back when Git started, we used the word "head" to mean the tip of > possibly multiple histories, and that is where the name of the > hierarchy .git/refs/heads/ came from. But these days we call these > entities "branches" in human terms, and "head" is still used to > refer to the tip of the history each of these branches represent. > > When asking "git ls-remote" or "git show-ref" to limit their output > to branches (as opposed to showing any ref), we use "--heads" for > historical reasons, but give the option a more human friendly name > "--branches", and demote "--heads" to the status of a deprecated > synonym. > > We do not plan to remove "--heads" or "-h" yet, but we may want to > do so at the Git 3.0 boundary, in which case we will need to start > advertising upcoming removal with an extra warning when they are > used. But let's not start annoying users for now. This version looks good to me, thanks! Patrick
tl;dr for those who did read v1: v2 does not warn when deprecated variants are used. ---------------------- Back when Git started, we used the word "head" to mean the tip of possibly multiple histories, and that is where the name of the hierarchy .git/refs/heads/ came from. But these days we call these entities "branches" in human terms, and "head" is still used to refer to the tip of the history each of these branches represent. When asking "git ls-remote" or "git show-ref" to limit their output to branches (as opposed to showing any ref), we use "--heads" for historical reasons, but give the option a more human friendly name "--branches", and demote "--heads" to the status of a deprecated synonym. We do not plan to remove "--heads" or "-h" yet, but we may want to do so at the Git 3.0 boundary, in which case we will need to start advertising upcoming removal with an extra warning when they are used. But let's not start annoying users for now. Junio C Hamano (3): refs: call branches branches ls-remote: introduce --branches and deprecate --heads show-ref: introduce --branches and deprecate --heads Documentation/git-ls-remote.txt | 12 +++++++----- Documentation/git-show-ref.txt | 18 ++++++++++-------- builtin/ls-remote.c | 9 ++++++--- builtin/show-ref.c | 16 +++++++++------- connect.c | 4 ++-- remote.h | 2 +- t/t1403-show-ref.sh | 24 ++++++++++++++++-------- t/t5512-ls-remote.sh | 32 +++++++++++++++++++++++++++----- 8 files changed, 78 insertions(+), 39 deletions(-) Range-diff against v1: 1: 2c551ed37b = 1: 2c551ed37b refs: call branches branches 2: f88fe89ff7 ! 2: 5549e98042 ls-remote: introduce --branches and deprecate --heads @@ Commit message limits the output to branches, and deprecate "--heads" option used that way. + We do not plan to remove "--heads" or "-h" yet; we may want to do so + at Git 3.0, in which case, we may need to start advertising upcoming + removal with an extra warning when they are used. + Signed-off-by: Junio C Hamano <gitster@pobox.com> ## Documentation/git-ls-remote.txt ## @@ builtin/ls-remote.c " [-q | --quiet] [--exit-code] [--get-url] [--sort=<key>]\n" " [--symref] [<repository> [<patterns>...]]"), NULL -@@ builtin/ls-remote.c: static int tail_match(const char **pattern, const char *path) - return 0; - } - -+static int heads_callback(const struct option *opt, const char *arg, int unset) -+{ -+ unsigned *flags = opt->value; -+ -+ if (unset) { -+ warning(_("'--no-heads' is deprecated; use '--no-branches' instead")); -+ *flags &= ~REF_BRANCHES; -+ } else { -+ warning(_("'--heads' is deprecated; use '--branches' instead")); -+ *flags |= REF_BRANCHES; -+ } -+ return 0; -+} -+ - int cmd_ls_remote(int argc, const char **argv, const char *prefix) - { - const char *dest = NULL; @@ builtin/ls-remote.c: int cmd_ls_remote(int argc, const char **argv, const char *prefix) N_("path of git-upload-pack on the remote host"), PARSE_OPT_HIDDEN }, OPT_BIT('t', "tags", &flags, N_("limit to tags"), REF_TAGS), - OPT_BIT('h', "heads", &flags, N_("limit to heads"), REF_BRANCHES), + OPT_BIT('b', "branches", &flags, N_("limit to branches"), REF_BRANCHES), -+ OPT_CALLBACK_F('h', "heads", &flags, -+ NULL, -+ N_("deprecated synonym for --branches"), -+ PARSE_OPT_NOARG|PARSE_OPT_HIDDEN, -+ &heads_callback), ++ OPT_BIT_F('h', "heads", &flags, ++ N_("deprecated synonym for --branches"), REF_BRANCHES, ++ PARSE_OPT_HIDDEN), OPT_BIT(0, "refs", &flags, N_("do not show peeled tags"), REF_NORMAL), OPT_BOOL(0, "get-url", &get_url, N_("take url.<base>.insteadOf into account")), @@ t/t5512-ls-remote.sh: test_expect_success 'ls-remote self' ' + test_cmp expected.branches actual +' + -+test_expect_success 'ls-remote -h is deprecated' ' ++test_expect_success 'ls-remote -h is deprecated w/o warning' ' + git ls-remote -h self >actual 2>warning && + test_cmp expected.branches actual && -+ test_grep deprecated warning ++ test_grep ! deprecated warning +' + -+test_expect_success 'ls-remote --heads is deprecated' ' ++test_expect_success 'ls-remote --heads is deprecated and hidden w/o warning' ' ++ test_expect_code 129 git ls-remote -h >short-help && ++ test_grep ! -e --head short-help && + git ls-remote --heads self >actual 2>warning && + test_cmp expected.branches actual && -+ test_grep deprecated warning ++ test_grep ! deprecated warning +' + test_expect_success 'ls-remote --sort="version:refname" --tags self' ' 3: 295554edfc ! 3: 9022743a32 show-ref: introduce --branches and deprecate --heads @@ Commit message limits the output to branches, and deprecate "--heads" option used that way. + We do not plan to remove "--heads" or "-h" yet; we may want to do so + at Git 3.0, in which case, we may need to start advertising upcoming + removal with an extra warning when they are used. + Signed-off-by: Junio C Hamano <gitster@pobox.com> ## Documentation/git-show-ref.txt ## @@ builtin/show-ref.c: static int cmd_show_ref__patterns(const struct patterns_opti for_each_fullref_in("refs/heads/", show_ref, &show_ref_data); if (opts->tags_only) for_each_fullref_in("refs/tags/", show_ref, &show_ref_data); -@@ builtin/show-ref.c: static int exclude_existing_callback(const struct option *opt, const char *arg, - return 0; - } - -+static int heads_callback(const struct option *opt, const char *arg, int unset) -+{ -+ int *branches_only = opt->value; -+ -+ if (unset) { -+ warning(_("'--no-heads' is deprecated; use '--no-branches' instead")); -+ *branches_only = 0; -+ } else { -+ warning(_("'--heads' is deprecated; use '--branches' instead")); -+ *branches_only = 1; -+ } -+ return 0; -+} -+ - int cmd_show_ref(int argc, const char **argv, const char *prefix) - { - struct exclude_existing_options exclude_existing_opts = {0}; @@ builtin/show-ref.c: int cmd_show_ref(int argc, const char **argv, const char *prefix) struct show_one_options show_one_opts = {0}; int verify = 0, exists = 0; @@ builtin/show-ref.c: int cmd_show_ref(int argc, const char **argv, const char *pr - OPT_BOOL(0, "heads", &patterns_opts.heads_only, N_("only show heads (can be combined with tags)")), + OPT_BOOL(0, "tags", &patterns_opts.tags_only, N_("only show tags (can be combined with branches)")), + OPT_BOOL(0, "branches", &patterns_opts.branches_only, N_("only show branches (can be combined with tags)")), -+ OPT_CALLBACK_F(0, "heads", &patterns_opts.branches_only, -+ NULL, -+ N_("deprecated synonym for --branches)"), -+ PARSE_OPT_NOARG|PARSE_OPT_HIDDEN, -+ &heads_callback), ++ OPT_HIDDEN_BOOL(0, "heads", &patterns_opts.branches_only, ++ N_("deprecated synonym for --branches")), OPT_BOOL(0, "exists", &exists, N_("check for reference existence without resolving")), OPT_BOOL(0, "verify", &verify, N_("stricter reference checking, " "requires exact ref path")), @@ t/t1403-show-ref.sh: test_expect_success 'show-ref --heads, --tags, --head, patt test_cmp expect actual ' -+test_expect_success 'show-ref --heads is deprecated' ' ++test_expect_success 'show-ref --heads is deprecated and hidden' ' ++ test_expect_code 129 git show-ref -h >short-help && ++ test_grep ! -e --heads short-help && + git show-ref --heads >actual 2>warning && -+ test_grep deprecated warning && ++ test_grep ! deprecated warning && + test_cmp expect.branches actual +' +