Merge branch 'jc/heads-are-branches'

The "--heads" option of "ls-remote" and "show-ref" has been been
deprecated; "--branches" replaces "--heads".

* jc/heads-are-branches:
  show-ref: introduce --branches and deprecate --heads
  ls-remote: introduce --branches and deprecate --heads
  refs: call branches branches
This commit is contained in:
Junio C Hamano 2024-06-20 15:45:16 -07:00
commit 892fd8b89f
8 changed files with 78 additions and 39 deletions

View file

@ -9,7 +9,7 @@ git-ls-remote - List references in a remote repository
SYNOPSIS
--------
[verse]
'git ls-remote' [--heads] [--tags] [--refs] [--upload-pack=<exec>]
'git ls-remote' [--branches] [--tags] [--refs] [--upload-pack=<exec>]
[-q | --quiet] [--exit-code] [--get-url] [--sort=<key>]
[--symref] [<repository> [<patterns>...]]
@ -21,14 +21,16 @@ commit IDs.
OPTIONS
-------
-h::
--heads::
-b::
--branches::
-t::
--tags::
Limit to only refs/heads and refs/tags, respectively.
Limit to only 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. Note that `git ls-remote -h` used without
displayed. Note that `--heads` and `-h` are deprecated
synonyms for `--branches` and `-b` and may be removed in
the future. Also note that `git ls-remote -h` used without
anything else on the command line gives help, consistent
with other git subcommands.

View file

@ -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`

View file

@ -9,7 +9,7 @@
#include "wildmatch.h"
static const char * const ls_remote_usage[] = {
N_("git ls-remote [--heads] [--tags] [--refs] [--upload-pack=<exec>]\n"
N_("git ls-remote [--branches] [--tags] [--refs] [--upload-pack=<exec>]\n"
" [-q | --quiet] [--exit-code] [--get-url] [--sort=<key>]\n"
" [--symref] [<repository> [<patterns>...]]"),
NULL
@ -68,7 +68,10 @@ 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_HEADS),
OPT_BIT('b', "branches", &flags, N_("limit to branches"), REF_BRANCHES),
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")),
@ -100,7 +103,7 @@ int cmd_ls_remote(int argc, const char **argv, const char *prefix)
if (flags & REF_TAGS)
strvec_push(&transport_options.ref_prefixes, "refs/tags/");
if (flags & REF_HEADS)
if (flags & REF_BRANCHES)
strvec_push(&transport_options.ref_prefixes, "refs/heads/");
remote = remote_get(dest);

View file

@ -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>...]"),
@ -189,7 +189,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;
};
@ -208,8 +208,8 @@ static int cmd_show_ref__patterns(const struct patterns_options *opts,
if (opts->show_head)
refs_head_ref(get_main_ref_store(the_repository), 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)
refs_for_each_fullref_in(get_main_ref_store(the_repository),
"refs/heads/", NULL,
show_ref, &show_ref_data);
@ -293,8 +293,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")),

View file

@ -38,8 +38,8 @@ static int check_ref(const char *name, unsigned int flags)
REFNAME_ALLOW_ONELEVEL))
return 0;
/* REF_HEADS means that we want regular branch heads */
if ((flags & REF_HEADS) && starts_with(name, "heads/"))
/* REF_BRANCHES means that we want regular branch heads */
if ((flags & REF_BRANCHES) && starts_with(name, "heads/"))
return 1;
/* REF_TAGS means that we want tags */

View file

@ -200,7 +200,7 @@ struct ref {
};
#define REF_NORMAL (1u << 0)
#define REF_HEADS (1u << 1)
#define REF_BRANCHES (1u << 1)
#define REF_TAGS (1u << 2)
struct ref *find_ref_by_name(const struct ref *list, const char *name);

View file

@ -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 &&

View file

@ -47,6 +47,7 @@ test_expect_success setup '
git show-ref -d >refs &&
sed -e "s/ / /" refs >>expected.all &&
grep refs/heads/ expected.all >expected.branches &&
git remote add self "$(pwd)/.git" &&
git remote add self2 "."
'
@ -71,6 +72,27 @@ test_expect_success 'ls-remote self' '
test_cmp expected.all actual
'
test_expect_success 'ls-remote --branches self' '
git ls-remote --branches self >actual &&
test_cmp expected.branches actual &&
git ls-remote -b self >actual &&
test_cmp expected.branches actual
'
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_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_expect_success 'ls-remote --sort="version:refname" --tags self' '
generate_references \
refs/tags/mark \
@ -275,7 +297,7 @@ test_expect_success 'ls-remote with filtered symref (refname)' '
test_cmp expect actual
'
test_expect_success 'ls-remote with filtered symref (--heads)' '
test_expect_success 'ls-remote with filtered symref (--branches)' '
git symbolic-ref refs/heads/foo refs/tags/mark &&
cat >expect.v2 <<-EOF &&
ref: refs/tags/mark refs/heads/foo
@ -283,9 +305,9 @@ test_expect_success 'ls-remote with filtered symref (--heads)' '
$rev refs/heads/main
EOF
grep -v "^ref: refs/tags/" <expect.v2 >expect.v0 &&
git -c protocol.version=0 ls-remote --symref --heads . >actual.v0 &&
git -c protocol.version=0 ls-remote --symref --branches . >actual.v0 &&
test_cmp expect.v0 actual.v0 &&
git -c protocol.version=2 ls-remote --symref --heads . >actual.v2 &&
git -c protocol.version=2 ls-remote --symref --branches . >actual.v2 &&
test_cmp expect.v2 actual.v2
'
@ -335,9 +357,9 @@ test_expect_success 'ls-remote patterns work with all protocol versions' '
test_expect_success 'ls-remote prefixes work with all protocol versions' '
git for-each-ref --format="%(objectname) %(refname)" \
refs/heads/ refs/tags/ >expect &&
git -c protocol.version=0 ls-remote --heads --tags . >actual.v0 &&
git -c protocol.version=0 ls-remote --branches --tags . >actual.v0 &&
test_cmp expect actual.v0 &&
git -c protocol.version=2 ls-remote --heads --tags . >actual.v2 &&
git -c protocol.version=2 ls-remote --branches --tags . >actual.v2 &&
test_cmp expect actual.v2
'