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>
Junio C Hamano committed
Jun 4, 2024 at 15:01 UTC
607c3d372ef89cf16874c288c60423587286d182
3 files changed
+35
-23
Documentation/git-show-ref.txt
+10
-8
@@ -9,8 +9,8 @@ SYNOPSIS
9
--------
10
[verse]
11
'git show-ref' [--head] [-d | --dereference]
12
- [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags]
13
- [--heads] [--] [<pattern>...]
12
+ [-s | --hash[=<n>]] [--abbrev[=<n>]] [--branches] [--tags]
13
+ [--] [<pattern>...]
14
'git show-ref' --verify [-q | --quiet] [-d | --dereference]
15
[-s | --hash[=<n>]] [--abbrev[=<n>]]
16
[--] [<ref>...]
@@ -45,12 +45,14 @@ OPTIONS
45
46
Show the HEAD reference, even if it would normally be filtered out.
47
48
---heads::
48
+--branches::
49
--tags::
50
51
- Limit to "refs/heads" and "refs/tags", respectively. These options
51
+ Limit to local branches and local tags, respectively. These options
52
are not mutually exclusive; when given both, references stored in
53
- "refs/heads" and "refs/tags" are displayed.
53
+ "refs/heads" and "refs/tags" are displayed. Note that `--heads`
54
+ is a deprecated synonym for `--branches` and may be removed
55
+ in the future.
56
57
-d::
58
--dereference::
@@ -139,7 +141,7 @@ When using `--hash` (and not `--dereference`), the output is in the format:
141
For example,
142
143
-----------------------------------------------------------------------------
142
-$ git show-ref --heads --hash
144
+$ git show-ref --branches --hash
145
2e3ba0114a1f52b47df29743d6915d056be13278
146
185008ae97960c8d551adcd9e23565194651b5d1
147
03adf42c988195b50e1a1935ba5fcbc39b2b029b
@@ -183,8 +185,8 @@ to check whether a particular branch exists or not (notice how we don't
185
actually want to show any results, and we want to use the full refname for it
186
in order to not trigger the problem with ambiguous partial matches).
187
186
-To show only tags, or only proper branch heads, use `--tags` and/or `--heads`
187
-respectively (using both means that it shows tags and heads, but not other
188
+To show only tags, or only proper branch heads, use `--tags` and/or `--branches`
189
+respectively (using both means that it shows tags and branches, but not other
190
random references under the refs/ subdirectory).
191
192
To do automatic tag object dereferencing, use the `-d` or `--dereference`
builtin/show-ref.c
+9
-7
@@ -11,8 +11,8 @@
11
12
static const char * const show_ref_usage[] = {
13
N_("git show-ref [--head] [-d | --dereference]\n"
14
- " [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags]\n"
15
- " [--heads] [--] [<pattern>...]"),
14
+ " [-s | --hash[=<n>]] [--abbrev[=<n>]] [--branches] [--tags]\n"
15
+ " [--] [<pattern>...]"),
16
N_("git show-ref --verify [-q | --quiet] [-d | --dereference]\n"
17
" [-s | --hash[=<n>]] [--abbrev[=<n>]]\n"
18
" [--] [<ref>...]"),
@@ -188,7 +188,7 @@ static int cmd_show_ref__verify(const struct show_one_options *show_one_opts,
188
189
struct patterns_options {
190
int show_head;
191
- int heads_only;
191
+ int branches_only;
192
int tags_only;
193
};
194
@@ -206,8 +206,8 @@ static int cmd_show_ref__patterns(const struct patterns_options *opts,
206
207
if (opts->show_head)
208
head_ref(show_ref, &show_ref_data);
209
- if (opts->heads_only || opts->tags_only) {
210
- if (opts->heads_only)
209
+ if (opts->branches_only || opts->tags_only) {
210
+ if (opts->branches_only)
211
for_each_fullref_in("refs/heads/", show_ref, &show_ref_data);
212
if (opts->tags_only)
213
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)
286
struct show_one_options show_one_opts = {0};
287
int verify = 0, exists = 0;
288
const struct option show_ref_options[] = {
289
- OPT_BOOL(0, "tags", &patterns_opts.tags_only, N_("only show tags (can be combined with heads)")),
290
- OPT_BOOL(0, "heads", &patterns_opts.heads_only, N_("only show heads (can be combined with tags)")),
289
+ OPT_BOOL(0, "tags", &patterns_opts.tags_only, N_("only show tags (can be combined with branches)")),
290
+ OPT_BOOL(0, "branches", &patterns_opts.branches_only, N_("only show branches (can be combined with tags)")),
291
+ OPT_HIDDEN_BOOL(0, "heads", &patterns_opts.branches_only,
292
+ N_("deprecated synonym for --branches")),
293
OPT_BOOL(0, "exists", &exists, N_("check for reference existence without resolving")),
294
OPT_BOOL(0, "verify", &verify, N_("stricter reference checking, "
295
"requires exact ref path")),
t/t1403-show-ref.sh
+16
-8
@@ -121,13 +121,13 @@ test_expect_success 'show-ref -d' '
121
122
'
123
124
-test_expect_success 'show-ref --heads, --tags, --head, pattern' '
124
+test_expect_success 'show-ref --branches, --tags, --head, pattern' '
125
for branch in B main side
126
do
127
echo $(git rev-parse refs/heads/$branch) refs/heads/$branch || return 1
128
- done >expect.heads &&
129
- git show-ref --heads >actual &&
130
- test_cmp expect.heads actual &&
128
+ done >expect.branches &&
129
+ git show-ref --branches >actual &&
130
+ test_cmp expect.branches actual &&
131
132
for tag in A B C
133
do
@@ -136,15 +136,15 @@ test_expect_success 'show-ref --heads, --tags, --head, pattern' '
136
git show-ref --tags >actual &&
137
test_cmp expect.tags actual &&
138
139
- cat expect.heads expect.tags >expect &&
140
- git show-ref --heads --tags >actual &&
139
+ cat expect.branches expect.tags >expect &&
140
+ git show-ref --branches --tags >actual &&
141
test_cmp expect actual &&
142
143
{
144
echo $(git rev-parse HEAD) HEAD &&
145
- cat expect.heads expect.tags
145
+ cat expect.branches expect.tags
146
} >expect &&
147
- git show-ref --heads --tags --head >actual &&
147
+ git show-ref --branches --tags --head >actual &&
148
test_cmp expect actual &&
149
150
{
@@ -165,6 +165,14 @@ test_expect_success 'show-ref --heads, --tags, --head, pattern' '
165
test_cmp expect actual
166
'
167
168
+test_expect_success 'show-ref --heads is deprecated and hidden' '
169
+ test_expect_code 129 git show-ref -h >short-help &&
170
+ test_grep ! -e --heads short-help &&
171
+ git show-ref --heads >actual 2>warning &&
172
+ test_grep ! deprecated warning &&
173
+ test_cmp expect.branches actual
174
+'
175
+
176
test_expect_success 'show-ref --verify HEAD' '
177
echo $(git rev-parse HEAD) HEAD >expect &&
178
git show-ref --verify HEAD >actual &&