threads / patch / 13501

patchDocumentation/git-gc.txt: change --aggressive description

Subject: [PATCH] Documentation/git-gc.txt: change --aggressive description

## tl;dr

10 messages between May 13, 2008 and May 24, 2008. Diffs are folded; open one to read it.

replies: 9people: 5as markdown or json

Pieter de Bie· May 13, 2008, 09:53 UTC · lore

The documentation for the --aggressive flag was misleading, hinting that running git gc with --aggressive is a good thing. However, --aggressive only really makes sense if you have a bad pack file, such as from git-fast-import. ---

I keep seeing people regularly packing their repo with git gc --aggressive. However, in my experience, this seldom results in a smaller repository. This can be because the repository was repacked tightly previously (for example, with a high --window value) or because incremental "git gc" just makes better packs anyway. Throwing away that information is often not a good idea.

The documentation for the --aggressive flag was misleading, in that it hints that you'll get a smaller pack, which is often not the case.
 Documentation/git-gc.txt |    8 +++++---
 1 files changed, 5 insertions(+), 3 deletions(-)
Show changes to Documentation/git-gc.txt +5 −3
diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt
index b6b5ce1..ebf972c 100644
--- a/Documentation/git-gc.txt
+++ b/Documentation/git-gc.txt
@@ -36,9 +36,11 @@ OPTIONS
 	Usually 'git-gc' runs very quickly while providing good disk
 	space utilization and performance.  This option will cause
 	git-gc to more aggressively optimize the repository at the expense
-	of taking much more time.  The effects of this optimization are
-	persistent, so this option only needs to be used occasionally; every
-	few hundred changesets or so.
+	of taking much more time. Note that this will throw away all previous
+	optimizations. As a result, running git gc with --aggressive will not
+	necessarily create a smaller pack file, especially when the repository was
+	packed tightly already. Using --aggressive only makes sense if you have a
+	badly packed repository, such as created by git-fast-import.
 
 --auto::
 	With this option, `git gc` checks whether any housekeeping is

-- 
1.5.5.1.174.g32fa0.dirty
Teemu Likonen· May 13, 2008, 10:57 UTC · re: Pieter de Bie · lore

Re: [PATCH] Documentation/git-gc.txt: change --aggressive description

Pieter de Bie wrote (2008-05-13 11:53 +0200):
Show 9 quoted lines
> I keep seeing people regularly packing their repo with git gc
> --aggressive. However, in my experience, this seldom results in
> a smaller repository. This can be because the repository was repacked
> tightly previously (for example, with a high --window value) or
> because incremental "git gc" just makes better packs anyway. Throwing
> away that information is often not a good idea.
> 
> The documentation for the --aggressive flag was misleading, in that it
> hints that you'll get a smaller pack, which is often not the case.

This patch might be a good thing. But from ordinary user's point of view this raises questions: if gc --aggressive really is not that aggressive then the option itself is misleading. Why not change gc --aggressive to be really effective? Using high --window/--depth value etc.

Teemu Likonen· May 13, 2008, 11:08 UTC · re: Teemu Likonen · lore

Re: [PATCH] Documentation/git-gc.txt: change --aggressive description

Teemu Likonen wrote (2008-05-13 13:57 +0300):
Show 18 quoted lines
> Pieter de Bie wrote (2008-05-13 11:53 +0200):
> 
> > I keep seeing people regularly packing their repo with git gc
> > --aggressive. However, in my experience, this seldom results in
> > a smaller repository. This can be because the repository was
> > repacked tightly previously (for example, with a high --window
> > value) or because incremental "git gc" just makes better packs
> > anyway. Throwing away that information is often not a good idea.
> >
> > The documentation for the --aggressive flag was misleading, in that
> > it hints that you'll get a smaller pack, which is often not the
> > case.
> 
> This patch might be a good thing. But from ordinary user's point of
> view this raises questions: if gc --aggressive really is not that
> aggressive then the option itself is misleading. Why not change gc
> --aggressive to be really effective? Using high --window/--depth value
> etc.
I mean, what I'm seeing many places is suggestions to run
  git repack -a -d -f --window=100 --depth=100

to get the repo small. _If_ there's such a common need for this then wouldn't it be good thing if there was easy and self-descriptive command for it, such as gc --aggressive?

Johannes Schindelin· May 13, 2008, 11:53 UTC · re: Teemu Likonen · lore

Re: [PATCH] Documentation/git-gc.txt: change --aggressive description

Hi,
On Tue, 13 May 2008, Teemu Likonen wrote:
Show 10 quoted lines
> Teemu Likonen wrote (2008-05-13 13:57 +0300):
> 
> > But from ordinary user's point of view this raises questions: if gc 
> > --aggressive really is not that aggressive then the option itself is 
> > misleading. Why not change gc --aggressive to be really effective? 
> > Using high --window/--depth value etc.
> 
> I mean, what I'm seeing many places is suggestions to run
> 
>   git repack -a -d -f --window=100 --depth=100

I posted a patch to use 250, not just 100, with --aggressive. See the mailing list archives for the discussion.

Ciao, Dscho

Teemu Likonen· May 13, 2008, 15:03 UTC · re: Johannes Schindelin · lore

