From: Patrick Steinhardt <ps@pks.im>
Date: Thu, 25 Sep 2025 13:58:42 GMT
Subject: Re: [PATCH v2 5/6] builtin/repo: add keyvalue and nul format for stats
Message-ID: <aNVKki1hXoYi8qCV@pks.im>
In-Reply-To: <lqzdrznf6kynr35eo74zodbfeofj6hnmskm2wqk6ty3o7wwaci@nyytil34eyzq>

On Thu, Sep 25, 2025 at 08:16:06AM -0500, Justin Tobler wrote:
> On 25/09/25 07:39AM, Patrick Steinhardt wrote:
> > On Wed, Sep 24, 2025 at 04:24:25PM -0500, Justin Tobler wrote:
> > > diff --git a/Documentation/git-repo.adoc b/Documentation/git-repo.adoc
> > > index 0b8d74ed3e..db21b75522 100644
> > > --- a/Documentation/git-repo.adoc
> > > +++ b/Documentation/git-repo.adoc
> > > @@ -52,7 +52,26 @@ supported:
> > >  * Reachable object counts categorized by type
> > >  
> > >  +
> > > -The table output format may change and is not intended for machine parsing.
> > > +The output format can be chosen through the flag `--format`. Three formats are
> > > +supported:
> > > ++
> > > +`table`:::
> > > +	Outputs repository stats in a human-friendly table and is used by
> > > +	default. This format may change and is not intended for machine
> > > +	parsing.
> > 
> > Let's mention that this is the default format.
> 
> I didn't mention that it is "used by default", but I think the wording
> could be more clear here. Will improve in the next version.

Oh, I completely missed this. I guess I was looking for a sentence like
"This is the default." at the end of this paragraph, which is what we
often use in other parts.

> > > +`keyvalue`:::
> > > +	Each line of output contains a key-value pair for a repository stat.
> > > +	The '=' character is used to delimit between the key and the value.
> > > +	Values containing "unusual" characters are quoted as explained for the
> > > +	configuration variable `core.quotePath` (see linkgit:git-config[1]).
> > 
> > In the current state there is never any quoting, so this statement here
> > is a bit misleading. Should we maybe drop that part?
> 
> While there are currently not any values in the output that would
> require quoting, I'm inclined to leave this note in the documentation.
> That way we set the expectation regarding how parsers should handle the
> output from the start.

Fair enough.

> > > @@ -407,8 +447,20 @@ static int cmd_repo_stats(int argc UNUSED, const char **argv UNUSED,
> > >  	stats_count_references(&stats.refs, &refs);
> > >  	stats_count_objects(&stats.objects, &refs, &revs);
> > >  
> > > -	stats_table_setup(&table, &stats);
> > > -	stats_table_print(&table);
> > > +	switch (format) {
> > > +	case FORMAT_TABLE:
> > > +		stats_table_setup(&table, &stats);
> > > +		stats_table_print(&table);
> > > +		break;
> > > +	case FORMAT_KEYVALUE:
> > > +		stats_keyvalue_print(&stats, '=', '\n');
> > > +		break;
> > > +	case FORMAT_NUL_TERMINATED:
> > > +		stats_keyvalue_print(&stats, '\n', '\0');
> > > +		break;
> > 
> > This reads much nicer now. The newline as key-value delimiter is a
> > curious choice, but you simply do what we already do in `git repo info`.
> 
> I agree that the key-value delimiter chosen is a bit strange. The
> command is still experimental so we could maybe change it if want. Not
> sure if it would be worth it though.

Dunno. If we wanted to do it I'd do it in a follow-up patch series
anyway.

Patrick