Re: [PATCH] show-ref: add --unresolved option

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 4, 2024, 23:23 UTC
Message-ID: <xmqqplw9mviu.fsf@gitster.g>
In-Reply-To: <pull.1684.git.git.1709592718743.gitgitgadget@gmail.com>

"John Cai via GitGitGadget" <gitgitgadget@gmail.com> writes:

Show 8 quoted lines

> From: John Cai <johncai86@gmail.com>
>
> For reftable development, it would be handy to have a tool to provide
> the direct value of any ref whether it be a symbolic ref or not.
> Currently there is git-symbolic-ref, which only works for symbolic refs,
> and git-rev-parse, which will resolve the ref. Let's add a --unresolved
> option that will only take one ref and return whatever it points to
> without dereferencing it.

The approach may be reasonble, but the above description can use some improvements.

 * Even though the title of the patch says show-ref, the last
   sentence is a bit too far from there and it was unclear to what
   you are adding a new feature at least to me during my first read.

      Let's teach show-ref a `--unresolved` optionthat will ...

   may make it easier to follow.

 * "Whatever it points to without dereferencing it" implied that it
   assumes what it is asked to show can be dereferenced, which
   invites a natural question: what happens to a thing that is not
   dereferenceable in the first place?  The implementation seems to
   show either symbolic-ref target (for symbolic refs) or the object
   name (for others), but let's make it easier for readers.

Show 27 quoted lines

>  Documentation/git-show-ref.txt |  8 ++++++
>  builtin/show-ref.c             | 33 ++++++++++++++++--------
>  t/t1403-show-ref.sh            | 47 ++++++++++++++++++++++++++++++++++
>  3 files changed, 77 insertions(+), 11 deletions(-)
>
> diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt
> index ba757470059..2f9b4de1346 100644
> --- a/Documentation/git-show-ref.txt
> +++ b/Documentation/git-show-ref.txt
> @@ -16,6 +16,7 @@ SYNOPSIS
>  	     [--] [<ref>...]
>  'git show-ref' --exclude-existing[=<pattern>]
>  'git show-ref' --exists <ref>
> +'git show-ref' --unresolved <ref>
>  
>  DESCRIPTION
>  -----------
> @@ -76,6 +77,13 @@ OPTIONS
>  	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.
>  
> +--unresolved::
> +
> +	Prints out what the reference points to without resolving it. 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.

Exactly the same issue as in the proposed log message, i.e. what is printed for what kind of ref is not really clear.

Show 32 quoted lines

> -static int cmd_show_ref__exists(const char **refs)
> +static int cmd_show_ref__raw(const char **refs, int show)
>  {
> -	struct strbuf unused_referent = STRBUF_INIT;
> -	struct object_id unused_oid;
> -	unsigned int unused_type;
> +	struct strbuf referent = STRBUF_INIT;
> +	struct object_id oid;
> +	unsigned int type;
>  	int failure_errno = 0;
>  	const char *ref;
>  	int ret = 0;
> @@ -236,7 +237,7 @@ static int cmd_show_ref__exists(const char **refs)
>  		die("--exists requires exactly one reference");
>  
>  	if (refs_read_raw_ref(get_main_ref_store(the_repository), ref,
> -			      &unused_oid, &unused_referent, &unused_type,
> +			      &oid, &referent, &type,
>  			      &failure_errno)) {
>  		if (failure_errno == ENOENT || failure_errno == EISDIR) {
>  			error(_("reference does not exist"));
> @@ -250,8 +251,16 @@ static int cmd_show_ref__exists(const char **refs)
>  		goto out;
>  	}
>  
> +		if (!show)
> +			goto out;
> +
> +		if (type & REF_ISSYMREF)
> +			printf("ref: %s\n", referent.buf);
> +		else
> +			printf("ref: %s\n", oid_to_hex(&oid));

If I create a symbolic ref whose value is deadbeef....deadbeef 40-hex, I cannot tell from this output if it is a symbolic ref of a ref that stores an object whose name is that hash. Reserve the use of "ref: %s" to the symbolic refs (so that it will also match how the files backend stores them in modern Git), and use some other prefix (or no perfix).

Actually, I am not sure if what is proposed is even a good interface. Given a repository with these few refs:

    $ git show-ref refs/heads/master
    b387623c12f3f4a376e4d35a610fd3e55d7ea907 refs/heads/master
    $ git show-ref refs/remotes/repo/HEAD
    b387623c12f3f4a376e4d35a610fd3e55d7ea907 refs/remotes/repo/HEAD
    $ git symbolic-ref refs/remotes/repo/HEAD
    refs/remotes/repo/master

I would think that the second command above shows the gap in feature set our current "show-ref" has. If we could do

    $ git show-ref --<option> refs/heads/master refs/remotes/repo/HEAD
    b387623c12f3f4a376e4d35a610fd3e55d7ea907 refs/heads/master
    ref:refs/remotes/repo/master refs/remotes/repo/HEAD

or alternatively

    $ git show-ref --<option> refs/heads/master refs/remotes/repo/HEAD
    b387623c12f3f4a376e4d35a610fd3e55d7ea907 refs/heads/master
    ref:refs/remotes/repo/master b387623c12f3f4a376e4d35a610fd3e55d7ea907 refs/remotes/repo/HEAD

wouldn't it match the existing feature set better? You also do not have to limit yourself to single ref query per process invocation.

I am not sure if you need to worry about quoting of the values of symbolic-ref, though. You _might_ need to move the (optional) symref information to the end, i.e. something like this you might prefer. I dunno.

    $ git show-ref --<option> refs/remotes/repo/HEAD
    b387623c12f3f4a376e4d35a610fd3e55d7ea907 refs/remotes/repo/HEAD refs/remotes/repo/master

I do not know what the <option> should be called, either. From an end-user's point of view, the option tells the command to also report which ref the ref points at, if it were a symbolic one. "unresolved" may be technically acceptable name to those who know the underlying implementation (i.e. we tell read_raw_ref not to resolve when it does its thing), but I am afraid that is a bit too opaque implementation detail for end-users who are expected to learn this option.