show-ref: introduce --branches and deprecate --heads

We call the tips of branches "heads", but this command calls the
option to show only branches "--heads", which confuses the branches
themselves and the tips of branches.

Straighten the terminology by introducing "--branches" option that
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

@@ -9,8 +9,8 @@ SYNOPSIS
 --------
 [verse]
 'git show-ref' [--head] [-d | --dereference]
-	     [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags]
+	     [-s | --hash[=<n>]] [--abbrev[=<n>]] [--branches] [--tags]
-	     [--heads] [--] [<pattern>...]
+	     [--] [<pattern>...]
 'git show-ref' --verify [-q | --quiet] [-d | --dereference]
 	     [-s | --hash[=<n>]] [--abbrev[=<n>]]
 	     [--] [<ref>...]
@@ -45,12 +45,14 @@ OPTIONS
 
 	Show the HEAD reference, even if it would normally be filtered out.
 
---heads::
+--branches::
 --tags::
 
-	Limit to "refs/heads" and "refs/tags", respectively.  These options
+	Limit to local branches and local tags, respectively.  These options
 	are not mutually exclusive; when given both, references stored in
-	"refs/heads" and "refs/tags" are displayed.
+	"refs/heads" and "refs/tags" are displayed.  Note that `--heads`
+	is a deprecated synonym for `--branches` and may be removed
+	in the future.
 
 -d::
 --dereference::
@@ -139,7 +141,7 @@ When using `--hash` (and not `--dereference`), the output is in the format:
 For example,
 
 -----------------------------------------------------------------------------
-$ git show-ref --heads --hash
+$ git show-ref --branches --hash
 2e3ba0114a1f52b47df29743d6915d056be13278
 185008ae97960c8d551adcd9e23565194651b5d1
 03adf42c988195b50e1a1935ba5fcbc39b2b029b
@@ -183,8 +185,8 @@ to check whether a particular branch exists or not (notice how we don't
 actually want to show any results, and we want to use the full refname for it
 in order to not trigger the problem with ambiguous partial matches).
 
-To show only tags, or only proper branch heads, use `--tags` and/or `--heads`
+To show only tags, or only proper branch heads, use `--tags` and/or `--branches`
-respectively (using both means that it shows tags and heads, but not other
+respectively (using both means that it shows tags and branches, but not other
 random references under the refs/ subdirectory).
 
 To do automatic tag object dereferencing, use the `-d` or `--dereference`

builtin/show-ref.c

@@ -11,8 +11,8 @@
 
 static const char * const show_ref_usage[] = {
 	N_("git show-ref [--head] [-d | --dereference]\n"
-	   "             [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags]\n"
+	   "             [-s | --hash[=<n>]] [--abbrev[=<n>]] [--branches] [--tags]\n"
-	   "             [--heads] [--] [<pattern>...]"),
+	   "             [--] [<pattern>...]"),
 	N_("git show-ref --verify [-q | --quiet] [-d | --dereference]\n"
 	   "             [-s | --hash[=<n>]] [--abbrev[=<n>]]\n"
 	   "             [--] [<ref>...]"),
@@ -188,7 +188,7 @@ static int cmd_show_ref__verify(const struct show_one_options *show_one_opts,
 
 struct patterns_options {
 	int show_head;
-	int heads_only;
+	int branches_only;
 	int tags_only;
 };
 
@@ -206,8 +206,8 @@ static int cmd_show_ref__patterns(const struct patterns_options *opts,
 
 	if (opts->show_head)
 		head_ref(show_ref, &show_ref_data);
-	if (opts->heads_only || opts->tags_only) {
+	if (opts->branches_only || opts->tags_only) {
-		if (opts->heads_only)
+		if (opts->branches_only)
 			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);
@@ -286,8 +286,10 @@ 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;
 	const struct option show_ref_options[] = {
-		OPT_BOOL(0, "tags", &patterns_opts.tags_only, N_("only show tags (can be combined with heads)")),
+		OPT_BOOL(0, "tags", &patterns_opts.tags_only, N_("only show tags (can be combined with branches)")),
-		OPT_BOOL(0, "heads", &patterns_opts.heads_only, N_("only show heads (can be combined with tags)")),
+		OPT_BOOL(0, "branches", &patterns_opts.branches_only, N_("only show branches (can be combined with tags)")),
+		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

@@ -121,13 +121,13 @@ test_expect_success 'show-ref -d' '
 
 '
 
-test_expect_success 'show-ref --heads, --tags, --head, pattern' '
+test_expect_success 'show-ref --branches, --tags, --head, pattern' '
 	for branch in B main side
 	do
 		echo $(git rev-parse refs/heads/$branch) refs/heads/$branch || return 1
-	done >expect.heads &&
+	done >expect.branches &&
-	git show-ref --heads >actual &&
+	git show-ref --branches >actual &&
-	test_cmp expect.heads actual &&
+	test_cmp expect.branches actual &&
 
 	for tag in A B C
 	do
@@ -136,15 +136,15 @@ test_expect_success 'show-ref --heads, --tags, --head, pattern' '
 	git show-ref --tags >actual &&
 	test_cmp expect.tags actual &&
 
-	cat expect.heads expect.tags >expect &&
+	cat expect.branches expect.tags >expect &&
-	git show-ref --heads --tags >actual &&
+	git show-ref --branches --tags >actual &&
 	test_cmp expect actual &&
 
 	{
 		echo $(git rev-parse HEAD) HEAD &&
-		cat expect.heads expect.tags
+		cat expect.branches expect.tags
 	} >expect &&
-	git show-ref --heads --tags --head >actual &&
+	git show-ref --branches --tags --head >actual &&
 	test_cmp expect actual &&
 
 	{
@@ -165,6 +165,14 @@ test_expect_success 'show-ref --heads, --tags, --head, pattern' '
 	test_cmp expect actual
 '
 
+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_cmp expect.branches actual
+'
+
 test_expect_success 'show-ref --verify HEAD' '
 	echo $(git rev-parse HEAD) HEAD >expect &&
 	git show-ref --verify HEAD >actual &&