[PATCH] Add commands that git-gc runs underneath

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

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

Johannes Schindelin wrote:

Hi,

On Thu, 30 Aug 2007, Jari Aalto wrote:

quoted

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


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

Johannes Schindelin [off-list ref] writes:

On Thu, 30 Aug 2007, Jari Aalto wrote:

quoted

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

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

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

Johannes Schindelin wrote:

Hi,

On Thu, 30 Aug 2007, Andreas Ericsson wrote:

quoted

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

On 8/30/07, Johannes Schindelin [off-list ref] 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

On Thu, Aug 30, 2007 at 12:58:00PM +0100, Johannes Schindelin wrote:

On Thu, 30 Aug 2007, Andreas Ericsson wrote:

quoted

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