patchbuiltin/refs: add 'get' subcommand

> Le 23 sept. 2025 à 06:47, Meet Soni <meetsoni3017@gmail.com> a écrit :
> 
> While `git-rev-parse(1)` and `git-show-ref(1)` can be used to read
> reference values, they have drawbacks for scripting and discoverability.
> `rev-parse` performs DWIM expansion which is unpredictable for scripts,

> To address this, introduce a new plumbing command, `git refs get <ref>`.
> This new command provides three key advantages:
> 
>  - It requires an exact refname and does not perform expansion, making
>    it safer and more predictable for scripting.

> With apologies if I cover well-trodden ground, as I haven’t been closely following this effort.
> 
> > Le 23 sept. 2025 à 06:47, Meet Soni <meetsoni3017@gmail.com> a écrit :
> > 
> > While `git-rev-parse(1)` and `git-show-ref(1)` can be used to read
> > reference values, they have drawbacks for scripting and discoverability.
> > `rev-parse` performs DWIM expansion which is unpredictable for scripts,
> 
> [snip]
> 
> > To address this, introduce a new plumbing command, `git refs get <ref>`.
> > This new command provides three key advantages:
> > 
> >  - It requires an exact refname and does not perform expansion, making
> >    it safer and more predictable for scripting.
> 
> What are the disadvantages of rev-parse’s DWIMmery in scripts? I would
> think it makes handling user input easier (e.g., my custom script can
> take a local branch name without writing « refs/heads/ » on the
> command-line). OTOH, a script that wants to precisely identify a ref
> can do so already, no?
> 
> Since rev-parse presumably won’t go away, it might be ok to have 2
> ways of parsing (one with magic and one without), but that might be
> back to the same boat of not having a unified interface 😅
> 
> Perhaps later we can add a « --dwim » flag for looser parsing, giving
> scripteds flexibility but strictness by default?

> While `git-rev-parse(1)` and `git-show-ref(1)` can be used to read
> reference values, they have drawbacks for scripting and discoverability.
> `rev-parse` performs DWIM expansion which is unpredictable for scripts,
> and `show-ref --verify` is difficult to discover and cannot read the
> direct target of a symbolic reference.