Re: [PATCH] Documentation/git-gc.txt: change --aggressive description

Johannes Schindelin wrote (2008-05-13 14:53 +0300):
Show 15 quoted lines
> On Tue, 13 May 2008, Teemu Likonen wrote:
> 
> > Teemu Likonen wrote (2008-05-13 13:57 +0300):
> >
> > > But from ordinary user's point of view this raises questions: if
> > > gc --aggressive really is not that aggressive then the option
> > > itself is misleading. Why not change gc --aggressive to be really
> > > effective? Using high --window/--depth value etc.
> >
> > I mean, what I'm seeing many places is suggestions to run
> >
> >   git repack -a -d -f --window=100 --depth=100
> 
> I posted a patch to use 250, not just 100, with --aggressive.  See the
> mailing list archives for the discussion.

Thanks. For easy access I'll paste a link to the discussion. I believe you are referring to this message and thread:

http://thread.gmane.org/gmane.comp.gcc.devel/94565/focus=67275
Pieter de Bie· May 13, 2008, 11:13 UTC · re: Teemu Likonen · lore

Re: [PATCH] Documentation/git-gc.txt: change --aggressive description

On 13 mei 2008, at 12:57, Teemu Likonen wrote:
Show 7 quoted lines
> This patch might be a good thing. But from ordinary user's point of  
> view
> this raises questions: if gc --aggressive really is not that  
> aggressive
> then the option itself is misleading. Why not change gc --aggressive  
> to
> be really effective? Using high --window/--depth value etc.

The problem is that you don't know what is aggressive for this repository; that is relative to how it was previously packed.

I'd much rather change --aggressive to something like --rebuild, which describes much better what it does. However, I don't think it's easy to just rename a flag, as scripts may depend on it.

- Pieter
Johannes Schindelin· May 13, 2008, 11:52 UTC · re: Pieter de Bie · lore

Re: [PATCH] Documentation/git-gc.txt: change --aggressive description

Hi,
On Tue, 13 May 2008, Pieter de Bie wrote:
> The documentation for the --aggressive flag was misleading, hinting that 
> running git gc with --aggressive is a good thing. However, --aggressive 
> only really makes sense if you have a bad pack file, such as from 
> git-fast-import.

I disagree. It makes sense to "git gc --aggressive" also after cloning from somebody who did not do so.

Ciao, Dscho

Pieter de Bie· May 14, 2008, 06:48 UTC · re: Johannes Schindelin · lore

Re: [PATCH] Documentation/git-gc.txt: change --aggressive description

On 13 mei 2008, at 13:52, Johannes Schindelin wrote:
Show 10 quoted lines
>> The documentation for the --aggressive flag was misleading, hinting  
>> that
>> running git gc with --aggressive is a good thing. However, -- 
>> aggressive
>> only really makes sense if you have a bad pack file, such as from
>> git-fast-import.
>
> I disagree.  It makes sense to "git gc --aggressive" also after  
> cloning
> from somebody who did not do so.

The problem with this is that your pack might increase in size, which you can't know in advance. Running "git gc --aggressive" on the git repo for example increases its size from 20MB to 30MB.

The current wording at least makes it sound as if --aggressive will always result in a smaller pack, which is simply not true. Increasing the window and depth might help, but 250 or even 100 can be too much on any decently size repository.

How about dropping the last sentence ("Using --aggressive only makes sense if you have a badly packed repository, such as created by git- fast-import.") then?

- Pieter
Matthieu Moy· May 14, 2008, 07:48 UTC · re: Pieter de Bie · lore

Re: [PATCH] Documentation/git-gc.txt: change --aggressive description

Pieter de Bie <pdebie@ai.rug.nl> writes:
> How about dropping the last sentence ("Using --aggressive only makes
> sense if you have a badly packed repository, such as created by git- 
> fast-import.") then?

I think informing the user that git-fast-import may require --aggressive is good. Actually, I like the sentence as it is (the "such as" makes it clear that it's not the /only/ case where it can be required).

My 2cts,
-- 
Matthieu
Pieter de Bie· May 24, 2008, 19:03 UTC · re: Pieter de Bie · lore

Re: [PATCH] Documentation/git-gc.txt: change --aggressive description

On May 14, 2008, at 8:48 AM, Pieter de Bie wrote:
Show 20 quoted lines
> On 13 mei 2008, at 13:52, Johannes Schindelin wrote:
>>> The documentation for the --aggressive flag was misleading,  
>>> hinting that
>>> running git gc with --aggressive is a good thing. However, -- 
>>> aggressive
>>> only really makes sense if you have a bad pack file, such as from
>>> git-fast-import.
>>
>> I disagree.  It makes sense to "git gc --aggressive" also after  
>> cloning
>> from somebody who did not do so.
>
> The problem with this is that your pack might increase in size,  
> which you can't know in advance. Running "git gc --aggressive" on  
> the git repo for example increases its size from 20MB to 30MB.
>
> The current wording at least makes it sound as if --aggressive will  
> always result in a smaller pack, which is simply not true.  
> Increasing the window and depth might help, but 250 or even 100 can  
> be too much on any decently size repository.

Any other comments on this patch? I still think it is an improvement over what is currently in the the man-page.

- Pieter

← back to recent threads