[PATCH] docs/git-pack-refs: document heuristic used for packing loose refs

[PATCH] docs/git-pack-refs: document heuristic used for packing loose refs

[Patrick Steinhardt]

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

Re: [PATCH] docs/git-pack-refs: document heuristic used for packing loose refs

[Karthik Nayak]

[-- Attachment #1: Type: text/plain, Size: 2511 bytes --]

Patrick Steinhardt <ps@pks.im> writes:

> 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.
>  +

Nice. The explanation has sufficient information without going too much
into detail. Perhaps a small nit would be s/ratio/logarithmic ratio/,
but I'm happy with this as is.

Thanks

>  	- "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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 690 bytes --]

Re: [PATCH] docs/git-pack-refs: document heuristic used for packing loose refs

[Patrick Steinhardt]

On Tue, Jul 08, 2025 at 04:43:42AM -0700, Karthik Nayak wrote:
> Patrick Steinhardt <ps@pks.im> writes:
> > 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.
> >  +
> 
> Nice. The explanation has sufficient information without going too much
> into detail. Perhaps a small nit would be s/ratio/logarithmic ratio/,
> but I'm happy with this as is.

I was very much on the fence on whether to add "logarithmic" in there or
not. I ultimately felt like it hinted too much at how exactly it works
without really giving enough information to fully understand it, so it
felt a bit useless to me to add "logarithmic".

I don't have a strong opinion though, and it doesn't seem like you feel
strongly about it, either. So for now I'll keep this as-is, but I'm
happy to change it if others also have a slight preference for adding
the word in.

Thanks!

Patrick

Re: [PATCH] docs/git-pack-refs: document heuristic used for packing loose refs

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

> 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, both.  Looks good.  Will queue.