Re: [PATCH v2 3/3] 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 | 18 ++++++++++--------
>  builtin/show-ref.c             | 16 +++++++++-------
>  t/t1403-show-ref.sh            | 24 ++++++++++++++++--------
>  3 files changed, 35 insertions(+), 23 deletions(-)
>
> diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt
> index ba75747005..616d919655 100644
> --- a/Documentation/git-show-ref.txt
> +++ b/Documentation/git-show-ref.txt
> @@ -9,8 +9,8 @@ SYNOPSIS
>  --------
>  [verse]
>  'git show-ref' [--head] [-d | --dereference]
> -            [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags]
> -            [--heads] [--] [<pattern>...]
> +            [-s | --hash[=<n>]] [--abbrev[=<n>]] [--branches] [--tags]
> +            [--] [<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`
> -respectively (using both means that it shows tags and heads, but not other
> +To show only tags, or only proper branch heads, use `--tags` and/or `--branches`
> +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`
> diff --git a/builtin/show-ref.c b/builtin/show-ref.c
> index 1c15421e60..f634bc3e44 100644
> --- a/builtin/show-ref.c
> +++ b/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"
> -          "             [--heads] [--] [<pattern>...]"),
> +          "             [-s | --hash[=<n>]] [--abbrev[=<n>]] [--branches] [--tags]\n"
> +          "             [--] [<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->heads_only)
> +       if (opts->branches_only || opts->tags_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, "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_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")),
> diff --git a/t/t1403-show-ref.sh b/t/t1403-show-ref.sh
> index 33fb7a38ff..403f6b8f7d 100755
> --- a/t/t1403-show-ref.sh
> +++ b/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 &&
> -       git show-ref --heads >actual &&
> -       test_cmp expect.heads actual &&
> +       done >expect.branches &&
> +       git show-ref --branches >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 &&
> -       git show-ref --heads --tags >actual &&
> +       cat expect.branches expect.tags >expect &&
> +       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 &&
> --
> 2.45.2-409-g7b0defb391