[PATCH] Add commands that git-gc runs underneath

[PATCH] Add commands that git-gc runs underneath

[Jari Aalto]

git-gc is a higher level utility to "do the right thing". However
there are many other lower level utilities for the house keeping and
it is not clear what git-gc actually does. Adding the actual lower
level command and their parameters explain "what's going on".x

Signed-off-by: Jari Aalto <jari.aalto@cante.net>
---
 Documentation/git-gc.txt |   18 ++++++++++++++++++
 1 files changed, 18 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt
index c7742ca..c2315bf 100644
--- a/Documentation/git-gc.txt
+++ b/Documentation/git-gc.txt
@@ -21,6 +21,24 @@ Users are encouraged to run this task on a regular basis within
 each repository to maintain good disk space utilization and good
 operating performance.
 
+`git-gc` is a front-end to lower level house keeping commands and
+effectively runs these:
+
+--------------------------------
+ # for non-bare repositories only
+ git pack-refs --all --prune
+
+ git reflog expire --all
+
+ # with added --window -f parameters if --aggressive was specified
+ git repack -a -d -l
+
+ # if --prune was specified
+ git prune
+
+ git rerere gc
+--------------------------------
+
 OPTIONS
 -------
 
-- 
1.5.3.rc5



-- 
Welcome to FOSS revolution: we fix and modify until it shines

Re: [PATCH] Add commands that git-gc runs underneath

[Johannes Schindelin]

Hi,

On Thu, 30 Aug 2007, Jari Aalto wrote:

> git-gc is a higher level utility to "do the right thing". However there 
> are many other lower level utilities for the house keeping and it is not 
> clear what git-gc actually does. Adding the actual lower level command 
> and their parameters explain "what's going on".x

Isn't the whole purpose of git-gc to make it _unnecessary_ to know which 
lowlevel commands are run?

NACK.

Ciao,
Dscho

Re: [PATCH] Add commands that git-gc runs underneath

[Andreas Ericsson]

Johannes Schindelin wrote:
> Hi,
> 
> On Thu, 30 Aug 2007, Jari Aalto wrote:
> 
>> git-gc is a higher level utility to "do the right thing". However there 
>> are many other lower level utilities for the house keeping and it is not 
>> clear what git-gc actually does. Adding the actual lower level command 
>> and their parameters explain "what's going on".x
> 
> Isn't the whole purpose of git-gc to make it _unnecessary_ to know which 
> lowlevel commands are run?
> 
> NACK.
> 

I think of it as a handy way of doing all those tasks in the correct order
without having to remember more than a single command.

I kinda like it, and it might be helpful if someone's got a large repo and
one part of gc for some reason didn't complete so they want to start at
whatever step it broke off on.

When gc was a shell-script, it was fairly easy to find out the command-
sequence. Now it's a built-in and that deduction actually takes some
time and brainpower, so...

Acked-by: Andreas Ericsson <ae@op5.se>


-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231

Re: [PATCH] Add commands that git-gc runs underneath

[Johannes Schindelin]

Hi,

On Thu, 30 Aug 2007, Andreas Ericsson wrote:

> I kinda like it [listing the commands git-gc calls], and it might be 
> helpful if someone's got a large repo and one part of gc for some reason 
> didn't complete so they want to start at whatever step it broke off on.

Let me clarify: I do not like the listing in the man page.  This suggests 
to the user to delve into plumbing areas where it is all too easy to shoot 
yourself in the foot.

