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

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

[Pieter de Bie]

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(-)

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

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

[Teemu Likonen]

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.

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

[Teemu Likonen]

Teemu Likonen wrote (2008-05-13 13:57 +0300):

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

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

[Pieter de Bie]

On 13 mei 2008, at 12:57, Teemu Likonen wrote:
> 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

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

[Johannes Schindelin]

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

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

[Johannes Schindelin]

Hi,

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.

Ciao,
Dscho

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

[Teemu Likonen]

Johannes Schindelin wrote (2008-05-13 14:53 +0300):

> 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

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

[Pieter de Bie]

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.

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

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

[Matthieu Moy]

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

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

[Pieter de Bie]

On May 14, 2008, at 8:48 AM, Pieter de Bie wrote:
> 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