threads / patch / 9702

patchAdd commands that git-gc runs underneath

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

## tl;dr

13 messages between Aug 30, 2007 and Aug 31, 2007. Diffs are folded; open one to read it.

replies: 12people: 7as markdown or json

Jari Aalto· Aug 30, 2007, 09:35 UTC · lore

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(-)
Show changes to Documentation/git-gc.txt +18 −0
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
Johannes Schindelin· Aug 30, 2007, 10:08 UTC · re: Jari Aalto · lore

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

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

Andreas Ericsson· Aug 30, 2007, 10:13 UTC · re: Johannes Schindelin · lore

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

Johannes Schindelin wrote:
Show 14 quoted lines
> 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
Johannes Schindelin· Aug 30, 2007, 11:58 UTC · re: Andreas Ericsson · lore

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

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

Andreas Ericsson· Aug 30, 2007, 12:13 UTC · re: Johannes Schindelin · lore

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

Johannes Schindelin wrote:
Show 12 quoted lines
> 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.
Show 10 quoted lines
> 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
Tom Clarke· Aug 30, 2007, 12:15 UTC · re: Johannes Schindelin · lore

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

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
Theodore Tso· Aug 30, 2007, 12:34 UTC · re: Johannes Schindelin · lore

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

On Thu, Aug 30, 2007 at 12:58:00PM +0100, Johannes Schindelin wrote:
Show 9 quoted lines
> 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
Junio C Hamano· Aug 30, 2007, 21:33 UTC · re: Andreas Ericsson · lore

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

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."

Andreas Ericsson· Aug 31, 2007, 09:33 UTC · re: Junio C Hamano · lore

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

Junio C Hamano wrote:
Show 17 quoted lines
> 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
David Kastrup· Aug 31, 2007, 19:25 UTC · re: Andreas Ericsson · lore

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

Andreas Ericsson <ae@op5.se> writes:
Show 22 quoted lines
> 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
Junio C Hamano· Aug 31, 2007, 21:12 UTC · re: Andreas Ericsson · lore

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

Andreas Ericsson <ae@op5.se> writes:
Show 21 quoted lines
> 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").
David Kastrup· Aug 31, 2007, 21:27 UTC · re: Junio C Hamano · lore

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

Junio C Hamano <gitster@pobox.com> writes:
Show 6 quoted lines
> 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
David Kastrup· Aug 30, 2007, 10:25 UTC · re: Johannes Schindelin · lore

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

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
Show 9 quoted lines
> 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

← back to recent threads