> Meet Soni <meetsoni3017@gmail.com> writes:
> 
> > While `git-rev-parse(1)` and `git-show-ref(1)` can be used to read
> > reference values, they have drawbacks for scripting and discoverability.
> > `rev-parse` performs DWIM expansion which is unpredictable for scripts,
> > and `show-ref --verify` is difficult to discover and cannot read the
> > direct target of a symbolic reference.
> 
> Well "refs get" is even harder to discover (it is not even in Git
> 2.50's manual that is available everywhere on the net), so difficult
> to discover is not a good excuse.  In a sense show-ref was invented
> exactly to serve as something like "refs get" you are writing, so I
> wonder if a better approach is to extend it instead of introducing
> a new subcommand in a distant place from it?
> 
> Perhaps "show-ref --verify --no-deref" or something that does not
> dereference but works directly on a symbolic ref?

> Le 24 sept. 2025 à 02:37, Patrick Steinhardt <ps@pks.im> a écrit :
> 
> On Tue, Sep 23, 2025 at 02:50:46PM -0700, Junio C Hamano wrote:
>> Meet Soni <meetsoni3017@gmail.com> writes:
>> 
>>> While `git-rev-parse(1)` and `git-show-ref(1)` can be used to read
>>> reference values, they have drawbacks for scripting and discoverability.
>>> `rev-parse` performs DWIM expansion which is unpredictable for scripts,
>>> and `show-ref --verify` is difficult to discover and cannot read the
>>> direct target of a symbolic reference.
>> 
>> Well "refs get" is even harder to discover (it is not even in Git
>> 2.50's manual that is available everywhere on the net), so difficult
>> to discover is not a good excuse.  In a sense show-ref was invented
>> exactly to serve as something like "refs get" you are writing, so I
>> wonder if a better approach is to extend it instead of introducing
>> a new subcommand in a distant place from it?
>> 
>> Perhaps "show-ref --verify --no-deref" or something that does not
>> dereference but works directly on a symbolic ref?
> 
> For now: yes, it's more difficult to discover for sure. But users will
> adjust over time as they get more familiar with git-refs(1), and from
> thereon I think it will become significantly easier to discover that
> subcommand.

>>> Perhaps "show-ref --verify --no-deref" or something that does not
>>> dereference but works directly on a symbolic ref?
>> 
>> For now: yes, it's more difficult to discover for sure. But users will
>> adjust over time as they get more familiar with git-refs(1), and from
>> thereon I think it will become significantly easier to discover that
>> subcommand.

> I think this goes to perhaps some of my unasked questions: who is
> the target audience? My experience suggest that most
> mostly-porcelain users don’t acquire familiarity with scripting
> commands, so it sounds like we’re talking about script-writers
> here (and in the commit message).
>
> But how do we encourage script writers to discover these things? 🤔 Hm. 

> Ben Knoble <ben.knoble@gmail.com> writes:
> 
> >>> Perhaps "show-ref --verify --no-deref" or something that does not
> >>> dereference but works directly on a symbolic ref?
> >> 
> >> For now: yes, it's more difficult to discover for sure. But users will
> >> adjust over time as they get more familiar with git-refs(1), and from
> >> thereon I think it will become significantly easier to discover that
> >> subcommand.
> 
> But unfortunately, that is a tautology, isn't it?  With the same
> effort to advertise git-refs to make it more familiar to the
> "users", you can make "show-ref" familiar to the same "users", and
> problem solved, without a need to do anything to "git-refs"?

> > I think this goes to perhaps some of my unasked questions: who is
> > the target audience? My experience suggest that most
> > mostly-porcelain users don’t acquire familiarity with scripting
> > commands, so it sounds like we’re talking about script-writers
> > here (and in the commit message).
> >
> > But how do we encourage script writers to discover these things? 🤔 Hm. 
> 
> Great question.  I understand what the patch author is trying to
> achieve (i.e. "consolidate ref-related functionality into git-refs",
> which is the title of GSoC project [*]), but what are we, as Git
> project, trying to achive by "consolidating"?  I often cannot shake
> the feeling that it may a make-work job without a clear answer to
> that question.  Or perhps xkcd.com/927/?
> 
> Perhaps the hope is to have a single kitchen sink "git refs" command
> that does anything related to "refs", so that they only need to
> learn this single command (and unlearn all the previous experiences
> they gained) and after that, they do not have to "discover" more
> things?

>
> On Wed, Sep 24, 2025 at 10:11:08AM -0700, Junio C Hamano wrote:
> > Ben Knoble <ben.knoble@gmail.com> writes:
> >
> > >>> Perhaps "show-ref --verify --no-deref" or something that does not
> > >>> dereference but works directly on a symbolic ref?
> > >>
> > >> For now: yes, it's more difficult to discover for sure. But users will
> > >> adjust over time as they get more familiar with git-refs(1), and from
> > >> thereon I think it will become significantly easier to discover that
> > >> subcommand.
> >
> > But unfortunately, that is a tautology, isn't it?  With the same
> > effort to advertise git-refs to make it more familiar to the
> > "users", you can make "show-ref" familiar to the same "users", and
> > problem solved, without a need to do anything to "git-refs"?
>
> I don't quite think so. The problem is that we have so many different
> tools that relate to refs, and you have to remember all of them:
>
>   - `git show-refs --verify` to read a single reference, unless it's a
>     symbolic reference.
>
>   - `git symbolic-ref` to read symbolic refs.
>
>   - `git show-refs --exists` to check a reference for existence.
>
>   - `git show-ref` and `git for-each-ref` to list references.
>
>   - `git pack-refs` to optimize references.
>
>   - `git update-refs` to update references`
>
> I'd claim that this is quite hard to remember. So...

> > > I think this goes to perhaps some of my unasked questions: who is
> > > the target audience? My experience suggest that most
> > > mostly-porcelain users don’t acquire familiarity with scripting
> > > commands, so it sounds like we’re talking about script-writers
> > > here (and in the commit message).
> > >
> > > But how do we encourage script writers to discover these things? 🤔 Hm.
> >
> > Great question.  I understand what the patch author is trying to
> > achieve (i.e. "consolidate ref-related functionality into git-refs",
> > which is the title of GSoC project [*]), but what are we, as Git
> > project, trying to achive by "consolidating"?  I often cannot shake
> > the feeling that it may a make-work job without a clear answer to
> > that question.  Or perhps xkcd.com/927/?
> >
> > Perhaps the hope is to have a single kitchen sink "git refs" command
> > that does anything related to "refs", so that they only need to
> > learn this single command (and unlearn all the previous experiences
> > they gained) and after that, they do not have to "discover" more
> > things?
>
> ... yes, this is exactly the goal of this exercise. You basically only
> need to know about the entrypoint git-refs(1). Once you know about it,
> you don't have to discover all the other commands, as it is now way
> easier to discover what ref-related functionality you have available.
> You can easily use tab completion (well, once it's wired up), type `git
> refs -h` to learn about evertyhing refs, and we now have a single
> manpage that will tell you everything about ref-related use commands.

> You could partially address that problem by providing a gitrefs(5)
> manpage that gives an overview. And maybe that's still something one
> could do, also to paint a bit of a broader picture. But documentation is
> only part of the solution -- with git-refs(1) we get some "natural"
> discoverability.
>
> That's also where the "git refs get" proposal comes from. Sure, you can
> use `git show-refs --verify`, potentially with a `--no-dereference` flag
> if you want to read normal refs. But I would claim that this is almost
> impossible to discover without searching through our manpages.
>
> Patrick

>>   - `git show-refs --verify` to read a single reference, unless it's a
>>     symbolic reference.
>>
>>   - `git symbolic-ref` to read symbolic refs.
>>
>>   - `git show-refs --exists` to check a reference for existence.
>>
>>   - `git show-ref` and `git for-each-ref` to list references.
>>
>>   - `git pack-refs` to optimize references.
>>
>>   - `git update-refs` to update references`
>>
>> I'd claim that this is quite hard to remember. So...
>
> Agreed! To be clear: me asking questions should be taken as support
> for this exercise :)

> diff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc
> index bfa9b3ea2d..f07fe8c864 100644
> --- a/Documentation/git-refs.adoc
> +++ b/Documentation/git-refs.adoc
> @@ -19,6 +19,7 @@ git refs list [--count=<count>] [--shell|--perl|--python|--tcl]
>  		   [(--exclude=<pattern>)...] [--start-after=<marker>]
>  		   [ --stdin | (<pattern>...)]
>  git refs exists <ref>
> +git refs get <ref>
>  
>  DESCRIPTION
>  -----------
> @@ -45,6 +46,12 @@ exists::
>  	failed with an error other than the reference being missing. This does
>  	not verify whether the reference resolves to an actual object.
>  
> +get::
> +	Reads the raw value of a single, exact reference. Instead of

> diff --git a/builtin/refs.c b/builtin/refs.c
> index 91548783b7..b473a78e18 100644
> --- a/builtin/refs.c
> +++ b/builtin/refs.c
> @@ -159,6 +163,43 @@ static int cmd_refs_exists(int argc, const char **argv, const char *prefix,
>  	return ret;
>  }
>  
> +static int cmd_refs_get(int argc, const char **argv, const char *prefix,
> +			struct repository *repo UNUSED)
> +{
> +	const char *refname;
> +	struct object_id oid;
> +	unsigned int type;
> +	int failure_errno = 0;
> +	struct strbuf referent = STRBUF_INIT;

> +	const char * const exists_usage[] = {
> +		REFS_EXISTS_USAGE,
> +		NULL,
> +	};
> +	struct option options[] = {
> +		OPT_END(),
> +	};
> +
> +	argc = parse_options(argc, argv, prefix, options, exists_usage, 0);
> +	if (argc != 1)
> +		die("refs get requires exactly one reference");

> +	}
> +
> +	if (type & REF_ISSYMREF) {
> +		printf("ref: %s\n", referent.buf);
> +	} else {
> +		printf("%s\n", oid_to_hex(&oid));
> +	}