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

Andreas Ericsson [off-list ref] writes:

Junio C Hamano wrote:

quoted

Andreas Ericsson [off-list ref] writes:

quoted

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