pack-write: add explanation to promisor file content

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.

As explained in the log message of commit 5374a290 (fetch-pack: write
fetched refs to .promisor, 2019-10-14), where this loop originally came
from, these ref names (and associated hashes) are not used for anything
in the production, but are solely there to help debugging.

Explain this in a new comment.

Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: LorenzoPegorari <lorenzo.pegorari2002@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/pack-write.c b/pack-write.c
index 83eaf88541eefb79e3933cb54783182cbddf88f6..b8ab9510fff098a335495ab43ab14b5606761bea 100644 (file)
--- a/pack-write.c
+++ b/pack-write.c
@@ -603,6 +603,15 @@ void write_promisor_file(const char *promisor_name, struct ref **sought, int nr_
        int i, err;
        FILE *output = xfopen(promisor_name, "w");
 
+       /*
+        * 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.
+        */
        for (i = 0; i < nr_sought; i++)
                fprintf(output, "%s %s\n", oid_to_hex(&sought[i]->old_oid),
                        sought[i]->name);