You have another option beside git rev-parse
/git cat-file
/git show
git show-ref --exists
With Git 2.43 (Q4 2023), rc1, teach "git show-ref
"(man) a mode to check the existence of a ref.
See commit 0497e6c, commit 9080a7f, commit 1307d5e, commit 199970e, commit ee26f1e, commit b0f0be9, commit 8465098, commit 7907fb0, commit 53921d5, commit dbabd0b, commit b14cbae, commit ff546eb (31 Oct 2023) by Patrick Steinhardt (pks-t
).
(Merged by Junio C Hamano -- gitster
-- in commit d8972a5, 08 Nov 2023)
builtin/show-ref
: add new mode to check for reference existence
Signed-off-by: Patrick Steinhardt
While we have multiple ways to show the value of a given reference, we do not have any way to check whether a reference exists at all.
While commands like git-rev-parse(1) or git-show-ref(1) can be used to check for reference existence in case the reference resolves to something sane, neither of them can be used to check for existence in some other scenarios where the reference does not resolve cleanly:
- References which have an invalid name cannot be resolved.
- References to nonexistent objects cannot be resolved.
- Dangling symrefs can be resolved via git-symbolic-ref(1), but this requires the caller to special case existence checks depending on whether or not a reference is symbolic or direct.
Furthermore, git-rev-list(1) and other commands do not let the caller distinguish easily between an actually missing reference and a generic error.
Taken together, this seems like sufficient motivation to introduce a separate plumbing command to explicitly check for the existence of a reference without trying to resolve its contents.
This new command comes in the form of git show-ref --exists
(man).
This new mode will exit successfully when the reference exists, with a specific exit code of 2 when it does not exist, or with 1 when there has been a generic error.
Note that the only way to properly implement this command is by using the internal refs_read_raw_ref()
function.
While the public function refs_resolve_ref_unsafe()
can be made to behave in the same way by passing various flags, it does not provide any way to obtain the errno with which the reference backend failed when reading the reference.
As such, it becomes impossible for us to distinguish generic errors from the explicit case where the reference wasn't found.
git show-ref
now includes in its man page:
The --exists
form can be used to check for the existence of a single
references. This form does not verify whether the reference resolves to an
actual object.
git show-ref
now includes in its man page:
--exists
Check whether the given reference exists.
Returns an exit code of:
- 0 if it does,
- 2 if it is missing, and
- 1 in case looking up the reference failed with an error other than the reference being missing.
With Git 2.44 (Q1 2024), batch 11, update to a new feature recently added, "git show-ref --exists
"(man).
See commit 0aabeaa (10 Jan 2024) by Toon Claes (To1ne
).
(Merged by Junio C Hamano -- gitster
-- in commit cf58f59, 29 Jan 2024)
builtin/show-ref
: treat directory as non-existing in --exists
Signed-off-by: Toon Claes
9080a7f ("builtin/show-ref
: add new mode to check for reference existence", 2023-10-31, Git v2.43.0-rc1 -- merge) added the option --exists
to git-show-ref(1).
When you use this option against a ref that doesn't exist, but it is a parent directory of an existing ref, you get the following error:
$ git show-ref --exists refs/heads
error: failed to look up reference: Is a directory
when the ref-files backend is in use.
To be more clear to user, hide the error about having found a directory.
What matters to the user is that the named ref does not exist.
Instead, print the same error as when the ref was not found:
error: reference does not exist
As an alternative, "git show-ref --verify
"(man) accepts pseudorefs.
It did not show things like "CHERRY_PICK_HEAD",
which has been corrected with Git 2.44 (Q1 2024), rc1.
See commit 1af410d, commit 1dbe401 (07 Feb 2024) by Phillip Wood (phillipwood
).
(Merged by Junio C Hamano -- gitster
-- in commit b3370dd, 12 Feb 2024)
Signed-off-by: Phillip Wood
"git show-ref --verify
"(man) is useful for scripts that want to look up a fully qualified refname without falling back to the DWIM rules used by git rev-parse
(man) rules when the ref does not exist.
Currently it will only accept "HEAD" or a refname beginning with "refs/".
Running
git show-ref --verify CHERRY_PICK_HEAD
will always result in
fatal: 'CHERRY_PICK_HEAD' - not a valid ref
even when CHERRY_PICK_HEAD
exists.
By calling refname_is_safe()
instead of comparing the refname to "HEAD" we can accept all one-level refs that contain only uppercase ascii letters and underscores.