{"thread":{"id":"9702","subject":"[PATCH] Add commands that git-gc runs underneath","startedAt":"2007-08-30T09:35:11Z","lastAt":"2007-08-31T21:27:46Z","messageCount":13,"participants":["Jari Aalto","Johannes Schindelin","Andreas Ericsson","David Kastrup","Tom Clarke","Theodore Tso","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"51887","messageId":"lkbtwek0.fsf@cante.net","threadId":"9702","inReplyTo":null,"subject":"[PATCH] Add commands that git-gc runs underneath","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2007-08-30T09:35:11Z","receivedAt":"2007-08-30T09:35:11Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"git-gc is a higher level utility to \"do the right thing\". However\nthere are many other lower level utilities for the house keeping and\nit is not clear what git-gc actually does. Adding the actual lower\nlevel command and their parameters explain \"what's going on\".x\n\nSigned-off-by: Jari Aalto \n---\n Documentation/git-gc.txt | 18 ++++++++++++++++++\n 1 files changed, 18 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt\nindex c7742ca..c2315bf 100644\n--- a/Documentation/git-gc.txt\n+++ b/Documentation/git-gc.txt\n@@ -21,6 +21,24 @@ Users are encouraged to run this task on a regular basis within\n each repository to maintain good disk space utilization and good\n operating performance.\n \n+`git-gc` is a front-end to lower level house keeping commands and\n+effectively runs these:\n+\n+--------------------------------\n+ # for non-bare repositories only\n+ git pack-refs --all --prune\n+\n+ git reflog expire --all\n+\n+ # with added --window -f parameters if --aggressive was specified\n+ git repack -a -d -l\n+\n+ # if --prune was specified\n+ git prune\n+\n+ git rerere gc\n+--------------------------------\n+\n OPTIONS\n -------\n \n-- \n1.5.3.rc5\n\n\n\n-- \nWelcome to FOSS revolution: we fix and modify until it shines\n"},{"id":"51888","messageId":"Pine.LNX.4.64.0708301107320.28586@racer.site","threadId":"9702","inReplyTo":"lkbtwek0.fsf@cante.net","subject":"Re: [PATCH] Add commands that git-gc runs underneath","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2007-08-30T10:08:09Z","receivedAt":"2007-08-30T10:08:09Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Thu, 30 Aug 2007, Jari Aalto wrote:\n\n> git-gc is a higher level utility to \"do the right thing\". However there \n> are many other lower level utilities for the house keeping and it is not \n> clear what git-gc actually does. Adding the actual lower level command \n> and their parameters explain \"what's going on\".x\n\nIsn't the whole purpose of git-gc to make it _unnecessary_ to know which \nlowlevel commands are run?\n\nNACK.\n\nCiao,\nDscho\n"},{"id":"51889","messageId":"46D6984D.9040802@op5.se","threadId":"9702","inReplyTo":"Pine.LNX.4.64.0708301107320.28586@racer.site","subject":"Re: [PATCH] Add commands that git-gc runs underneath","fromName":"Andreas Ericsson","fromEmail":"ae@op5.se","sentAt":"2007-08-30T10:13:33Z","receivedAt":"2007-08-30T10:13:33Z","isPatch":true,"sender":{"key":"ae@op5.se","avatar":"https://gravatar.com/avatar/426e89595c75a8f5252dd0c989e5fabe5bcac616e68557427ad9aef6b0ca342a?d=mp&s=160"},"body":"Johannes Schindelin wrote:\n> Hi,\n> \n> On Thu, 30 Aug 2007, Jari Aalto wrote:\n> \n>> git-gc is a higher level utility to \"do the right thing\". However there \n>> are many other lower level utilities for the house keeping and it is not \n>> clear what git-gc actually does. Adding the actual lower level command \n>> and their parameters explain \"what's going on\".x\n> \n> Isn't the whole purpose of git-gc to make it _unnecessary_ to know which \n> lowlevel commands are run?\n> \n> NACK.\n> \n\nI think of it as a handy way of doing all those tasks in the correct order\nwithout having to remember more than a single command.\n\nI kinda like it, and it might be helpful if someone's got a large repo and\none part of gc for some reason didn't complete so they want to start at\nwhatever step it broke off on.\n\nWhen gc was a shell-script, it was fairly easy to find out the command-\nsequence. Now it's a built-in and that deduction actually takes some\ntime and brainpower, so...\n\nAcked-by: Andreas Ericsson \n\n\n-- \nAndreas Ericsson andreas.ericsson@op5.se\nOP5 AB www.op5.se\nTel: +46 8-230225 Fax: +46 8-230231\n"},{"id":"51891","messageId":"864pihjp4o.fsf@lola.quinscape.zz","threadId":"9702","inReplyTo":"Pine.LNX.4.64.0708301107320.28586@racer.site","subject":"Re: [PATCH] Add commands that git-gc runs underneath","fromName":"David Kastrup","fromEmail":"dak@gnu.org","sentAt":"2007-08-30T10:25:11Z","receivedAt":"2007-08-30T10:25:11Z","isPatch":true,"sender":{"key":"dak@gnu.org","avatar":"https://avatars.githubusercontent.com/u/52141349?v=4"},"body":"Johannes Schindelin writes:\n\n> On Thu, 30 Aug 2007, Jari Aalto wrote:\n>\n>> git-gc is a higher level utility to \"do the right thing\". However there \n>> are many other lower level utilities for the house keeping and it is not \n>> clear what git-gc actually does. Adding the actual lower level command \n>> and their parameters explain \"what's going on\".x\n>\n> Isn't the whole purpose of git-gc to make it _unnecessary_ to know which \n> lowlevel commands are run?\n\nUnnecessary and undocumented are two different things. I think it\nvery reasonable to document what exactly git-gc does and what it is\nequivalent to. So in principle,\n\nAcked-by: David Kastrup \n\nHowever, since this is detail information, it may be appropriate to\nput this into a footnote and/or compress the copious number of empty\nlines in it: that would better maintain the relation with the rest of\nthe entry.\n\n-- \nDavid Kastrup\n"},{"id":"51899","messageId":"Pine.LNX.4.64.0708301254420.28586@racer.site","threadId":"9702","inReplyTo":"46D6984D.9040802@op5.se","subject":"Re: [PATCH] Add commands that git-gc runs underneath","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2007-08-30T11:58:00Z","receivedAt":"2007-08-30T11:58:00Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Thu, 30 Aug 2007, Andreas Ericsson wrote:\n\n> I kinda like it [listing the commands git-gc calls], and it might be \n> helpful if someone's got a large repo and one part of gc for some reason \n> didn't complete so they want to start at whatever step it broke off on.\n\nLet me clarify: I do not like the listing in the man page. This suggests \nto the user to delve into plumbing areas where it is all too easy to shoot \nyourself in the foot.\n\nI have nothing against listing the commands per se. But the man page is \ntoo exposed IMHO. (Or would you like to add the original shell script to \ngit-log's man page, too?)\n\nMy preferred location would be somewhere near Documentation/technical/, so \nthat people reading the commands are more likely to understand the \nconsequences.\n\nBut maybe I'm wrong.\n\nCiao,\nDscho\n"},{"id":"51903","messageId":"46D6B45E.4020800@op5.se","threadId":"9702","inReplyTo":"Pine.LNX.4.64.0708301254420.28586@racer.site","subject":"Re: [PATCH] Add commands that git-gc runs underneath","fromName":"Andreas Ericsson","fromEmail":"ae@op5.se","sentAt":"2007-08-30T12:13:18Z","receivedAt":"2007-08-30T12:13:18Z","isPatch":true,"sender":{"key":"ae@op5.se","avatar":"https://gravatar.com/avatar/426e89595c75a8f5252dd0c989e5fabe5bcac616e68557427ad9aef6b0ca342a?d=mp&s=160"},"body":"Johannes Schindelin wrote:\n> Hi,\n> \n> On Thu, 30 Aug 2007, Andreas Ericsson wrote:\n> \n>> I kinda like it [listing the commands git-gc calls], and it might be \n>> helpful if someone's got a large repo and one part of gc for some reason \n>> didn't complete so they want to start at whatever step it broke off on.\n> \n> Let me clarify: I do not like the listing in the man page. This suggests \n> to the user to delve into plumbing areas where it is all too easy to shoot \n> yourself in the foot.\n> \n\nI misunderstood.\n\n> I have nothing against listing the commands per se. But the man page is \n> too exposed IMHO. (Or would you like to add the original shell script to \n> git-log's man page, too?)\n> \n> My preferred location would be somewhere near Documentation/technical/, so \n> that people reading the commands are more likely to understand the \n> consequences.\n> \n> But maybe I'm wrong.\n> \n\nHaving read the reasoning, I confess myself convinced. Thanks for clarifying.\n\n-- \nAndreas Ericsson andreas.ericsson@op5.se\nOP5 AB www.op5.se\nTel: +46 8-230225 Fax: +46 8-230231\n"},{"id":"51904","messageId":"550f9510708300515s2069d680y1a02d95d517ec705@mail.gmail.com","threadId":"9702","inReplyTo":"Pine.LNX.4.64.0708301254420.28586@racer.site","subject":"Re: [PATCH] Add commands that git-gc runs underneath","fromName":"Tom Clarke","fromEmail":"tom@u2i.com","sentAt":"2007-08-30T12:15:30Z","receivedAt":"2007-08-30T12:15:30Z","isPatch":true,"sender":{"key":"tom@u2i.com","avatar":null},"body":"On 8/30/07, Johannes Schindelin wrote:\n> I have nothing against listing the commands per se. But the man page is\n> too exposed IMHO. (Or would you like to add the original shell script to\n> git-log's man page, too?)\n\nPerhaps the man pages for the lower level commands should reference\ngit-gc as the command that - unless you have special circumstances -\nyou probably want. As a new git user it was only reading this thread\nthat made me realise that git-gc is the command I want most of the\ntime - a number of the tutorials I had read referenced the low level\ncommands, and I didn't realise they had been superseded for normal\nuse.\n\n-Tom\n"},{"id":"51907","messageId":"20070830123432.GD10160@thunk.org","threadId":"9702","inReplyTo":"Pine.LNX.4.64.0708301254420.28586@racer.site","subject":"Re: [PATCH] Add commands that git-gc runs underneath","fromName":"Theodore Tso","fromEmail":"tytso@mit.edu","sentAt":"2007-08-30T12:34:32Z","receivedAt":"2007-08-30T12:34:32Z","isPatch":true,"sender":{"key":"tytso@mit.edu","avatar":"https://avatars.githubusercontent.com/u/51416?v=4"},"body":"On Thu, Aug 30, 2007 at 12:58:00PM +0100, Johannes Schindelin wrote:\n> On Thu, 30 Aug 2007, Andreas Ericsson wrote:\n> \n> > I kinda like it [listing the commands git-gc calls], and it might be \n> > helpful if someone's got a large repo and one part of gc for some reason \n> > didn't complete so they want to start at whatever step it broke off on.\n> \n> Let me clarify: I do not like the listing in the man page. This suggests \n> to the user to delve into plumbing areas where it is all too easy to shoot \n> yourself in the foot.\n\nI'm somewhat sympathetic to that argument, but at the same time, we're\nstill telling users to read the man page for plumbing areas in order\nto understand to get the listing valid command-line options to git\ncommands. In addition, the main git(1) man page is dedicating talking\nabout all sorts of low-level on-disk storage details that arguably\nshould be in the Documentation/technical that you suggested. I also\ndon't quite see how commands like git-repack, git-prune,\ngit-pack-refs, et. al., are likely to get the user into trouble, any\nmore than git-gc --prune might. Those commands are all relatively\nsafe, and indeed, they are all listed in the git-gc's \"SEE ALSO\"\nsection of its man page, so users are already being encouraged to\ndelve into plumbing areas.\n\nThat being said, given the SEE ALSO section, I don't think it adds a\nhuge amount of value to list the exact set of commands and options by\ngit-gc. Also, if we add more functionality to git-gc in the future,\nit would be pain to have to keep upgrading to man page uptodate.\n\n \t \t \t \t \t - Ted\n"},{"id":"51944","messageId":"7v7inc907e.fsf@gitster.siamese.dyndns.org","threadId":"9702","inReplyTo":"46D6984D.9040802@op5.se","subject":"Re: [PATCH] Add commands that git-gc runs underneath","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-08-30T21:33:41Z","receivedAt":"2007-08-30T21:33:41Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Andreas Ericsson writes:\n\n> When gc was a shell-script, it was fairly easy to find out the command-\n> sequence...\n\nMaybe referring more advanced/curious users to contrib/examples/\ndirectory is a good idea, but not necessarily from manpages of\nthe commands that have been rewritten in C.\n\nI think contrib/examples/ needs a README file that effectively\nsay \"these are the last versions of shell script implementation\nof the commands before they were rewritten in C. New features\nmay have been added to the built-in ones but these example\nscripts are not kept up to date. They are here to serve as\nexamples to show you how you would pipeline the plumbing level\ncommands.\"\n"},{"id":"52014","messageId":"46D7E058.9050001@op5.se","threadId":"9702","inReplyTo":"7v7inc907e.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] Add commands that git-gc runs underneath","fromName":"Andreas Ericsson","fromEmail":"ae@op5.se","sentAt":"2007-08-31T09:33:12Z","receivedAt":"2007-08-31T09:33:12Z","isPatch":true,"sender":{"key":"ae@op5.se","avatar":"https://gravatar.com/avatar/426e89595c75a8f5252dd0c989e5fabe5bcac616e68557427ad9aef6b0ca342a?d=mp&s=160"},"body":"Junio C Hamano wrote:\n> Andreas Ericsson writes:\n> \n>> When gc was a shell-script, it was fairly easy to find out the command-\n>> sequence...\n> \n> Maybe referring more advanced/curious users to contrib/examples/\n> directory is a good idea, but not necessarily from manpages of\n> the commands that have been rewritten in C.\n> \n> I think contrib/examples/ needs a README file that effectively\n> say \"these are the last versions of shell script implementation\n> of the commands before they were rewritten in C. New features\n> may have been added to the built-in ones but these example\n> scripts are not kept up to date. They are here to serve as\n> examples to show you how you would pipeline the plumbing level\n> commands.\"\n> \n\nSensible, and also avoids the possible bitrot problem with the\nman-page should there be additional actions added to standard\ngit-gc operations.\n\n-- \nAndreas Ericsson andreas.ericsson@op5.se\nOP5 AB www.op5.se\nTel: +46 8-230225 Fax: +46 8-230231\n"},{"id":"52070","messageId":"85wsvbbj6c.fsf@lola.goethe.zz","threadId":"9702","inReplyTo":"46D7E058.9050001@op5.se","subject":"Re: [PATCH] Add commands that git-gc runs underneath","fromName":"David Kastrup","fromEmail":"dak@gnu.org","sentAt":"2007-08-31T19:25:31Z","receivedAt":"2007-08-31T19:25:31Z","isPatch":true,"sender":{"key":"dak@gnu.org","avatar":"https://avatars.githubusercontent.com/u/52141349?v=4"},"body":"Andreas Ericsson writes:\n\n> Junio C Hamano wrote:\n>> Andreas Ericsson writes:\n>>\n>>> When gc was a shell-script, it was fairly easy to find out the command-\n>>> sequence...\n>>\n>> Maybe referring more advanced/curious users to contrib/examples/\n>> directory is a good idea, but not necessarily from manpages of\n>> the commands that have been rewritten in C.\n>>\n>> I think contrib/examples/ needs a README file that effectively\n>> say \"these are the last versions of shell script implementation\n>> of the commands before they were rewritten in C. New features\n>> may have been added to the built-in ones but these example\n>> scripts are not kept up to date. They are here to serve as\n>> examples to show you how you would pipeline the plumbing level\n>> commands.\"\n>>\n>\n> Sensible, and also avoids the possible bitrot problem with the\n> man-page should there be additional actions added to standard\n> git-gc operations.\n\nLet's just make all manual pages empty, and then we have solved all\nmanual page bitrot problems in one fell swoop.\n\nReally: I don't see how this helps at all. If I am interested in\nseeing what operations git-gc performs, I am not interested in some\nhistorical script's behavior.\n\nHiding that information into contrib/examples and telling people that\nit may be wrong, anyway, is not really helpful as a way of documenting\ngit-gc's behavior.\n\nOf _course_, _any_ useful documentation will have a \"possible bitrot\nproblem with the man-page\" whenever code is changed. The solution is\nnot to make the manual pages as useless as possible so that nothing\ncan be subject to bitrot. The solution is to update the information.\n\n-- \nDavid Kastrup, Kriemhildstr. 15, 44793 Bochum\n"},{"id":"52083","messageId":"7vlkbrxvbm.fsf@gitster.siamese.dyndns.org","threadId":"9702","inReplyTo":"46D7E058.9050001@op5.se","subject":"Re: [PATCH] Add commands that git-gc runs underneath","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-08-31T21:12:13Z","receivedAt":"2007-08-31T21:12:13Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Andreas Ericsson writes:\n\n> Junio C Hamano wrote:\n>> Andreas Ericsson writes:\n>>\n>>> When gc was a shell-script, it was fairly easy to find out the command-\n>>> sequence...\n>>\n>> Maybe referring more advanced/curious users to contrib/examples/\n>> directory is a good idea, but not necessarily from manpages of\n>> the commands that have been rewritten in C.\n>>\n>> I think contrib/examples/ needs a README file that effectively\n>> say \"these are the last versions of shell script implementation\n>> of the commands before they were rewritten in C. New features\n>> may have been added to the built-in ones but these example\n>> scripts are not kept up to date. They are here to serve as\n>> examples to show you how you would pipeline the plumbing level\n>> commands.\"\n>\n> Sensible, and also avoids the possible bitrot problem with the\n> man-page should there be additional actions added to standard\n> git-gc operations.\n\nOh, I did not mean to address bit-rot issue. I was addressing\n\"ah, in good old days we had tons of example scripts\" issue.\n\nIf we want the manual to be explicit about what exactly happens\nwhen you run \"git-gc\" (and I think we do), that needs to be done\nindependently. But my feeling is that we do not want to\ndescribe what happens solely in terms of what other individual\ncommands do. Referring to other manual pages for more details\nis fine, but that should not be the sole description.\n\nIn other words, instead of saying:\n\n - runs \"git pack-refs\", \"git reflog expire --all\", \"git repack\n -a -d -l\", ...\n\nI think we would want to say it this way:\n\n * Under such-and-such condition, loose refs are packed for\n quicker access in $GIT_DIR/packed-refs file (runs \"git\n pack-refs --prune\");\n\n * Old reflog entries that record how tips of each branches were\n moved are expired (runs \"git-reflog expire --all\");\n\n * Packfiles are repacked along with loose object files, while\n exclusing objects that are available from the alternates\n (runs \"git repack -a -d -l\");\n\n * Unreferenced loose objects are removed if --prune is given\n (runs \"git prune\");\n \n * Old rerere records that record resolutions to previously\n conflicted merges are expired (runs \"git rerere gc\").\n"},{"id":"52087","messageId":"85hcmfbdil.fsf@lola.goethe.zz","threadId":"9702","inReplyTo":"7vlkbrxvbm.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] Add commands that git-gc runs underneath","fromName":"David Kastrup","fromEmail":"dak@gnu.org","sentAt":"2007-08-31T21:27:46Z","receivedAt":"2007-08-31T21:27:46Z","isPatch":true,"sender":{"key":"dak@gnu.org","avatar":"https://avatars.githubusercontent.com/u/52141349?v=4"},"body":"Junio C Hamano writes:\n\n> But my feeling is that we do not want to describe what happens\n> solely in terms of what other individual commands do. Referring to\n> other manual pages for more details is fine, but that should not be\n> the sole description.\n>\n> In other words, instead of saying:\n\n[...]\n\n> I think we would want to say it this way:\n\n[...]\n\nI would say your feeling is dead-on. Full agreement with that\nproposal.\n\n-- \nDavid Kastrup, Kriemhildstr. 15, 44793 Bochum\n"}]}