[PATCH v2 0/3] Branches are branches and not heads

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
     +'
     +