{"thread":{"id":"10372","subject":"[PATCH 2/2] Documentation/git-gc: improve description of --auto","startedAt":"2007-10-19T02:05:10Z","lastAt":"2007-10-19T04:45:17Z","messageCount":4,"participants":["Jeff King","Shawn O. Pearce"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"56468","messageId":"20071019020510.GB7711@coredump.intra.peff.net","threadId":"10372","inReplyTo":null,"subject":"[PATCH 2/2] Documentation/git-gc: improve description of --auto","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2007-10-19T02:05:10Z","receivedAt":"2007-10-19T02:05:10Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"This patch tries to make the description of --auto a little\nmore clear for new users, especially those referred by the\n\"git-gc --auto\" notification message.\n\nIt also cleans up some grammatical errors and typos in the\noriginal description, as well as rewording for clarity.\n\nSigned-off-by: Jeff King \n---\nI started by just trying to fix a couple of grammar issues, but it\nseemed quite awkward, and somehow this came out. I think it reads better\nthan the original, but I'm open to comment.\n\nIt is a little bit odd that there is so much low-level detail in the\n'--auto' description versus the rest of the page. But I think it reads\nOK. Also note that the previous incarnation (and my changes) use the\n`foo` form to monospace arguments, while the rest of the page uses 'foo'\n(which actually means emphasis). I think the former is more correct, but\nasciidoc renders the latter much more pleasantly in manpages. I will see\nif I can tweak asciidoc to make this look better.\n\n Documentation/git-gc.txt | 29 +++++++++++++++++------------\n 1 files changed, 17 insertions(+), 12 deletions(-)\n\ndiff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt\nindex 83843a5..872056e 100644\n--- a/Documentation/git-gc.txt\n+++ b/Documentation/git-gc.txt\n@@ -45,18 +45,23 @@ OPTIONS\n \tfew hundred changesets or so.\n \n --auto::\n-\tWith this option, `git gc` checks if there are too many\n-\tloose objects in the repository and runs\n-\tgitlink:git-repack[1] with `-d -l` option to pack them.\n-\tThe threshold for loose objects is set with `gc.auto` configuration\n-\tvariable, and can be disabled by setting it to 0. Some\n-\tPorcelain commands use this after they perform operation\n-\tthat could create many loose objects automatically.\n-\tAdditionally, when there are too many packs are present,\n-\tthey are consolidated into one larger pack by running\n-\tthe `git-repack` command with `-A` option. The\n-\tthreshold for number of packs is set with\n-\t`gc.autopacklimit` configuration variable.\n+\tWith this option, `git gc` checks whether any housekeeping is\n+\trequired; if not, it exits without performing any work.\n+\tSome git commands run `git gc --auto` after performing\n+\toperations that could create many loose objects.\n++\n+Housekeeping is required if there are too many loose objects or\n+too many packs in the repository. If the number of loose objects\n+exceeds the value of the `gc.auto` configuration variable, then\n+all loose objects are combined into a single pack using\n+`git-repack -d -l`. Setting the value of `gc.auto` to 0\n+disables automatic packing of loose objects.\n++\n+If the number of packs exceeds the value of `gc.autopacklimit`,\n+then existing packs (except those marked with a `.keep` file)\n+are consolidated into a single pack by using the `-A` option of\n+`git-repack`. Setting `gc.autopacklimit` to 0 disables\n+automatic consolidation of packs.\n \n Configuration\n -------------\n-- \n1.5.3.4.1249.g895be-dirty\n"},{"id":"56477","messageId":"20071019022909.GZ14735@spearce.org","threadId":"10372","inReplyTo":"20071019020510.GB7711@coredump.intra.peff.net","subject":"Re: [PATCH 2/2] Documentation/git-gc: improve description of --auto","fromName":"Shawn O. Pearce","fromEmail":"spearce@spearce.org","sentAt":"2007-10-19T02:29:09Z","receivedAt":"2007-10-19T02:29:09Z","isPatch":true,"sender":{"key":"spearce@spearce.org","avatar":"https://avatars.githubusercontent.com/u/34844?v=4"},"body":"Jeff King wrote:\n> It is a little bit odd that there is so much low-level detail in the\n> '--auto' description versus the rest of the page. But I think it reads\n> OK. Also note that the previous incarnation (and my changes) use the\n> `foo` form to monospace arguments, while the rest of the page uses 'foo'\n> (which actually means emphasis). I think the former is more correct, but\n> asciidoc renders the latter much more pleasantly in manpages. I will see\n> if I can tweak asciidoc to make this look better.\n\nI like this a lot better than what was there before. Nice work.\nI have no real opinion on the asciidoc syntax.\n\nI personally prefer to read commands in the source as `foo` and\nfeel that asciidoc should just format it correctly for the backend.\nIf it isn't then we should try to work with the asciidoc folks to\nget it right...\n\n> --auto::\n> -\tWith this option, `git gc` checks if there are too many\n> -\tloose objects in the repository and runs\n> -\tgitlink:git-repack[1] with `-d -l` option to pack them.\n> -\tThe threshold for loose objects is set with `gc.auto` configuration\n> -\tvariable, and can be disabled by setting it to 0. Some\n> -\tPorcelain commands use this after they perform operation\n> -\tthat could create many loose objects automatically.\n> -\tAdditionally, when there are too many packs are present,\n> -\tthey are consolidated into one larger pack by running\n> -\tthe `git-repack` command with `-A` option. The\n> -\tthreshold for number of packs is set with\n> -\t`gc.autopacklimit` configuration variable.\n> +\tWith this option, `git gc` checks whether any housekeeping is\n> +\trequired; if not, it exits without performing any work.\n> +\tSome git commands run `git gc --auto` after performing\n> +\toperations that could create many loose objects.\n> ++\n> +Housekeeping is required if there are too many loose objects or\n> +too many packs in the repository. If the number of loose objects\n> +exceeds the value of the `gc.auto` configuration variable, then\n> +all loose objects are combined into a single pack using\n> +`git-repack -d -l`. Setting the value of `gc.auto` to 0\n> +disables automatic packing of loose objects.\n> ++\n> +If the number of packs exceeds the value of `gc.autopacklimit`,\n> +then existing packs (except those marked with a `.keep` file)\n> +are consolidated into a single pack by using the `-A` option of\n> +`git-repack`. Setting `gc.autopacklimit` to 0 disables\n> +automatic consolidation of packs.\n\n-- \nShawn.\n"},{"id":"56482","messageId":"20071019023850.GD8298@coredump.intra.peff.net","threadId":"10372","inReplyTo":"20071019022909.GZ14735@spearce.org","subject":"Re: [PATCH 2/2] Documentation/git-gc: improve description of --auto","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2007-10-19T02:38:50Z","receivedAt":"2007-10-19T02:38:50Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Oct 18, 2007 at 10:29:09PM -0400, Shawn O. Pearce wrote:\n\n> I personally prefer to read commands in the source as `foo` and\n> feel that asciidoc should just format it correctly for the backend.\n> If it isn't then we should try to work with the asciidoc folks to\n> get it right...\n\nI am hunting this down right now. asciidoc _does_ generate\nXML foo for `foo`, but it looks like docbook is\nthrowing that away when converting to manpages. Hopefully there is an\neasy tweak...\n\n-Peff\n"},{"id":"56518","messageId":"20071019044517.GA18354@coredump.intra.peff.net","threadId":"10372","inReplyTo":"20071019023850.GD8298@coredump.intra.peff.net","subject":"Re: [PATCH 2/2] Documentation/git-gc: improve description of --auto","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2007-10-19T04:45:17Z","receivedAt":"2007-10-19T04:45:17Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Oct 18, 2007 at 10:38:50PM -0400, Jeff King wrote:\n\n> I am hunting this down right now. asciidoc _does_ generate\n> XML foo for `foo`, but it looks like docbook is\n> throwing that away when converting to manpages. Hopefully there is an\n> easy tweak...\n\nUgh. Looks like Junio came up with a solution to this in 524e5ffc\n(although it was for literallayout sections, I think the same technique\ncould be applied). However, it had problems with docbook 1.69, and was\nreverted in 63c21c49.\n\nJulian Phillips added monospacing of listingblocks in 281a53bb, but that\ntechnique is only applicable to asciidoc \"blocks\", which I think won't\nwork in this instance.\n\nIt really seems silly that docbook doesn't monospace s when\nconverting to manpages. Perhaps somebody who knows more about docbook\nthan I do can say more.\n\n-Peff\n"}]}