[RFC] gc: correct gc.autoPackLimit documentation

I'm not sure if this is the best approach, or if changing too_many_packs can be done without causing problems for hosts of big repos.

-------8<-----
Subject: [PATCH] gc: correct gc.autoPackLimit documentation

I want to ensure there is only one pack in my repo to take advantage of pack bitmaps. Based on my reading of the documentation, I configured gc.autoPackLimit=1 which led to "gc --auto" constantly trying to repack on every invocation.

Update the documentation to reflect what is probably a long-standing off-by-one bug in builtin/gc.c::too_many_packs:

	-	return gc_auto_pack_limit <= cnt;
	+	return gc_auto_pack_limit < cnt;

However, changing gc itself at this time may cause problems for people who are already using gc.autoPackLimit=2 and expect bitmaps to work for them.

Signed-off-by: Eric Wong <e@80x24.org>
---
 Documentation/config.txt | 2 +-
 Documentation/git-gc.txt | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

On Sat, Jun 25, 2016 at 01:14:50AM +0000, Eric Wong wrote:

I'm not sure if you might be misinterpreting earlier advice on bitmaps here. At the time of packing, bitmaps need for all of the objects to go to a single pack (they cannot handle a case where one object in the pack can reach another object that is not in the pack). But that is easily done with "git repack -adb".

After that packing, you can add new packs that do not have bitmaps, and the bitmaps will gracefully degrade. E.g., imagine master was at tip X when you repacked with bitmaps, and now somebody has pushed to make it tip Y. Somebody then clones, asking for Y. The bitmap code will start at Y and walk backwards. When it hits X, it stops walking as it can fill in the rest of the reachability from there.

So you do have to walk X..Y the old-fashioned way, but that's generally not a big problem for a few pushes.

IOW, I think trying to repack on every single push is probably overkill. Yes, it will buy you a little savings on fetch requests, but whether it is worthwhile to pack depends on:

 - how big the push was (e.g., 2 commits versus thousands; the bigger
   it is, the more you save per fetch

 - how big the repo is (the bigger it is, the more it costs to do the
   repack; packing is linear-ish effort in the number of objects in the
   repo)

 - how often you get fetches versus pushes (your cost is amortized
   across all the fetches)

There are numbers where it can be worth it to pack really aggressively, but I doubt it's common. At GitHub we use a combination of number of packs (and we try to keep it under 50) and size of objects not in the "main" pack (I did a bunch of fancy logging and analysis of object counts, bytes in packs, etc, at one point, and we basically realized that for the common cases, all of the interesting metrics are roughly proportional to the number of bytes that could be moved into the main pack).

That's neither here nor there for the off-by-one in gc or its documentation, of course, but just FYI.

-Peff

Jeff King <peff@peff.net> wrote:

Ah, thanks, makes sense. I was misinterpreting earlier advice on bitmaps.

I'm now inclined to fix the problem in gc and leave the documentation as-is (unless it cause other problems...)

Eric Wong <e@80x24.org> writes:

I think that is the best in the longer term.

This matches the documentation and allows gc.autoPackLimit=1 to maintain a single pack without attempting a repack on every "git gc --auto" invocation.

Signed-off-by: Eric Wong <e@80x24.org>
---
 builtin/gc.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

On Sat, Jun 25, 2016 at 06:46:47AM +0000, Eric Wong wrote:

Looks good, and I cannot think of any real downside. "0" is special for "do not use this limit", so you now have no way of asking to gc every time. But why would you want to? Asking for 1 pack is effectively "gc if something happened, otherwise do nothing".

-Peff