{"thread":{"id":"32535","subject":"[PATCH] Alphabetize the fast-import options, following a suggestion on the list.","startedAt":"2013-01-05T16:44:15Z","lastAt":"2013-01-06T23:10:48Z","messageCount":9,"participants":["Eric S. Raymond","Jonathan Nieder","Junio C Hamano","John Keeping"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"206037","messageId":"20130105164415.39B144044B@snark.thyrsus.com","threadId":"32535","inReplyTo":null,"subject":"[PATCH] Alphabetize the fast-import options, following a suggestion on the list.","fromName":"Eric S. Raymond","fromEmail":"esr@thyrsus.com","sentAt":"2013-01-05T16:44:15Z","receivedAt":"2013-01-05T16:44:15Z","isPatch":true,"sender":{"key":"esr@thyrsus.com","avatar":"https://avatars.githubusercontent.com/u/727961?v=4"},"body":"---\n Documentation/git-fast-import.txt | 94 +++++++++++++++++++--------------------\n 1 file changed, 45 insertions(+), 49 deletions(-)\n\ndiff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt\nindex 68bca1a..d006bcf 100644\n--- a/Documentation/git-fast-import.txt\n+++ b/Documentation/git-fast-import.txt\n@@ -33,24 +33,9 @@ the frontend program in use.\n \n OPTIONS\n -------\n---date-format=::\n-\tSpecify the type of dates the frontend will supply to\n-\tfast-import within `author`, `committer` and `tagger` commands.\n-\tSee ``Date Formats'' below for details about which formats\n-\tare supported, and their syntax.\n-\n--- done::\n-\tTerminate with error if there is no 'done' command at the\n-\tend of the stream.\n-\n---force::\n-\tForce updating modified existing branches, even if doing\n-\tso would cause commits to be lost (as the new commit does\n-\tnot contain the old commit).\n-\n---max-pack-size=::\n-\tMaximum size of each output packfile.\n-\tThe default is unlimited.\n+--active-branches=::\n+\tMaximum number of branches to maintain active at once.\n+\tSee ``Memory Utilization'' below for details. Default is 5.\n \n --big-file-threshold=::\n \tMaximum size of a blob that fast-import will attempt to\n@@ -58,13 +43,27 @@ OPTIONS\n \t(512 MiB). Some importers may wish to lower this on systems\n \twith constrained memory.\n \n+--cat-blob-fd=::\n+\tWrite responses to `cat-blob` and `ls` queries to the\n+\tfile descriptor instead of `stdout`. Allows `progress`\n+\toutput intended for the end-user to be separated from other\n+\toutput.\n+\n+--date-format=::\n+\tSpecify the type of dates the frontend will supply to\n+\tfast-import within `author`, `committer` and `tagger` commands.\n+\tSee ``Date Formats'' below for details about which formats\n+\tare supported, and their syntax.\n+\n --depth=::\n \tMaximum delta depth, for blob and tree deltification.\n \tDefault is 10.\n \n---active-branches=::\n-\tMaximum number of branches to maintain active at once.\n-\tSee ``Memory Utilization'' below for details. Default is 5.\n+--done::\n+\tTerminate with error if there is no 'done' command at the end\n+\tof the stream. This option might be useful for detecting\n+\terrors that cause the frontend to terminate before it has\n+\tstarted to write a stream.\n \n --export-marks=::\n \tDumps the internal marks table to when complete.\n@@ -75,6 +74,20 @@ OPTIONS\n \tat checkpoint (or completion) the same path can also be\n \tsafely given to \\--import-marks.\n \n+--export-pack-edges=::\n+\tAfter creating a packfile, print a line of data to\n+\t listing the filename of the packfile and the last\n+\tcommit on each branch that was written to that packfile.\n+\tThis information may be useful after importing projects\n+\twhose total object set exceeds the 4 GiB packfile limit,\n+\tas these commits can be used as edge points during calls\n+\tto 'git pack-objects'.\n+\n+--force::\n+\tForce updating modified existing branches, even if doing\n+\tso would cause commits to be lost (as the new commit does\n+\tnot contain the old commit).\n+\n --import-marks=::\n \tBefore processing any input, load the marks specified in\n \t. The input file must exist, must be readable, and\n@@ -87,13 +100,9 @@ OPTIONS\n \tLike --import-marks but instead of erroring out, silently\n \tskips the file if it does not exist.\n \n---relative-marks::\n-\tAfter specifying --relative-marks the paths specified\n-\twith --import-marks= and --export-marks= are relative\n-\tto an internal directory in the current repository.\n-\tIn git-fast-import this means that the paths are relative\n-\tto the .git/info/fast-import directory. However, other\n-\timporters may use a different location.\n+--max-pack-size=::\n+\tMaximum size of each output packfile.\n+\tThe default is unlimited.\n \n --no-relative-marks::\n \tNegates a previous --relative-marks. Allows for combining\n@@ -101,32 +110,19 @@ OPTIONS\n \t--(no-)-relative-marks with the --(import|export)-marks=\n \toptions.\n \n---cat-blob-fd=::\n-\tWrite responses to `cat-blob` and `ls` queries to the\n-\tfile descriptor instead of `stdout`. Allows `progress`\n-\toutput intended for the end-user to be separated from other\n-\toutput.\n-\n---done::\n-\tRequire a `done` command at the end of the stream.\n-\tThis option might be useful for detecting errors that\n-\tcause the frontend to terminate before it has started to\n-\twrite a stream.\n-\n---export-pack-edges=::\n-\tAfter creating a packfile, print a line of data to\n-\t listing the filename of the packfile and the last\n-\tcommit on each branch that was written to that packfile.\n-\tThis information may be useful after importing projects\n-\twhose total object set exceeds the 4 GiB packfile limit,\n-\tas these commits can be used as edge points during calls\n-\tto 'git pack-objects'.\n-\n --quiet::\n \tDisable all non-fatal output, making fast-import silent when it\n \tis successful. This option disables the output shown by\n \t\\--stats.\n \n+--relative-marks::\n+\tAfter specifying --relative-marks the paths specified\n+\twith --import-marks= and --export-marks= are relative\n+\tto an internal directory in the current repository.\n+\tIn git-fast-import this means that the paths are relative\n+\tto the .git/info/fast-import directory. However, other\n+\timporters may use a different location.\n+\n --stats::\n \tDisplay some basic statistics about the objects fast-import has\n \tcreated, the packfiles they were stored into, and the\n-- \n1.8.1\n\n\n\n-- \n\t\tEric S. Raymond\n\n\"Gun control\" is a job-safety program for criminals.\n"},{"id":"206070","messageId":"20130105231151.GD3247@elie.Belkin","threadId":"32535","inReplyTo":"20130105164415.39B144044B@snark.thyrsus.com","subject":"Re: [PATCH] Alphabetize the fast-import options, following a suggestion on the list.","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2013-01-05T23:11:51Z","receivedAt":"2013-01-05T23:11:51Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Eric S. Raymond wrote:\n\n> ---\n\nMissing sign-off. Depending on when you prefer to add the sign-off, something\nlike\n\n\techo '[alias] c = commit --signoff' >>~/.gitconfig\n\nor\n\n\techo '[alias] f = format-patch --signoff' >>~/.gitconfig\n\nmight be useful for the future, assuming you already look over what\nyou are sending out in a mail client to avoid mistakes.\n\n> Documentation/git-fast-import.txt | 94 +++++++++++++++++++--------------------\n> 1 file changed, 45 insertions(+), 49 deletions(-)\n\nMy knee-jerk response was \"If the options are currently organized logically,\nwouldn't it be more appropriate to add a sub-heading for each group of options\nand alphabetize only within the subgroups?\"\n\nBut in fact the current options list doesn't seem to be well organized at all.\nWhat do you think would be a logical way to group these?\n\n Features of input syntax\n\n\t--date-format\n\t--done\n\n Verbosity\n\n\t--quiet\n\t--stats\n\n Marks handling (checkpoint/restore)\n\n\t--import-marks\n\t--import-marks-if-exists\n\t--export-marks\n\t--relative-marks\n\n Semantics of execution\n\n\t--dry-run\n\t--force\n\t--cat-blob-fd\n\t--export-pack-edges\n\n Tuning\n\n\t--active-branches\n\t--max-pack-size\n\t--big-file-threshold\n\t--depth\n"},{"id":"206084","messageId":"20130106051309.GB2303@thyrsus.com","threadId":"32535","inReplyTo":"20130105231151.GD3247@elie.Belkin","subject":"Re: [PATCH] Alphabetize the fast-import options, following a suggestion on the list.","fromName":"Eric S. Raymond","fromEmail":"esr@thyrsus.com","sentAt":"2013-01-06T05:13:09Z","receivedAt":"2013-01-06T05:13:09Z","isPatch":true,"sender":{"key":"esr@thyrsus.com","avatar":"https://avatars.githubusercontent.com/u/727961?v=4"},"body":"Jonathan Nieder :\n> But in fact the current options list doesn't seem to be well organized at all.\n\nI agree.\n\n> What do you think would be a logical way to group these?\n> \n> Features of input syntax\n> \n> \t--date-format\n> \t--done\n> \n> Verbosity\n> \n> \t--quiet\n> \t--stats\n> \n> Marks handling (checkpoint/restore)\n> \n> \t--import-marks\n> \t--import-marks-if-exists\n> \t--export-marks\n> \t--relative-marks\n> \n> Semantics of execution\n> \n> \t--dry-run\n> \t--force\n> \t--cat-blob-fd\n> \t--export-pack-edges\n> \n> Tuning\n> \n> \t--active-branches\n> \t--max-pack-size\n> \t--big-file-threshold\n> \t--depth\n\nThat would work as well or better than any other organization I can\nthink of. Um, which is significant because my work on surgery tools\nand exporters means I've had to consult this page a *lot*.\n-- \n\t\tEric S. Raymond\n"},{"id":"206115","messageId":"7vy5g6okdi.fsf@alter.siamese.dyndns.org","threadId":"32535","inReplyTo":"20130105231151.GD3247@elie.Belkin","subject":"Re: [PATCH] Alphabetize the fast-import options, following a suggestion on the list.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-01-06T07:12:25Z","receivedAt":"2013-01-06T07:12:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder writes:\n\n> My knee-jerk response was \"If the options are currently organized logically,\n> wouldn't it be more appropriate to add a sub-heading for each group of options\n> and alphabetize only within the subgroups?\"\n>\n> But in fact the current options list doesn't seem to be well organized at all.\n> What do you think would be a logical way to group these?\n>\n> Features of input syntax\n>\n> \t--date-format\n> \t--done\n>\n> Verbosity\n>\n> \t--quiet\n> \t--stats\n>\n> Marks handling (checkpoint/restore)\n>\n> \t--import-marks\n> \t--import-marks-if-exists\n> \t--export-marks\n> \t--relative-marks\n>\n> Semantics of execution\n>\n> \t--dry-run\n> \t--force\n> \t--cat-blob-fd\n> \t--export-pack-edges\n>\n> Tuning\n>\n> \t--active-branches\n> \t--max-pack-size\n> \t--big-file-threshold\n> \t--depth\n\nSounds sensible.\n"},{"id":"206132","messageId":"20130106132915.GG6440@serenity.lan","threadId":"32535","inReplyTo":"7vy5g6okdi.fsf@alter.siamese.dyndns.org","subject":"[PATCH] git-fast-import(1): reorganise options","fromName":"John Keeping","fromEmail":"john@keeping.me.uk","sentAt":"2013-01-06T13:29:15Z","receivedAt":"2013-01-06T13:29:15Z","isPatch":true,"sender":{"key":"john@keeping.me.uk","avatar":"https://avatars.githubusercontent.com/u/1702081?v=4"},"body":"On Sat, Jan 05, 2013 at 11:12:25PM -0800, Junio C Hamano wrote:\n> Jonathan Nieder writes:\n>> But in fact the current options list doesn't seem to be well organized at all.\n>> What do you think would be a logical way to group these?\n>>\n>> Features of input syntax\n>>\n>> \t--date-format\n>> \t--done\n>>\n>> Verbosity\n>>\n>> \t--quiet\n>> \t--stats\n>>\n>> Marks handling (checkpoint/restore)\n>>\n>> \t--import-marks\n>> \t--import-marks-if-exists\n>> \t--export-marks\n>> \t--relative-marks\n>>\n>> Semantics of execution\n>>\n>> \t--dry-run\n>> \t--force\n>> \t--cat-blob-fd\n>> \t--export-pack-edges\n>>\n>> Tuning\n>>\n>> \t--active-branches\n>> \t--max-pack-size\n>> \t--big-file-threshold\n>> \t--depth\n> \n> Sounds sensible.\n\nHow about this?\n\nI left the \"Semantics of execution\" options with the general options\nsince I couldn't think of a sensible heading that didn't also apply to\n'--quiet' or '--stats', but I think the result is reasonable.\n\n-- <8 --\n\nThe options in git-fast-import(1) are not currently arranged in a\nlogical order, which has caused the '--done' options to be documented\ntwice (commit 3266de10).\n\nRearrange them into logical groups under subheadings.\n\nWhile doing this, fix the duplicate '--done' documentation by taking the\nbest bits of each. Also combine the descriptions of '--relative-marks'\nand '--no-relative-marks' since they make more sense together.\n\nSuggested-by: Jonathan Nieder \nSigned-off-by: John Keeping \n---\n Documentation/git-fast-import.txt | 115 +++++++++++++++++++-------------------\n 1 file changed, 59 insertions(+), 56 deletions(-)\n\ndiff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt\nindex 68bca1a..0e25c8d 100644\n--- a/Documentation/git-fast-import.txt\n+++ b/Documentation/git-fast-import.txt\n@@ -33,38 +33,55 @@ the frontend program in use.\n \n OPTIONS\n -------\n---date-format=::\n-\tSpecify the type of dates the frontend will supply to\n-\tfast-import within `author`, `committer` and `tagger` commands.\n-\tSee ``Date Formats'' below for details about which formats\n-\tare supported, and their syntax.\n \n--- done::\n-\tTerminate with error if there is no 'done' command at the\n-\tend of the stream.\n+--quiet::\n+\tDisable all non-fatal output, making fast-import silent when it\n+\tis successful. This option disables the output shown by\n+\t\\--stats.\n+\n+--stats::\n+\tDisplay some basic statistics about the objects fast-import has\n+\tcreated, the packfiles they were stored into, and the\n+\tmemory used by fast-import during this run. Showing this output\n+\tis currently the default, but can be disabled with \\--quiet.\n \n --force::\n \tForce updating modified existing branches, even if doing\n \tso would cause commits to be lost (as the new commit does\n \tnot contain the old commit).\n \n---max-pack-size=::\n-\tMaximum size of each output packfile.\n-\tThe default is unlimited.\n+--cat-blob-fd=::\n+\tWrite responses to `cat-blob` and `ls` queries to the\n+\tfile descriptor instead of `stdout`. Allows `progress`\n+\toutput intended for the end-user to be separated from other\n+\toutput.\n \n---big-file-threshold=::\n-\tMaximum size of a blob that fast-import will attempt to\n-\tcreate a delta for, expressed in bytes. The default is 512m\n-\t(512 MiB). Some importers may wish to lower this on systems\n-\twith constrained memory.\n+--export-pack-edges=::\n+\tAfter creating a packfile, print a line of data to\n+\t listing the filename of the packfile and the last\n+\tcommit on each branch that was written to that packfile.\n+\tThis information may be useful after importing projects\n+\twhose total object set exceeds the 4 GiB packfile limit,\n+\tas these commits can be used as edge points during calls\n+\tto 'git pack-objects'.\n \n---depth=::\n-\tMaximum delta depth, for blob and tree deltification.\n-\tDefault is 10.\n+Options related to the input stream\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n---active-branches=::\n-\tMaximum number of branches to maintain active at once.\n-\tSee ``Memory Utilization'' below for details. Default is 5.\n+--date-format=::\n+\tSpecify the type of dates the frontend will supply to\n+\tfast-import within `author`, `committer` and `tagger` commands.\n+\tSee ``Date Formats'' below for details about which formats\n+\tare supported, and their syntax.\n+\n+--done::\n+\tTerminate with error if there is no `done` command at the end of\n+\tthe stream. This option might be useful for detecting errors\n+\tthat cause the frontend to terminate before it has started to\n+\twrite a stream.\n+\n+Options related to marks\n+~~~~~~~~~~~~~~~~~~~~~~~~\n \n --export-marks=::\n \tDumps the internal marks table to when complete.\n@@ -87,51 +104,37 @@ OPTIONS\n \tLike --import-marks but instead of erroring out, silently\n \tskips the file if it does not exist.\n \n---relative-marks::\n+--[no-]relative-marks::\n \tAfter specifying --relative-marks the paths specified\n \twith --import-marks= and --export-marks= are relative\n \tto an internal directory in the current repository.\n \tIn git-fast-import this means that the paths are relative\n \tto the .git/info/fast-import directory. However, other\n \timporters may use a different location.\n++\n+Relative and non-relative marks may be combined by interweaving\n+--(no-)-relative-marks with the --(import|export)-marks= options.\n \n---no-relative-marks::\n-\tNegates a previous --relative-marks. Allows for combining\n-\trelative and non-relative marks by interweaving\n-\t--(no-)-relative-marks with the --(import|export)-marks=\n-\toptions.\n+Options for tuning\n+~~~~~~~~~~~~~~~~~~\n \n---cat-blob-fd=::\n-\tWrite responses to `cat-blob` and `ls` queries to the\n-\tfile descriptor instead of `stdout`. Allows `progress`\n-\toutput intended for the end-user to be separated from other\n-\toutput.\n-\n---done::\n-\tRequire a `done` command at the end of the stream.\n-\tThis option might be useful for detecting errors that\n-\tcause the frontend to terminate before it has started to\n-\twrite a stream.\n+--active-branches=::\n+\tMaximum number of branches to maintain active at once.\n+\tSee ``Memory Utilization'' below for details. Default is 5.\n \n---export-pack-edges=::\n-\tAfter creating a packfile, print a line of data to\n-\t listing the filename of the packfile and the last\n-\tcommit on each branch that was written to that packfile.\n-\tThis information may be useful after importing projects\n-\twhose total object set exceeds the 4 GiB packfile limit,\n-\tas these commits can be used as edge points during calls\n-\tto 'git pack-objects'.\n+--big-file-threshold=::\n+\tMaximum size of a blob that fast-import will attempt to\n+\tcreate a delta for, expressed in bytes. The default is 512m\n+\t(512 MiB). Some importers may wish to lower this on systems\n+\twith constrained memory.\n \n---quiet::\n-\tDisable all non-fatal output, making fast-import silent when it\n-\tis successful. This option disables the output shown by\n-\t\\--stats.\n+--depth=::\n+\tMaximum delta depth, for blob and tree deltification.\n+\tDefault is 10.\n \n---stats::\n-\tDisplay some basic statistics about the objects fast-import has\n-\tcreated, the packfiles they were stored into, and the\n-\tmemory used by fast-import during this run. Showing this output\n-\tis currently the default, but can be disabled with \\--quiet.\n+--max-pack-size=::\n+\tMaximum size of each output packfile.\n+\tThe default is unlimited.\n \n \n Performance\n-- \n1.8.0.2\n"},{"id":"206133","messageId":"20130106133415.GE22081@elie.Belkin","threadId":"32535","inReplyTo":"20130105231151.GD3247@elie.Belkin","subject":"[PATCH/RFC] fast-import doc: split OPTIONS into subsections","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2013-01-06T13:34:15Z","receivedAt":"2013-01-06T13:34:15Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"The OPTIONS section of this manpage has grown long without any\nparticular organization to ensure it remains manageable. Split into\ncategories to make the documentation for each option easier to find.\nThe categories:\n\n 1. Features of the input format, such as the date format and whether\n the file is required to end with a \"done\" command.\n 2. How much output the importer should write to stderr.\n 3. Marks Handling (Checkpoint/Restart).\n 4. Other options that change the behavior in a semantically\n meaningful way (backflow pipe setup, whether to force ref\n updates, where to list pack edges).\n 5. Performance and compression tuning.\n\nReported-by: John Keeping \nSigned-off-by: Jonathan Nieder \n---\nThe second-to-last subsection (\"Import Semantics\") is kind of a\ncatch-all. Better ideas for organization or naming would be\nwelcome.\n\n Documentation/git-fast-import.txt | 82 ++++++++++++++++++++++-----------------\n 1 file changed, 46 insertions(+), 36 deletions(-)\n\ndiff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt\nindex d2c0e357..1676d436 100644\n--- a/Documentation/git-fast-import.txt\n+++ b/Documentation/git-fast-import.txt\n@@ -32,35 +32,36 @@ the frontend program in use.\n \n OPTIONS\n -------\n+Input Syntax\n+~~~~~~~~~~~~\n --date-format=::\n \tSpecify the type of dates the frontend will supply to\n \tfast-import within `author`, `committer` and `tagger` commands.\n \tSee ``Date Formats'' below for details about which formats\n \tare supported, and their syntax.\n \n---force::\n-\tForce updating modified existing branches, even if doing\n-\tso would cause commits to be lost (as the new commit does\n-\tnot contain the old commit).\n+--done::\n+\tTerminate with error if there is no 'done' command at the\n+\tend of the stream.\n+\tThis option might be useful for detecting errors that\n+\tcause the frontend to terminate before it has started to\n+\twrite a stream.\n \n---max-pack-size=::\n-\tMaximum size of each output packfile.\n-\tThe default is unlimited.\n+Verbosity\n+~~~~~~~~~\n+--quiet::\n+\tDisable all non-fatal output, making fast-import silent when it\n+\tis successful. This option disables the output shown by\n+\t\\--stats.\n \n---big-file-threshold=::\n-\tMaximum size of a blob that fast-import will attempt to\n-\tcreate a delta for, expressed in bytes. The default is 512m\n-\t(512 MiB). Some importers may wish to lower this on systems\n-\twith constrained memory.\n-\n---depth=::\n-\tMaximum delta depth, for blob and tree deltification.\n-\tDefault is 10.\n-\n---active-branches=::\n-\tMaximum number of branches to maintain active at once.\n-\tSee ``Memory Utilization'' below for details. Default is 5.\n+--stats::\n+\tDisplay some basic statistics about the objects fast-import has\n+\tcreated, the packfiles they were stored into, and the\n+\tmemory used by fast-import during this run. Showing this output\n+\tis currently the default, but can be disabled with \\--quiet.\n \n+Marks Handling (Checkpoint/Restart)\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n --export-marks=::\n \tDumps the internal marks table to when complete.\n \tMarks are written one per line as `:markid SHA-1`.\n@@ -96,18 +97,18 @@ OPTIONS\n \t--(no-)-relative-marks with the --(import|export)-marks=\n \toptions.\n \n+Import Semantics\n+~~~~~~~~~~~~~~~~\n+--force::\n+\tForce updating modified existing branches, even if doing\n+\tso would cause commits to be lost (as the new commit does\n+\tnot contain the old commit).\n+\n --cat-blob-fd=::\n \tSpecify the file descriptor that will be written to\n \twhen the `cat-blob` command is encountered in the stream.\n \tThe default behaviour is to write to `stdout`.\n \n---done::\n-\tTerminate with error if there is no 'done' command at the\n-\tend of the stream.\n-\tThis option might be useful for detecting errors that\n-\tcause the frontend to terminate before it has started to\n-\twrite a stream.\n-\n --export-pack-edges=::\n \tAfter creating a packfile, print a line of data to\n \t listing the filename of the packfile and the last\n@@ -117,16 +118,25 @@ OPTIONS\n \tas these commits can be used as edge points during calls\n \tto 'git pack-objects'.\n \n---quiet::\n-\tDisable all non-fatal output, making fast-import silent when it\n-\tis successful. This option disables the output shown by\n-\t\\--stats.\n+Tuning\n+~~~~~~\n+--max-pack-size=::\n+\tMaximum size of each output packfile.\n+\tThe default is unlimited.\n \n---stats::\n-\tDisplay some basic statistics about the objects fast-import has\n-\tcreated, the packfiles they were stored into, and the\n-\tmemory used by fast-import during this run. Showing this output\n-\tis currently the default, but can be disabled with \\--quiet.\n+--big-file-threshold=::\n+\tMaximum size of a blob that fast-import will attempt to\n+\tcreate a delta for, expressed in bytes. The default is 512m\n+\t(512 MiB). Some importers may wish to lower this on systems\n+\twith constrained memory.\n+\n+--depth=::\n+\tMaximum delta depth, for blob and tree deltification.\n+\tDefault is 10.\n+\n+--active-branches=::\n+\tMaximum number of branches to maintain active at once.\n+\tSee ``Memory Utilization'' below for details. Default is 5.\n \n \n Performance\n-- \n1.8.1\n"},{"id":"206134","messageId":"20130106135109.GF22081@elie.Belkin","threadId":"32535","inReplyTo":"20130106132915.GG6440@serenity.lan","subject":"Re: [PATCH] git-fast-import(1): reorganise options","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2013-01-06T13:51:09Z","receivedAt":"2013-01-06T13:51:09Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"John Keeping wrote:\n\n> How about this?\n\nAh, our patches crossed.\n\n> I left the \"Semantics of execution\" options with the general options\n> since I couldn't think of a sensible heading\n\nNeat trick. :)\n\n[...]\n> -- <8 --\n> The options in git-fast-import(1) are not currently arranged in a\n> logical order, which has caused the '--done' options to be documented\n> twice (commit 3266de10).\n>\n> Rearrange them into logical groups under subheadings.\n\nNice description.\n\n> While doing this, fix the duplicate '--done' documentation by taking the\n> best bits of each. Also combine the descriptions of '--relative-marks'\n> and '--no-relative-marks' since they make more sense together.\n\nI'd prefer to keep those as separate patches, if that's manageable.\n\nThe organization you propose is:\n\n\tOPTIONS\n\t-------\n\t--quiet\n\t--stats\n\t--force\n\t--cat-blob-fd\n\t--export-pack-edges\n\n\tOptions related to the input stream\n\t~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\t--date-format\n\t--done\n\n\tOptions related to marks\n\t~~~~~~~~~~~~~~~~~~~~~~~~\n\t--export-marks\n\t--import-marks\n\t--import-marks-if-exists\n\t--relative-marks\n\t--no-relative-marks\n\n\tOptions for tuning\n\t~~~~~~~~~~~~~~~~~~\n\t--active-branches\n\t--big-file-threshold\n\t--depth\n\t--max-pack-size\n\nThese headings are less cryptic than the ones I proposed, which is a\nnice thing.\n\nMy only nitpicks:\n\nI'd worry that the catch-all toplevel category would grow larger\nand larger with time, since it's the obvious place to put any new\noption.\n\nPart of what I tried to do with the proposed categorization was to\nseparate options that change the semantics of the import (which one\nuses with \"feature\" when they are specified in the fast-import stream\nsince ignoring them results in a broken import) from options that only\nchange superficial aspects of the interface or the details of how the\nresulting packfiles representing the same objects get written.\n\nThe phrasing of the name of the category \"Options related to the input\nstream\" is too broad. All options relate to the input stream, since\nconsuming an input stream and acting on it is all fast-import does.\nSomething more specific than \"related to\" and a mention of \"syntax\"\ncould make it clearer --- how about something like \"Input Syntax\nFeatures\"?\n\nLikewise, lots of functionality is _related_ to marks, but the marks\noptions are the options that specify marks files. I don't know a good\nway to say that --- maybe \"Location of Marks Files\"?\n\n\"Options for Tuning\" could also be made more specific --- e.g.,\n\"Performance and Compression Tuning\".\n\nI like how you put important options like --force on top. Perhaps\nthe less important --quiet and --stats could be split off from that\ninto a subsection like \"Verbosity\" to make them stand out even more.\n\nGenerally I think this is a better starting point for future work than\nthe patch I sent. Thanks for writing it.\n\nJonathan\n"},{"id":"206137","messageId":"20130106142825.GH6440@serenity.lan","threadId":"32535","inReplyTo":"20130106135109.GF22081@elie.Belkin","subject":"Re: [PATCH] git-fast-import(1): reorganise options","fromName":"John Keeping","fromEmail":"john@keeping.me.uk","sentAt":"2013-01-06T14:28:25Z","receivedAt":"2013-01-06T14:28:25Z","isPatch":true,"sender":{"key":"john@keeping.me.uk","avatar":"https://avatars.githubusercontent.com/u/1702081?v=4"},"body":"On Sun, Jan 06, 2013 at 05:51:09AM -0800, Jonathan Nieder wrote:\n> John Keeping wrote:\n>> I left the \"Semantics of execution\" options with the general options\n>> since I couldn't think of a sensible heading\n> \n> Neat trick. :)\n\nI took inspiration from git-pull(1), which has a few general options\nfollowed by several \"Options related to...\" sections.\n\n> [...]\n> > -- <8 --\n> > The options in git-fast-import(1) are not currently arranged in a\n> > logical order, which has caused the '--done' options to be documented\n> > twice (commit 3266de10).\n> >\n> > Rearrange them into logical groups under subheadings.\n> \n> Nice description.\n> \n> > While doing this, fix the duplicate '--done' documentation by taking the\n> > best bits of each. Also combine the descriptions of '--relative-marks'\n> > and '--no-relative-marks' since they make more sense together.\n> \n> I'd prefer to keep those as separate patches, if that's manageable.\n\nI'll send a series of three patches if the discussion below seems\nreasonable:\n\n[1/3] remove duplicate '--done'\n[2/3] combine --[no-]relative-marks\n[3/3] reorganize options\n\n> The organization you propose is:\n> \n> \tOPTIONS\n> \t-------\n> \t--quiet\n> \t--stats\n> \t--force\n> \t--cat-blob-fd\n> \t--export-pack-edges\n> \n> \tOptions related to the input stream\n> \t~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n> \t--date-format\n> \t--done\n> \n> \tOptions related to marks\n> \t~~~~~~~~~~~~~~~~~~~~~~~~\n> \t--export-marks\n> \t--import-marks\n> \t--import-marks-if-exists\n> \t--relative-marks\n> \t--no-relative-marks\n> \n> \tOptions for tuning\n> \t~~~~~~~~~~~~~~~~~~\n> \t--active-branches\n> \t--big-file-threshold\n> \t--depth\n> \t--max-pack-size\n> \n> These headings are less cryptic than the ones I proposed, which is a\n> nice thing.\n> \n> My only nitpicks:\n> \n> I'd worry that the catch-all toplevel category would grow larger\n> and larger with time, since it's the obvious place to put any new\n> option.\n\nI agree that that's a concern, perhaps '--cat-blob-fd' should be\ncombined with '--date-format' and '--done' into a section called\n\"Options for frontends\" or similar?\n\nAnd maybe '--export-pack-edges' can move to the performance/compression\ntuning section? I expect the interested audience would be the same.\n\nThat only leaves three options in that section, which seems more\nreasonable.\n\n> Part of what I tried to do with the proposed categorization was to\n> separate options that change the semantics of the import (which one\n> uses with \"feature\" when they are specified in the fast-import stream\n> since ignoring them results in a broken import) from options that only\n> change superficial aspects of the interface or the details of how the\n> resulting packfiles representing the same objects get written.\n>\n> The phrasing of the name of the category \"Options related to the input\n> stream\" is too broad. All options relate to the input stream, since\n> consuming an input stream and acting on it is all fast-import does.\n> Something more specific than \"related to\" and a mention of \"syntax\"\n> could make it clearer --- how about something like \"Input Syntax\n> Features\"?\n> \n> Likewise, lots of functionality is _related_ to marks, but the marks\n> options are the options that specify marks files. I don't know a good\n> way to say that --- maybe \"Location of Marks Files\"?\n>\n> \"Options for Tuning\" could also be made more specific --- e.g.,\n> \"Performance and Compression Tuning\".\n\nI realise it's personal taste, but I like the subheadings of the form\n\"Options (for|related to) ...\", so maybe:\n\nOptions for input stream features\nOptions related to marks files\nOptions for performance and compression tuning\n\nNote that I chose sentence case instead of title case to be consistent\nwith git-pull(1).\n\n> I like how you put important options like --force on top. Perhaps\n> the less important --quiet and --stats could be split off from that\n> into a subsection like \"Verbosity\" to make them stand out even more.\n\nI quite like having the verbosity options near the top since those are\nthe ones that are most likely to be of interest to a user, whereas the\nrest are likely to be prescribed by the frontend (or only really useful\nto frontend authors).\n\n\nJohn\n"},{"id":"206186","messageId":"7va9slnc07.fsf@alter.siamese.dyndns.org","threadId":"32535","inReplyTo":"20130106142825.GH6440@serenity.lan","subject":"Re: [PATCH] git-fast-import(1): reorganise options","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-01-06T23:10:48Z","receivedAt":"2013-01-06T23:10:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"John Keeping writes:\n\n> On Sun, Jan 06, 2013 at 05:51:09AM -0800, Jonathan Nieder wrote:\n> ...\n>> Nice description.\n>> \n>> > While doing this, fix the duplicate '--done' documentation by taking the\n>> > best bits of each. Also combine the descriptions of '--relative-marks'\n>> > and '--no-relative-marks' since they make more sense together.\n>> \n>> I'd prefer to keep those as separate patches, if that's manageable.\n>\n> I'll send a series of three patches if the discussion below seems\n> reasonable:\n>\n> [1/3] remove duplicate '--done'\n> [2/3] combine --[no-]relative-marks\n> [3/3] reorganize options\n\nSounds sensible and I like the direction in which this discussion is\nprogressing.\n\n>> I'd worry that the catch-all toplevel category would grow larger\n>> and larger with time, since it's the obvious place to put any new\n>> option.\n>\n> I agree that that's a concern, perhaps '--cat-blob-fd' should be\n> combined with '--date-format' and '--done' into a section called\n> \"Options for frontends\" or similar?\n>\n> And maybe '--export-pack-edges' can move to the performance/compression\n> tuning section? I expect the interested audience would be the same.\n>\n> That only leaves three options in that section, which seems more\n> reasonable.\n\nI'll leave it to others to decide which individual options would\nfall into that catch-all category, but the idea you outlined above\nsounds sensible overall.\n\n> I realise it's personal taste, but I like the subheadings of the form\n> \"Options (for|related to) ...\", so maybe:\n>\n> Options for input stream features\n> Options related to marks files\n> Options for performance and compression tuning\n\nAgain, sounds sensible.\n\n>> I like how you put important options like --force on top. Perhaps\n>> the less important --quiet and --stats could be split off from that\n>> into a subsection like \"Verbosity\" to make them stand out even more.\n>\n> I quite like having the verbosity options near the top since those are\n> the ones that are most likely to be of interest to a user, whereas the\n> rest are likely to be prescribed by the frontend (or only really useful\n> to frontend authors).\n\nI tend to agree with Jonathan that verbosity options are less\nimportant ones than the ones that affect how things work.\n\nThanks.\n"}]}