builtin/refs: add 'exists' subcommand

As part of the ongoing effort to consolidate reference handling, introduce a new `exists` subcommand. This command provides the same functionality and exit-code behavior as `git show-ref --exists`, serving as its modern replacement. The logic for `show-ref --exists` is minimal. Rather than creating a shared helper function which would be overkill for ~20 lines of code, its implementation is intentionally duplicated here. This contrasts with `git refs list`, where sharing the larger implementation of `for-each-ref` was necessary. Documentation for the new subcommand is also added to the `git-refs(1)` man page. Mentored-by: Patrick Steinhardt <ps@pks.im> Mentored-by: shejialuo <shejialuo@gmail.com> Signed-off-by: Meet Soni <meetsoni3017@gmail.com> Acked-by: Patrick Steinhardt <ps@pks.im> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Meet Soni committed Aug 26, 2025 at 12:11 UTC 0f0a8a11c00295ed30b02cc721b0994900c6a3d3
2 files changed +55
Documentation/git-refs.adoc
+7
@@ -18,6 +18,7 @@ git refs list [--count=<count>] [--shell|--perl|--python|--tcl]
18 [--contains[=<object>]] [--no-contains[=<object>]]
19 [(--exclude=<pattern>)...] [--start-after=<marker>]
20 [ --stdin | <pattern>... ]
21 +git refs exists <ref>
22
23 DESCRIPTION
24 -----------
@@ -38,6 +39,12 @@ list::
39 formatting, and sorting. This subcommand is an alias for
40 linkgit:git-for-each-ref[1] and offers identical functionality.
41
42 +exists::
43 + Check whether the given reference exists. Returns an exit code of 0 if
44 + it does, 2 if it is missing, and 1 in case looking up the reference
45 + failed with an error other than the reference being missing. This does
46 + not verify whether the reference resolves to an actual object.
47 +
48 OPTIONS
49 -------
50
builtin/refs.c
+48
@@ -7,6 +7,7 @@
7 #include "strbuf.h"
8 #include "worktree.h"
9 #include "for-each-ref.h"
10 +#include "refs/refs-internal.h"
11
12 #define REFS_MIGRATE_USAGE \
13 N_("git refs migrate --ref-format=<format> [--no-reflog] [--dry-run]")
@@ -14,6 +15,9 @@
15 #define REFS_VERIFY_USAGE \
16 N_("git refs verify [--strict] [--verbose]")
17
18 +#define REFS_EXISTS_USAGE \
19 + N_("git refs exists <ref>")
20 +
21 static int cmd_refs_migrate(int argc, const char **argv, const char *prefix,
22 struct repository *repo UNUSED)
23 {
@@ -113,6 +117,48 @@ static int cmd_refs_list(int argc, const char **argv, const char *prefix,
117 return for_each_ref_core(argc, argv, prefix, repo, refs_list_usage);
118 }
119
120 +static int cmd_refs_exists(int argc, const char **argv, const char *prefix,
121 + struct repository *repo UNUSED)
122 +{
123 + struct strbuf unused_referent = STRBUF_INIT;
124 + struct object_id unused_oid;
125 + unsigned int unused_type;
126 + int failure_errno = 0;
127 + const char *ref;
128 + int ret = 0;
129 + const char * const exists_usage[] = {
130 + REFS_EXISTS_USAGE,
131 + NULL,
132 + };
133 + struct option options[] = {
134 + OPT_END(),
135 + };
136 +
137 + argc = parse_options(argc, argv, prefix, options, exists_usage, 0);
138 + if (argc != 1)
139 + die(_("'git refs exists' requires a reference"));
140 +
141 + ref = *argv++;
142 + if (refs_read_raw_ref(get_main_ref_store(the_repository), ref,
143 + &unused_oid, &unused_referent, &unused_type,
144 + &failure_errno)) {
145 + if (failure_errno == ENOENT || failure_errno == EISDIR) {
146 + error(_("reference does not exist"));
147 + ret = 2;
148 + } else {
149 + errno = failure_errno;
150 + error_errno(_("failed to look up reference"));
151 + ret = 1;
152 + }
153 +
154 + goto out;
155 + }
156 +
157 +out:
158 + strbuf_release(&unused_referent);
159 + return ret;
160 +}
161 +
162 int cmd_refs(int argc,
163 const char **argv,
164 const char *prefix,
@@ -122,6 +168,7 @@ int cmd_refs(int argc,
168 REFS_MIGRATE_USAGE,
169 REFS_VERIFY_USAGE,
170 "git refs list " COMMON_USAGE_FOR_EACH_REF,
171 + REFS_EXISTS_USAGE,
172 NULL,
173 };
174 parse_opt_subcommand_fn *fn = NULL;
@@ -129,6 +176,7 @@ int cmd_refs(int argc,
176 OPT_SUBCOMMAND("migrate", &fn, cmd_refs_migrate),
177 OPT_SUBCOMMAND("verify", &fn, cmd_refs_verify),
178 OPT_SUBCOMMAND("list", &fn, cmd_refs_list),
179 + OPT_SUBCOMMAND("exists", &fn, cmd_refs_exists),
180 OPT_END(),
181 };
182