patchdocs/git-pack-refs: document heuristic used for packing loose refs

> 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

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

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