{"thread":{"id":"63761","subject":"[PATCH] docs/git-pack-refs: document heuristic used for packing loose refs","startedAt":"2025-07-08T11:24:02Z","lastAt":"2025-07-08T20:45:21Z","messageCount":4,"participants":["Patrick Steinhardt","Karthik Nayak","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"521534","messageId":"20250708-b4-pks-pack-refs-document-files-heuristic-v1-1-e28d65a94573@pks.im","threadId":"63761","inReplyTo":null,"subject":"[PATCH] docs/git-pack-refs: document heuristic used for packing loose refs","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2025-07-08T11:23:56Z","receivedAt":"2025-07-08T11:24:02Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"The `git pack-refs --auto` flag asks the ref backend to decide for\nitself whether or not references need to be repacked. This is done to\nensure that we don't repack in cases where the backend is already in a\ngood-enough state, which is typically the case for the \"reftable\"\nbackend that performs auto-compaction on writes.\n\nAs such, we initially only had heuristics in place for the \"reftable\"\nbackend. The \"files\" backend didn't have any heuristics, so we'd repack\nloose references every time `git pack-refs --auto` was executed. This\ncaused excessive repacking with that backend though, which is why we\neventually implemented a heuristic via c3459ae9ef2 (refs/files: use\nheuristic to decide whether to repack with `--auto`, 2024-09-04).\n\nThe documentation for the `--auto` flag hasn't been updated accordingly\nand still claims that we don't have any metrics for the \"files\" backend.\nUpdate it to reflect the new reality.\n\nReported-by: Karthik Nayak \nSigned-off-by: Patrick Steinhardt \n---\nHi,\n\na small fix for our out-of-date documentation, as discovered by Karthik.\n\nThanks!\n\nPatrick\n---\n Documentation/git-pack-refs.adoc | 5 ++++-\n 1 file changed, 4 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-pack-refs.adoc b/Documentation/git-pack-refs.adoc\nindex 652c5497715..42b90051e69 100644\n--- a/Documentation/git-pack-refs.adoc\n+++ b/Documentation/git-pack-refs.adoc\n@@ -66,7 +66,10 @@ Pack refs as needed depending on the current state of the ref database. The\n behavior depends on the ref format used by the repository and may change in the\n future.\n +\n-\t- \"files\": No special handling for `--auto` has been implemented.\n+\t- \"files\": Loose references are packed into the `packed-refs` file\n+\t based on the ratio of loose references to the size of the\n+\t `packed-refs` file. The bigger the `packed-refs` file, the more loose\n+\t references need to exist before we repack.\n +\n \t- \"reftable\": Tables are compacted such that they form a geometric\n \t sequence. For two tables N and N+1, where N+1 is newer, this\n\n---\nbase-commit: 41905d60226a0346b22f0d0d99428c746a5a3b14\nchange-id: 20250708-b4-pks-pack-refs-document-files-heuristic-58a9df3df946\n\n"},{"id":"521536","messageId":"CAOLa=ZSmY8ooXL1c-jE7tqjfMuz2o+wkWaV6W3_XXQFncv0JrA@mail.gmail.com","threadId":"63761","inReplyTo":"20250708-b4-pks-pack-refs-document-files-heuristic-v1-1-e28d65a94573@pks.im","subject":"Re: [PATCH] docs/git-pack-refs: document heuristic used for packing loose refs","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2025-07-08T11:43:42Z","receivedAt":"2025-07-08T11:43:44Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Patrick Steinhardt writes:\n\n> The `git pack-refs --auto` flag asks the ref backend to decide for\n> itself whether or not references need to be repacked. This is done to\n> ensure that we don't repack in cases where the backend is already in a\n> good-enough state, which is typically the case for the \"reftable\"\n> backend that performs auto-compaction on writes.\n>\n> As such, we initially only had heuristics in place for the \"reftable\"\n> backend. The \"files\" backend didn't have any heuristics, so we'd repack\n> loose references every time `git pack-refs --auto` was executed. This\n> caused excessive repacking with that backend though, which is why we\n> eventually implemented a heuristic via c3459ae9ef2 (refs/files: use\n> heuristic to decide whether to repack with `--auto`, 2024-09-04).\n>\n> The documentation for the `--auto` flag hasn't been updated accordingly\n> and still claims that we don't have any metrics for the \"files\" backend.\n> Update it to reflect the new reality.\n>\n> Reported-by: Karthik Nayak \n> Signed-off-by: Patrick Steinhardt \n> ---\n> Hi,\n>\n> a small fix for our out-of-date documentation, as discovered by Karthik.\n>\n> Thanks!\n>\n> Patrick\n> ---\n> Documentation/git-pack-refs.adoc | 5 ++++-\n> 1 file changed, 4 insertions(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git-pack-refs.adoc b/Documentation/git-pack-refs.adoc\n> index 652c5497715..42b90051e69 100644\n> --- a/Documentation/git-pack-refs.adoc\n> +++ b/Documentation/git-pack-refs.adoc\n> @@ -66,7 +66,10 @@ Pack refs as needed depending on the current state of the ref database. The\n> behavior depends on the ref format used by the repository and may change in the\n> future.\n> +\n> -\t- \"files\": No special handling for `--auto` has been implemented.\n> +\t- \"files\": Loose references are packed into the `packed-refs` file\n> +\t based on the ratio of loose references to the size of the\n> +\t `packed-refs` file. The bigger the `packed-refs` file, the more loose\n> +\t references need to exist before we repack.\n> +\n\nNice. The explanation has sufficient information without going too much\ninto detail. Perhaps a small nit would be s/ratio/logarithmic ratio/,\nbut I'm happy with this as is.\n\nThanks\n\n> \t- \"reftable\": Tables are compacted such that they form a geometric\n> \t sequence. For two tables N and N+1, where N+1 is newer, this\n>\n> ---\n> base-commit: 41905d60226a0346b22f0d0d99428c746a5a3b14\n> change-id: 20250708-b4-pks-pack-refs-document-files-heuristic-58a9df3df946\n"},{"id":"521537","messageId":"aG0FcY_SVqe9pe4A@pks.im","threadId":"63761","inReplyTo":"CAOLa=ZSmY8ooXL1c-jE7tqjfMuz2o+wkWaV6W3_XXQFncv0JrA@mail.gmail.com","subject":"Re: [PATCH] docs/git-pack-refs: document heuristic used for packing loose refs","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2025-07-08T11:48:01Z","receivedAt":"2025-07-08T11:48:07Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Tue, Jul 08, 2025 at 04:43:42AM -0700, Karthik Nayak wrote:\n> Patrick Steinhardt writes:\n> > diff --git a/Documentation/git-pack-refs.adoc b/Documentation/git-pack-refs.adoc\n> > index 652c5497715..42b90051e69 100644\n> > --- a/Documentation/git-pack-refs.adoc\n> > +++ b/Documentation/git-pack-refs.adoc\n> > @@ -66,7 +66,10 @@ Pack refs as needed depending on the current state of the ref database. The\n> > behavior depends on the ref format used by the repository and may change in the\n> > future.\n> > +\n> > -\t- \"files\": No special handling for `--auto` has been implemented.\n> > +\t- \"files\": Loose references are packed into the `packed-refs` file\n> > +\t based on the ratio of loose references to the size of the\n> > +\t `packed-refs` file. The bigger the `packed-refs` file, the more loose\n> > +\t references need to exist before we repack.\n> > +\n> \n> Nice. The explanation has sufficient information without going too much\n> into detail. Perhaps a small nit would be s/ratio/logarithmic ratio/,\n> but I'm happy with this as is.\n\nI was very much on the fence on whether to add \"logarithmic\" in there or\nnot. I ultimately felt like it hinted too much at how exactly it works\nwithout really giving enough information to fully understand it, so it\nfelt a bit useless to me to add \"logarithmic\".\n\nI don't have a strong opinion though, and it doesn't seem like you feel\nstrongly about it, either. So for now I'll keep this as-is, but I'm\nhappy to change it if others also have a slight preference for adding\nthe word in.\n\nThanks!\n\nPatrick\n"},{"id":"521570","messageId":"xmqqqzyqtns0.fsf@gitster.g","threadId":"63761","inReplyTo":"20250708-b4-pks-pack-refs-document-files-heuristic-v1-1-e28d65a94573@pks.im","subject":"Re: [PATCH] docs/git-pack-refs: document heuristic used for packing loose refs","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-07-08T20:45:19Z","receivedAt":"2025-07-08T20:45:21Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt writes:\n\n> Reported-by: Karthik Nayak \n> Signed-off-by: Patrick Steinhardt \n> ---\n> Hi,\n>\n> a small fix for our out-of-date documentation, as discovered by Karthik.\n\nThanks, both. Looks good. Will queue.\n\n"}]}