Re: [GSoC PATCH v2 1/4] pack-write: add explanation to promisor file content
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Mar 23, 2026, 21:07 UTC
- Message-ID
- <xmqqmrzy45m4.fsf@gitster.g>
- In-Reply-To
- <fec0c24897092d19a718563ca4ef6e509ab104e6.1774205661.git.lorenzo.pegorari2002@gmail.com>
LorenzoPegorari <lorenzo.pegorari2002@gmail.com> writes:
Show 8 quoted lines
> In the entire codebase there is no explanation as to why the ".promisor" > files may contain the ref names (and their associated hashes) that were > fetched at the time the corresponding packfile was downloaded. > > Add comment explaining that these pieces of information are used only for > debugging reasons, and how they can be used while debugging. > > Signed-off-by: LorenzoPegorari <lorenzo.pegorari2002@gmail.com>
A natural question any reader of the above (and below) would be asking is: Who told you that these are only to aid debugging?
Please refer to the commit that brought in the reasoning behind the comment to make it more convincing.
Something like this replacing the second paragraph,
As explained in the log message of the commit 5374a290
(fetch-pack: write fetched refs to .promisor, 2019-10-14), where
this loop originally came from, these ref values are not
actually used for anything in the production, but are solely
there to help debugging. Explain it in a new comment.perhaps?
Show 9 quoted lines
> + /* > + * Write in the .promisor file the ref names and associated hashes, > + * obtained by fetch-pack, at the point of generation of the > + * corresponding packfile. These pieces of info are only used to make > + * it easier to debug issues with partial clones, as we can identify > + * what refs (and their associated hashes) were fetched at the time > + * the packfile was downloaded, and if necessary, compare those hashes > + * against what the promisor remote reports now. > + */
I do not want to sound too pedantic, but we align '*' asterisks in our multi-line comments, assuming tabwidth=8 and monospace:
/* * Write in the .promisor ... ... * against what the promisor remote reports now. */
Your second and subsequent lines lack a single whitespace after the leading tab used for indent.
> for (i = 0; i < nr_sought; i++) > fprintf(output, "%s %s\n", oid_to_hex(&sought[i]->old_oid), > sought[i]->name);