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

[John Cai <johncai86@gmail.com>]

Hi Junio,

On 4 Mar 2024, at 18:23, Junio C Hamano wrote:

> "John Cai via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> 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.

Yeah good point. The language could be made more precise.

>
>>  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.
>
>> -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

I like this option. It makes it clear that it's a symbolic ref without adding
additional output to the command.

cc'ing Patrick here for his thoughts as well since he has interest in this topic.

>
> 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.

I think something like --no-dereference that was suggested in [1] could work
since the concept of dereferencing should be familiar to the user. However, this
maybe confusing because of the existing --dereference flag that is specific to
tags...

1. https://lore.kernel.org/git/a3de2b7b-4603-4604-a4d2-938a598e312e@gmail.com/

thanks
John