I have nothing against listing the commands per se.  But the man page is 
too exposed IMHO.  (Or would you like to add the original shell script to 
git-log's man page, too?)

My preferred location would be somewhere near Documentation/technical/, so 
that people reading the commands are more likely to understand the 
consequences.

But maybe I'm wrong.

Ciao,
Dscho

Re: [PATCH] Add commands that git-gc runs underneath

[Andreas Ericsson]

Johannes Schindelin wrote:
> Hi,
> 
> On Thu, 30 Aug 2007, Andreas Ericsson wrote:
> 
>> I kinda like it [listing the commands git-gc calls], and it might be 
>> helpful if someone's got a large repo and one part of gc for some reason 
>> didn't complete so they want to start at whatever step it broke off on.
> 
> Let me clarify: I do not like the listing in the man page.  This suggests 
> to the user to delve into plumbing areas where it is all too easy to shoot 
> yourself in the foot.
> 

I misunderstood.

> I have nothing against listing the commands per se.  But the man page is 
> too exposed IMHO.  (Or would you like to add the original shell script to 
> git-log's man page, too?)
> 
> My preferred location would be somewhere near Documentation/technical/, so 
> that people reading the commands are more likely to understand the 
> consequences.
> 
> But maybe I'm wrong.
> 

Having read the reasoning, I confess myself convinced. Thanks for clarifying.

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231

Re: [PATCH] Add commands that git-gc runs underneath

[Tom Clarke]

On 8/30/07, Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:
> I have nothing against listing the commands per se.  But the man page is
> too exposed IMHO.  (Or would you like to add the original shell script to
> git-log's man page, too?)

Perhaps the man pages for the lower level commands should reference
git-gc as the command that - unless you have special circumstances -
you probably want. As a new git user it was only reading this thread
that made me realise that git-gc is the command I want most of the
time - a number of the tutorials I had read referenced the low level
commands, and I didn't realise they had been superseded for normal
use.

-Tom

Re: [PATCH] Add commands that git-gc runs underneath

[Theodore Tso]

On Thu, Aug 30, 2007 at 12:58:00PM +0100, Johannes Schindelin wrote:
> On Thu, 30 Aug 2007, Andreas Ericsson wrote:
> 
> > I kinda like it [listing the commands git-gc calls], and it might be 
> > helpful if someone's got a large repo and one part of gc for some reason 
> > didn't complete so they want to start at whatever step it broke off on.
> 
> Let me clarify: I do not like the listing in the man page.  This suggests 
> to the user to delve into plumbing areas where it is all too easy to shoot 
> yourself in the foot.

I'm somewhat sympathetic to that argument, but at the same time, we're
still telling users to read the man page for plumbing areas in order
to understand to get the listing valid command-line options to git
commands.  In addition, the main git(1) man page is dedicating talking
about all sorts of low-level on-disk storage details that arguably
should be in the Documentation/technical that you suggested.  I also
don't quite see how commands like git-repack, git-prune,
git-pack-refs, et. al., are likely to get the user into trouble, any
more than git-gc --prune might.  Those commands are all relatively
safe, and indeed, they are all listed in the git-gc's "SEE ALSO"
section of its man page, so users are already being encouraged to
delve into plumbing areas.

That being said, given the SEE ALSO section, I don't think it adds a
huge amount of value to list the exact set of commands and options by
git-gc.  Also, if we add more functionality to git-gc in the future,
it would be pain to have to keep upgrading to man page uptodate.

   	    	    	    	 	      - Ted

Re: [PATCH] Add commands that git-gc runs underneath

[Junio C Hamano]

Andreas Ericsson <ae@op5.se> writes:

> When gc was a shell-script, it was fairly easy to find out the command-
> sequence...

Maybe referring more advanced/curious users to contrib/examples/
directory is a good idea, but not necessarily from manpages of
the commands that have been rewritten in C.

I think contrib/examples/ needs a README file that effectively
say "these are the last versions of shell script implementation
of the commands before they were rewritten in C.  New features
may have been added to the built-in ones but these example
scripts are not kept up to date.  They are here to serve as
examples to show you how you would pipeline the plumbing level
commands."

Re: [PATCH] Add commands that git-gc runs underneath

[Andreas Ericsson]

Junio C Hamano wrote:
> Andreas Ericsson <ae@op5.se> writes:
> 
>> When gc was a shell-script, it was fairly easy to find out the command-
>> sequence...
> 
> Maybe referring more advanced/curious users to contrib/examples/
> directory is a good idea, but not necessarily from manpages of
> the commands that have been rewritten in C.
> 
> I think contrib/examples/ needs a README file that effectively
> say "these are the last versions of shell script implementation
> of the commands before they were rewritten in C.  New features
> may have been added to the built-in ones but these example
> scripts are not kept up to date.  They are here to serve as
> examples to show you how you would pipeline the plumbing level
> commands."
> 

Sensible, and also avoids the possible bitrot problem with the
man-page should there be additional actions added to standard
git-gc operations.

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231

Re: [PATCH] Add commands that git-gc runs underneath

[David Kastrup]

Andreas Ericsson <ae@op5.se> writes:

> Junio C Hamano wrote:
>> Andreas Ericsson <ae@op5.se> writes:
>>
>>> When gc was a shell-script, it was fairly easy to find out the command-
>>> sequence...
>>
>> Maybe referring more advanced/curious users to contrib/examples/
>> directory is a good idea, but not necessarily from manpages of
>> the commands that have been rewritten in C.
>>
>> I think contrib/examples/ needs a README file that effectively
>> say "these are the last versions of shell script implementation
>> of the commands before they were rewritten in C.  New features
>> may have been added to the built-in ones but these example
>> scripts are not kept up to date.  They are here to serve as
>> examples to show you how you would pipeline the plumbing level
>> commands."
>>
>
> Sensible, and also avoids the possible bitrot problem with the
> man-page should there be additional actions added to standard
> git-gc operations.

Let's just make all manual pages empty, and then we have solved all
manual page bitrot problems in one fell swoop.

Really: I don't see how this helps at all.  If I am interested in
seeing what operations git-gc performs, I am not interested in some
historical script's behavior.

Hiding that information into contrib/examples and telling people that
it may be wrong, anyway, is not really helpful as a way of documenting
git-gc's behavior.

Of _course_, _any_ useful documentation will have a "possible bitrot
problem with the man-page" whenever code is changed.  The solution is
not to make the manual pages as useless as possible so that nothing
can be subject to bitrot.  The solution is to update the information.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: [PATCH] Add commands that git-gc runs underneath

[Junio C Hamano]

Andreas Ericsson <ae@op5.se> writes:

> Junio C Hamano wrote:
>> Andreas Ericsson <ae@op5.se> writes:
>>
>>> When gc was a shell-script, it was fairly easy to find out the command-
>>> sequence...
>>
>> Maybe referring more advanced/curious users to contrib/examples/
>> directory is a good idea, but not necessarily from manpages of
>> the commands that have been rewritten in C.
>>
>> I think contrib/examples/ needs a README file that effectively
>> say "these are the last versions of shell script implementation
>> of the commands before they were rewritten in C.  New features
>> may have been added to the built-in ones but these example
>> scripts are not kept up to date.  They are here to serve as
>> examples to show you how you would pipeline the plumbing level
>> commands."
>
> Sensible, and also avoids the possible bitrot problem with the
> man-page should there be additional actions added to standard
> git-gc operations.

Oh, I did not mean to address bit-rot issue.  I was addressing
"ah, in good old days we had tons of example scripts" issue.

If we want the manual to be explicit about what exactly happens
when you run "git-gc" (and I think we do), that needs to be done
independently.  But my feeling is that we do not want to
describe what happens solely in terms of what other individual
commands do.  Referring to other manual pages for more details
is fine, but that should not be the sole description.

In other words, instead of saying:

 - runs "git pack-refs", "git reflog expire --all", "git repack
   -a -d -l", ...

I think we would want to say it this way:

 * Under such-and-such condition, loose refs are packed for
   quicker access in $GIT_DIR/packed-refs file (runs "git
   pack-refs --prune");

 * Old reflog entries that record how tips of each branches were
   moved are expired (runs "git-reflog expire --all");

 * Packfiles are repacked along with loose object files, while
   exclusing objects that are available from the alternates
   (runs "git repack -a -d -l");

 * Unreferenced loose objects are removed if --prune is given
   (runs "git prune");
  
 * Old rerere records that record resolutions to previously
   conflicted merges are expired (runs "git rerere gc").

Re: [PATCH] Add commands that git-gc runs underneath

[David Kastrup]

Junio C Hamano <gitster@pobox.com> writes:

> But my feeling is that we do not want to describe what happens
> solely in terms of what other individual commands do.  Referring to
> other manual pages for more details is fine, but that should not be
> the sole description.
>
> In other words, instead of saying:

[...]

> I think we would want to say it this way:

[...]

I would say your feeling is dead-on.  Full agreement with that
proposal.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: [PATCH] Add commands that git-gc runs underneath

[David Kastrup]

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

> On Thu, 30 Aug 2007, Jari Aalto wrote:
>
>> git-gc is a higher level utility to "do the right thing". However there 
>> are many other lower level utilities for the house keeping and it is not 
>> clear what git-gc actually does. Adding the actual lower level command 
>> and their parameters explain "what's going on".x
>
> Isn't the whole purpose of git-gc to make it _unnecessary_ to know which 
> lowlevel commands are run?

Unnecessary and undocumented are two different things.  I think it
very reasonable to document what exactly git-gc does and what it is
equivalent to.  So in principle,

Acked-by: David Kastrup <dak@gnu.org>

However, since this is detail information, it may be appropriate to
put this into a footnote and/or compress the copious number of empty
lines in it: that would better maintain the relation with the rest of
the entry.

-- 
David Kastrup