[PATCH] docs/git-pack-refs: document heuristic used for packing loose refs
- From
Patrick Steinhardt <ps@pks.im>
- Date
- Jul 8, 2025, 11:23 UTC
- Message-ID
- <20250708-b4-pks-pack-refs-document-files-heuristic-v1-1-e28d65a94573@pks.im>
The `git pack-refs --auto` flag asks the ref backend to decide for itself whether or not references need to be repacked. This is done to ensure that we don't repack in cases where the backend is already in a good-enough state, which is typically the case for the "reftable" backend that performs auto-compaction on writes.
As such, we initially only had heuristics in place for the "reftable" backend. The "files" backend didn't have any heuristics, so we'd repack loose references every time `git pack-refs --auto` was executed. This caused excessive repacking with that backend though, which is why we eventually implemented a heuristic via c3459ae9ef2 (refs/files: use heuristic to decide whether to repack with `--auto`, 2024-09-04).
The documentation for the `--auto` flag hasn't been updated accordingly and still claims that we don't have any metrics for the "files" backend. Update it to reflect the new reality.
Reported-by: Karthik Nayak <karthik.188@gmail.com> Signed-off-by: Patrick Steinhardt <ps@pks.im> --- Hi,
a small fix for our out-of-date documentation, as discovered by Karthik.
Thanks!
Patrick --- Documentation/git-pack-refs.adoc | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-)
diff --git a/Documentation/git-pack-refs.adoc b/Documentation/git-pack-refs.adoc index 652c5497715..42b90051e69 100644 --- a/Documentation/git-pack-refs.adoc +++ b/Documentation/git-pack-refs.adoc @@ -66,7 +66,10 @@ Pack refs as needed depending on the current state of the ref database. The behavior depends on the ref format used by the repository and may change in the future. + - - "files": No special handling for `--auto` has been implemented. + - "files": Loose references are packed into the `packed-refs` file + based on the ratio of loose references to the size of the + `packed-refs` file. The bigger the `packed-refs` file, the more loose + references need to exist before we repack. + - "reftable": Tables are compacted such that they form a geometric sequence. For two tables N and N+1, where N+1 is newer, this --- base-commit: 41905d60226a0346b22f0d0d99428c746a5a3b14 change-id: 20250708-b4-pks-pack-refs-document-files-heuristic-58a9df3df946