{"thread":{"id":"24532","subject":"[RFC PATCH 0/24] Documentation: refactor config variable descriptions","startedAt":"2010-07-26T18:48:52Z","lastAt":"2010-07-28T17:23:29Z","messageCount":14,"participants":["Thomas Rast","Ævar Arnfjörð Bjarmason","Jonathan Nieder","Jakub Narebski","Sverre Rabbelier","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":24},"messages":[{"id":"146416","messageId":"cover.1280169048.git.trast@student.ethz.ch","threadId":"24532","inReplyTo":null,"subject":"[RFC PATCH 0/24] Documentation: refactor config variable descriptions","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2010-07-26T18:48:52Z","receivedAt":"2010-07-26T18:48:52Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"This little series is a bit of a spinoff from\n\n  http://article.gmane.org/gmane.comp.version-control.git/146696\nand\n  http://article.gmane.org/gmane.comp.version-control.git/145139\n\nSince I didn't want to spam the list with 24 RFC emails, I squashed\nall the manpage-specific patches into one for this submission.  You\ncan find the originals at\n\n  git://repo.or.cz/git/trast.git t/doc-config-extraction  \n\nJudging from its size it's quite possible that\n\n  [1/24] Documentation: Move variables from config.txt to separate file\n\nwon't make it through to the list, either, and -M doesn't help, so you\nmay have to look it up at the above repository too.\n\n\nWork so far:\n\nI moved the variables from config.txt and merge-config.txt to a new\nfile, and made a little helper script that expands @@CONFIG(key)@@ in\nthe asciidoc files, driven by the Makefile of course.\n\nI then went over the manpages in the \"Main Porcelain Commands\" list of\ngit(1) and either (easy case) added a \"CONFIGURATION\" section with the\nrelevant variables or (hard case) tried to refactor the descriptions\nso that they are only kept in one place.\n\nÆvar kindly rewrote the Perl script in a more readable and error-safe\nstyle, which I squashed for this posting.  It's still a separate patch\nat the above link, too.\n\n\nFurther directions:\n\nI'm a bit hesitant to go in Peff's suggested direction of outright\nremoving all variables from git-config(1).  I would prefer to both\nhave the short list and group them by some category system, if that\nhappens to work out.  Perhaps the categorized list can eventually be\nremoved once we can verify that all variables are documented in\nanother manpage.\n\n\nKnown omissions/todos:\n\n* git-gc has an elaborate prose section to the same effect that I\n  wasn't quite ready to tear apart yet\n\n* git-notes has excellent custom descriptions from Jonathan's series\n  that I didn't want to refactor \n\n* The description of format.pretty in git-log.txt is unsatisfactory\n\n* check-docs or some other make target should verify that no manpage\n  links to itself\n\n\nThomas Rast (3):\n  Documentation: Move variables from config.txt to separate file\n  Documentation: Add variable-substitution script\n  Documentation: include configuration options in manpages\n\n Documentation/Makefile             |   14 +-\n Documentation/config-vars.txt      | 1761 ++++++++++++++++++++++++++++++++++++\n Documentation/config.txt           | 1693 +----------------------------------\n Documentation/git-add.txt          |    6 +-\n Documentation/git-am.txt           |   18 +\n Documentation/git-archive.txt      |    8 +-\n Documentation/git-branch.txt       |    8 +\n Documentation/git-checkout.txt     |    8 +\n Documentation/git-clean.txt        |    6 +\n Documentation/git-commit.txt       |    7 +\n Documentation/git-diff.txt         |   12 +\n Documentation/git-fetch.txt        |   12 +\n Documentation/git-format-patch.txt |   22 +-\n Documentation/git-grep.txt         |    7 +\n Documentation/git-gui.txt          |   16 +\n Documentation/git-log.txt          |   38 +-\n Documentation/git-merge.txt        |   15 +-\n Documentation/git-pull.txt         |   14 +\n Documentation/git-push.txt         |   19 +\n Documentation/git-rebase.txt       |    5 +-\n Documentation/git-shortlog.txt     |    6 +\n Documentation/git-status.txt       |   18 +-\n Documentation/git-submodule.txt    |    8 +\n Documentation/git-tag.txt          |   11 +-\n Documentation/gitk.txt             |    8 +\n Documentation/merge-config.txt     |   49 -\n Documentation/subst-config.perl    |   74 ++\n 27 files changed, 2042 insertions(+), 1821 deletions(-)\n create mode 100644 Documentation/config-vars.txt\n delete mode 100644 Documentation/merge-config.txt\n create mode 100755 Documentation/subst-config.perl\n\n-- \n1.7.2.349.gd5452\n"},{"id":"146418","messageId":"049043aa444288fd9409a3706fe3190fd679cb7d.1280169048.git.trast@student.ethz.ch","threadId":"24532","inReplyTo":"cover.1280169048.git.trast@student.ethz.ch","subject":"[PATCH 2/24] Documentation: Add variable-substitution script","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2010-07-26T18:48:54Z","receivedAt":"2010-07-26T18:48:54Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"The new subst-config.perl is run by the Makefile as\n\n  ./subst-config.perl <vars> <in> <out>\n\nIt first reads <vars> for variable-documenting blocks.  A line\nconsisting of '<name>::' starts the block for <name>, except inside a\n'--' delimited block (which is used to generate sub-lists).  A block\nextends until the first blank line, which is what asciidoc also looks\nfor.\n\nThen it copies from <in> to <out>, substituting lines of the form\n\n  @@CONFIG(<name>)@@\n\nwith the documentation block for <name>.\n\nÆvar kindly implemented the following, squashed into this patch:\n\n - Print a usage message when argument prerequisites aren't met\n - Use Getopt::Long instead of manually looking at @ARGV\n - use warnings, not -w\n - Split the parsing & substituting functionality into subroutines\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\nSigned-off-by: Thomas Rast <trast@student.ethz.ch>\n---\n Documentation/Makefile          |   14 +++++---\n Documentation/config-vars.txt   |    1 +\n Documentation/subst-config.perl |   74 +++++++++++++++++++++++++++++++++++++++\n 3 files changed, 84 insertions(+), 5 deletions(-)\n create mode 100755 Documentation/subst-config.perl\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex a4c4063..c20d580 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -239,12 +239,16 @@ cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT)\n clean:\n \t$(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7\n \t$(RM) *.texi *.texi+ *.texi++ git.info gitman.info\n+\t$(RM) *.txt.cv\n \t$(RM) howto-index.txt howto/*.html doc.dep\n \t$(RM) technical/api-*.html technical/api-index.txt\n \t$(RM) $(cmds_txt) *.made\n \t$(RM) manpage-base-url.xsl\n \n-$(MAN_HTML): %.html : %.txt\n+%.txt.cv : %.txt subst-config.perl config-vars.txt\n+\t$(QUIET_GEN) ./subst-config.perl --varlist=config-vars.txt --input=$< --output=$@\n+\n+$(patsubst %.txt,%.txt.cv,$(MAN_HTML)): %.html : %.txt.cv\n \t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n \t$(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf \\\n \t\t$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \\\n@@ -257,13 +261,13 @@ manpage-base-url.xsl: manpage-base-url.xsl.in\n \t$(QUIET_XMLTO)$(RM) $@ && \\\n \txmlto -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<\n \n-%.xml : %.txt\n+%.xml : %.txt.cv\n \t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n \t$(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \\\n \t\t$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \\\n \tmv $@+ $@\n \n-user-manual.xml: user-manual.txt user-manual.conf\n+user-manual.xml: user-manual.txt.cv user-manual.conf\n \t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n \t$(ASCIIDOC) $(ASCIIDOC_EXTRA) -b docbook -d book -o $@+ $< && \\\n \tmv $@+ $@\n@@ -320,8 +324,8 @@ howto-index.txt: howto-index.sh $(wildcard howto/*.txt)\n \t'$(SHELL_PATH_SQ)' ./howto-index.sh $(wildcard howto/*.txt) >$@+ && \\\n \tmv $@+ $@\n \n-$(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt\n-\t$(QUIET_ASCIIDOC)$(ASCIIDOC) $(ASCIIDOC_EXTRA) -b xhtml11 $*.txt\n+$(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt.cv\n+\t$(QUIET_ASCIIDOC)$(ASCIIDOC) $(ASCIIDOC_EXTRA) -b xhtml11 $*.txt.cv\n \n WEBDOC_DEST = /pub/software/scm/git/docs\n \ndiff --git a/Documentation/config-vars.txt b/Documentation/config-vars.txt\nindex b82fada..3fcefe9 100644\n--- a/Documentation/config-vars.txt\n+++ b/Documentation/config-vars.txt\n@@ -689,6 +689,7 @@ diff.mnemonicprefix::\n \tstandard \"a/\" and \"b/\" depending on what is being compared.  When\n \tthis configuration is in effect, reverse diff output also swaps\n \tthe order of the prefixes:\n+\n diff.noprefix::\n \tIf set, 'git diff' does not show any source or destination prefix.\n `git diff`;;\ndiff --git a/Documentation/subst-config.perl b/Documentation/subst-config.perl\nnew file mode 100755\nindex 0000000..a981670\n--- /dev/null\n+++ b/Documentation/subst-config.perl\n@@ -0,0 +1,74 @@\n+#!/usr/bin/perl\n+use 5.006002;\n+use strict;\n+use warnings;\n+use Getopt::Long;\n+\n+Getopt::Long::Configure qw/ pass_through /;\n+\n+my $rc = GetOptions(\n+    \"varlist=s\" => \\my $varlist,\n+    \"input=s\"   => \\my $input,\n+    \"output=s\"  => \\my $output,\n+);\n+\n+if (!$rc or (!-r $varlist or !-r $input)) {\n+    print \"$0 --varlist=<varlist> --input=<in> --output=<out>\\n\";\n+    exit 1;\n+}\n+\n+my $vars = read_varlist($varlist);\n+substitute_variables($vars, $input, $output);\n+exit 0;\n+\n+sub read_varlist {\n+    my ($file) = @_;\n+\n+    open my $fh, \"<\", $varlist or die \"cannot open $varlist: $!\";\n+    my %vars;\n+\n+    my ($v, $last_v);\n+    my $in_block = 0;\n+    while (<$fh>) {\n+        if (/^(\\S+)::/) {\n+            $v = lc $1;\n+            $in_block = 0;\n+            push @{$vars{$v}}, $_;\n+        } elsif (/^$/ && !$in_block) {\n+            if (defined $last_v && !$#{$vars{$last_v}}) {\n+                $vars{$last_v} = $vars{$v};\n+            }\n+            $last_v = $v;\n+        } elsif (defined $v) {\n+            push @{$vars{$v}}, $_;\n+            $in_block = !$in_block if /^--$/;\n+        }\n+    }\n+\n+    close $fh or die \"eh? close failed: $!\";\n+\n+    return \\%vars\n+}\n+\n+sub substitute_variables {\n+    my ($varlist, $in, $out) = @_;\n+\n+    open my $infh, \"<\", $input or die \"Can't open $in for reading: $!\";\n+    open my $outfh, \">\", $output or die \"Can't open $out for reading: $!\";\n+\n+    while (<$infh>) {\n+        if (/^\\@\\@CONFIG\\((\\S+)\\)\\@\\@$/) {\n+            my $v = lc $1;\n+            die \"Key $v not documented\" unless exists $varlist->{$v};\n+            print $outfh @{$varlist->{$v}};\n+            print $outfh \"\\n\";\n+        } else {\n+            print $outfh $_;\n+        }\n+    }\n+\n+    close $infh or die \"closing input failed: $!\";\n+    close $outfh or die \"closing output failed: $!\";\n+\n+    return;\n+}\n-- \n1.7.2.349.gd5452\n"},{"id":"146417","messageId":"a0be121e0b89f010273f3a3de9ad054bcec26d6c.1280169048.git.trast@student.ethz.ch","threadId":"24532","inReplyTo":"cover.1280169048.git.trast@student.ethz.ch","subject":"[PATCH 3-24/24] Documentation: include configuration options in manpages","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2010-07-26T18:48:55Z","receivedAt":"2010-07-26T18:48:55Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"This is a squash of 22 commits.  You can find their originals at\n\n  git://repo.or.cz/git/trast.git t/doc-config-extraction\n---\n Documentation/config-vars.txt      |  107 +++++++++++++++++++++++++++++------\n Documentation/git-add.txt          |    6 +-\n Documentation/git-am.txt           |   18 ++++++\n Documentation/git-archive.txt      |    8 +--\n Documentation/git-branch.txt       |    8 +++\n Documentation/git-checkout.txt     |    8 +++\n Documentation/git-clean.txt        |    6 ++\n Documentation/git-commit.txt       |    7 ++\n Documentation/git-diff.txt         |   12 ++++\n Documentation/git-fetch.txt        |   12 ++++\n Documentation/git-format-patch.txt |   22 ++++++-\n Documentation/git-grep.txt         |    7 ++\n Documentation/git-gui.txt          |   16 +++++\n Documentation/git-log.txt          |   38 ++-----------\n Documentation/git-merge.txt        |   15 +++--\n Documentation/git-pull.txt         |   14 +++++\n Documentation/git-push.txt         |   19 ++++++\n Documentation/git-rebase.txt       |    5 +-\n Documentation/git-shortlog.txt     |    6 ++\n Documentation/git-status.txt       |   18 ++----\n Documentation/git-submodule.txt    |    8 +++\n Documentation/git-tag.txt          |   11 +---\n Documentation/gitk.txt             |    8 +++\n Documentation/merge-config.txt     |   49 ----------------\n 24 files changed, 284 insertions(+), 144 deletions(-)\n delete mode 100644 Documentation/merge-config.txt\n\ndiff --git a/Documentation/config-vars.txt b/Documentation/config-vars.txt\nindex 3fcefe9..0ae80be 100644\n--- a/Documentation/config-vars.txt\n+++ b/Documentation/config-vars.txt\n@@ -426,7 +426,9 @@ core.sparseCheckout::\n add.ignore-errors::\n \tTells 'git add' to continue adding files when some files cannot be\n \tadded due to indexing errors. Equivalent to the '--ignore-errors'\n-\toption of linkgit:git-add[1].\n+\toption\n+ifdef::git-config[of linkgit:git-add[1].]\n+ifndef::git-config[.]\n \n alias.*::\n \tCommand aliases for the linkgit:git[1] command wrapper - e.g.\n@@ -1137,8 +1139,11 @@ i18n.commitEncoding::\n \tporcelains). See e.g. linkgit:git-mailinfo[1]. Defaults to 'utf-8'.\n \n i18n.logOutputEncoding::\n-\tCharacter encoding the commit messages are converted to when\n-\trunning 'git log' and friends.\n+\tEncoding to use when displaying logs.\n+ifdef::git-log[(See \"Discussion\", above.)]\n+ifndef::git-log[See \"Discussion\" in linkgit:git-log[1].]\n+\tDefaults to the value of `i18n.commitEncoding` if set, UTF-8\n+\totherwise.\n \n imap::\n \tThe configuration variables in the 'imap' section are described\n@@ -1175,10 +1180,11 @@ interactive.singlekey::\n \tignored if portable keystroke input is not available.\n \n log.date::\n-\tSet default date-time mode for the log command. Setting log.date\n-\tvalue is similar to using 'git log'\\'s --date option. The value is one of the\n-\tfollowing alternatives: {relative,local,default,iso,rfc,short}.\n-\tSee linkgit:git-log[1].\n+\tDefault date-time mode for the log family. The value must be\n+\tone of {relative,local,default,iso,rfc,short}. Defaults to\n+\t\"default\".  See the `\\--date` option\n+ifdef::git-log[above.]\n+ifndef::git-log[in linkgit:git-log[1].]\n \n log.decorate::\n \tPrint out the ref names of any commits that are shown by the log\n@@ -1188,10 +1194,16 @@ log.decorate::\n \tThis is the same as the log commands '--decorate' option.\n \n log.showroot::\n-\tIf true, the initial commit will be shown as a big creation event.\n-\tThis is equivalent to a diff against an empty tree.\n-\tTools like linkgit:git-log[1] or linkgit:git-whatchanged[1], which\n-\tnormally hide the root commit will now show it. True by default.\n+\tIf enabled, the initial commit will be shown as a big creation\n+\tevent (equivalent to a diff against an empty tree).  Otherwise\n+\tit has an empty diff. Enabled by default.\n+\n+mailinfo.scissors::\n+\tWhen splitting the patch out of an email, remove everything in\n+\tbody before a scissors line, if such a line is found.  A\n+\tscissors line is a line that mainly consists of scissors\n+\t(either \">8\" or \"8<\") and perforation (dash \"-\") marks.\n+\tSee the `\\--scissors` option in linkgit:git-mailinfo.txt[].\n \n mailmap.file::\n \tThe location of an augmenting mailmap file. The default\n@@ -1199,7 +1211,9 @@ mailmap.file::\n \tfirst, then the mailmap file pointed to by this variable.\n \tThe location of the mailmap file may be in a repository\n \tsubdirectory, or somewhere outside of the repository itself.\n+ifdef::git-config[]\n \tSee linkgit:git-shortlog[1] and linkgit:git-blame[1].\n+endif::git-config[]\n \n man.viewer::\n \tSpecify the programs that may be used to display help in the\n@@ -1214,7 +1228,55 @@ man.<tool>.path::\n \tOverride the path for the given tool that may be used to\n \tdisplay help in the 'man' format. See linkgit:git-help[1].\n \n-include::merge-config.txt[]\n+merge.conflictstyle::\n+\tSpecify the style in which conflicted hunks are written out to\n+\tworking tree files upon merge.  The default is \"merge\", which\n+\tshows a `<<<<<<<` conflict marker, changes made by one side,\n+\ta `=======` marker, changes made by the other side, and then\n+\ta `>>>>>>>` marker.  An alternate style, \"diff3\", adds a `|||||||`\n+\tmarker and the original text before the `=======` marker.\n+\n+merge.log::\n+\tWhether to include summaries of merged commits in newly created\n+\tmerge commit messages. False by default.\n+\n+merge.renameLimit::\n+\tThe number of files to consider when performing rename detection\n+\tduring a merge; if not specified, defaults to the value of\n+\tdiff.renameLimit.\n+\n+merge.stat::\n+\tWhether to print the diffstat between ORIG_HEAD and the merge result\n+\tat the end of the merge.  True by default.\n+\n+merge.tool::\n+\tControls which merge resolution program is used by\n+\tlinkgit:git-mergetool[1].  Valid built-in values are: \"kdiff3\",\n+\t\"tkdiff\", \"meld\", \"xxdiff\", \"emerge\", \"vimdiff\", \"gvimdiff\",\n+\t\"diffuse\", \"ecmerge\", \"tortoisemerge\", \"p4merge\", \"araxis\" and\n+\t\"opendiff\".  Any other value is treated is custom merge tool\n+\tand there must be a corresponding mergetool.<tool>.cmd option.\n+\n+merge.verbosity::\n+\tControls the amount of output shown by the recursive merge\n+\tstrategy.  Level 0 outputs nothing except a final error\n+\tmessage if conflicts were detected. Level 1 outputs only\n+\tconflicts, 2 outputs conflicts and file changes.  Level 5 and\n+\tabove outputs debugging information.  The default is level 2.\n+\tCan be overridden by the 'GIT_MERGE_VERBOSITY' environment variable.\n+\n+merge.<driver>.name::\n+\tDefines a human-readable name for a custom low-level\n+\tmerge driver.  See linkgit:gitattributes[5] for details.\n+\n+merge.<driver>.driver::\n+\tDefines the command that implements a custom low-level\n+\tmerge driver.  See linkgit:gitattributes[5] for details.\n+\n+merge.<driver>.recursive::\n+\tNames a low-level merge driver to be used when\n+\tperforming an internal merge between common ancestors.\n+\tSee linkgit:gitattributes[5] for details.\n \n mergetool.<tool>.path::\n \tOverride the path for the given tool.  This is useful in case\n@@ -1271,6 +1333,11 @@ globs.\n The effective value of \"core.notesRef\" (possibly overridden by\n GIT_NOTES_REF) is also implicitly added to the list of refs to be\n displayed.\n+ifdef::git-log[]\n++\n+This setting can be disabled by the `--no-standard-notes` option\n+and supplemented by the `--show-notes` option.\n+endif::git-log[]\n \n notes.rewrite.<command>::\n \tWhen rewriting commits with <command> (currently `amend` or\n@@ -1637,8 +1704,9 @@ tar.umask::\n \tThis variable can be used to restrict the permission bits of\n \ttar archive entries.  The default is 0002, which turns off the\n \tworld write bit.  The special value \"user\" indicates that the\n-\tarchiving user's umask will be used instead.  See umask(2) and\n-\tlinkgit:git-archive[1].\n+\tarchiving user's umask will be used instead.  See umask(2)\n+ifdef::git-config[and linkgit:git-archive[1].]\n+ifndef::git-config[for details.]\n \n transfer.unpackLimit::\n \tWhen `fetch.unpackLimit` or `receive.unpackLimit` are\n@@ -1680,11 +1748,12 @@ user.name::\n \tenvironment variables.  See linkgit:git-commit-tree[1].\n \n user.signingkey::\n-\tIf linkgit:git-tag[1] is not selecting the key you want it to\n-\tautomatically when creating a signed tag, you can override the\n-\tdefault selection with this variable.  This option is passed\n-\tunchanged to gpg's --local-user parameter, so you may specify a key\n-\tusing any method that gpg supports.\n+\tBy default, 'git tag -s' (-s) will use your committer identity\n+\t(of the form \"Your Name <your@email.address>\") to find a key.\n+\tIf you want to use a different default key, you can override\n+\tthe selection with this variable.  The value is passed\n+\tunchanged to gpg's --local-user parameter, so you may specify\n+\ta key using any method that gpg supports.\n \n web.browser::\n \tSpecify a web browser that may be used by some commands.\ndiff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\nindex e22a62f..da1ac09 100644\n--- a/Documentation/git-add.txt\n+++ b/Documentation/git-add.txt\n@@ -148,10 +148,8 @@ subdirectories.\n Configuration\n -------------\n \n-The optional configuration variable `core.excludesfile` indicates a path to a\n-file containing patterns of file names to exclude from git-add, similar to\n-$GIT_DIR/info/exclude.  Patterns in the exclude file are used in addition to\n-those in info/exclude.  See linkgit:gitrepository-layout[5].\n+@@CONFIG(add.ignore-errors)@@\n+@@CONFIG(core.excludesfile)@@\n \n \n EXAMPLES\ndiff --git a/Documentation/git-am.txt b/Documentation/git-am.txt\nindex 9e62f87..3db8e9d 100644\n--- a/Documentation/git-am.txt\n+++ b/Documentation/git-am.txt\n@@ -185,6 +185,24 @@ commits that is more easily fixed by changing the mailbox (e.g.\n errors in the \"From:\" lines).\n \n \n+CONFIGURATION\n+-------------\n+\n+Variables that affect 'git am' itself:\n+\n+@@CONFIG(am.keepcr)@@\n+@@CONFIG(i18n.commitEncoding)@@\n+\n+Variables that affect 'git apply', which is used to apply the patches:\n+\n+@@CONFIG(apply.ignorewhitespace)@@\n+@@CONFIG(apply.whitespace)@@\n+\n+Variables that affect 'git mailinfo':\n+\n+@@CONFIG(mailinfo.scissors)@@\n+\n+\n SEE ALSO\n --------\n linkgit:git-apply[1].\ndiff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt\nindex 8d3e666..01a6bc5 100644\n--- a/Documentation/git-archive.txt\n+++ b/Documentation/git-archive.txt\n@@ -93,12 +93,8 @@ zip\n CONFIGURATION\n -------------\n \n-tar.umask::\n-\tThis variable can be used to restrict the permission bits of\n-\ttar archive entries.  The default is 0002, which turns off the\n-\tworld write bit.  The special value \"user\" indicates that the\n-\tarchiving user's umask will be used instead.  See umask(2) for\n-\tdetails.\n+@@CONFIG(tar.umask)@@\n+\n \n ATTRIBUTES\n ----------\ndiff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\nindex 1940256..08ea917 100644\n--- a/Documentation/git-branch.txt\n+++ b/Documentation/git-branch.txt\n@@ -222,6 +222,14 @@ but different purposes:\n - `--no-merged` is used to find branches which are candidates for merging\n   into HEAD, since those branches are not fully contained by HEAD.\n \n+\n+CONFIGURATION\n+-------------\n+\n+@@CONFIG(branch.autosetupmerge)@@\n+@@CONFIG(branch.autosetuprebase)@@\n+\n+\n SEE ALSO\n --------\n linkgit:git-check-ref-format[1],\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex 1bacd2e..c5d5c03 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -299,6 +299,14 @@ $ git add frotz\n ------------\n \n \n+CONFIGURATION\n+-------------\n+\n+@@CONFIG(branch.autosetupmerge)@@\n+@@CONFIG(branch.autosetuprebase)@@\n+@@CONFIG(merge.conflictstyle)@@\n+\n+\n Author\n ------\n Written by Linus Torvalds <torvalds@osdl.org>\ndiff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt\nindex a81cb6c..eab8de5 100644\n--- a/Documentation/git-clean.txt\n+++ b/Documentation/git-clean.txt\n@@ -56,6 +56,12 @@ OPTIONS\n \teverything from scratch, but keep manually created files.\n \n \n+CONFIGURATION\n+-------------\n+\n+@@CONFIG(clean.requireForce)@@\n+\n+\n Author\n ------\n Written by Pavel Roskin <proski@gnu.org>\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex c28603e..49420cd 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -375,6 +375,13 @@ and `post-commit` hooks.  See linkgit:githooks[5] for more\n information.\n \n \n+CONFIGURATION\n+-------------\n+\n+@@CONFIG(commit.status)@@\n+@@CONFIG(commit.template)@@\n+\n+\n SEE ALSO\n --------\n linkgit:git-add[1],\ndiff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\nindex 08fd409..b7dc1e6 100644\n--- a/Documentation/git-diff.txt\n+++ b/Documentation/git-diff.txt\n@@ -157,6 +157,18 @@ $ git diff -R                          <2>\n rewrites (very expensive).\n <2> Output diff in reverse.\n \n+CONFIGURATION\n+-------------\n+\n+@@CONFIG(diff.autorefreshindex)@@\n+@@CONFIG(diff.external)@@\n+@@CONFIG(diff.mnemonicprefix)@@\n+@@CONFIG(diff.noprefix)@@\n+@@CONFIG(diff.renameLimit)@@\n+@@CONFIG(diff.renames)@@\n+@@CONFIG(diff.suppressBlankEmpty)@@\n+@@CONFIG(diff.wordRegex)@@\n+\n SEE ALSO\n --------\n linkgit:git-difftool[1]::\ndiff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt\nindex 400fe7f..b0c2027 100644\n--- a/Documentation/git-fetch.txt\n+++ b/Documentation/git-fetch.txt\n@@ -76,6 +76,18 @@ The `pu` branch will be updated even if it is does not fast-forward,\n because it is prefixed with a plus sign; `tmp` will not be.\n \n \n+CONFIGURATION\n+-------------\n+\n+@@CONFIG(fetch.unpackLimit)@@\n+@@CONFIG(core.gitProxy)@@\n+@@CONFIG(branch.<name>.remote)@@\n+@@CONFIG(branch.<name>.merge)@@\n+\n+The `remote.<name>.*` configuration options also affect git-fetch as\n+discussed above.\n+\n+\n SEE ALSO\n --------\n linkgit:git-pull[1]\ndiff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt\nindex 4b3f5ba..def364f 100644\n--- a/Documentation/git-format-patch.txt\n+++ b/Documentation/git-format-patch.txt\n@@ -211,10 +211,9 @@ you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`.\n \n CONFIGURATION\n -------------\n-You can specify extra mail header lines to be added to each message,\n-defaults for the subject prefix and file suffix, number patches when\n-outputting more than one patch, add \"To\" or \"Cc:\" headers, configure\n-attachments, and sign off patches with configuration variables.\n+\n+'git format-patch' has a lot of configuration variables.  A short\n+example:\n \n ------------\n [format]\n@@ -226,8 +225,23 @@ attachments, and sign off patches with configuration variables.\n \tcc = <email>\n \tattach [ = mime-boundary-string ]\n \tsignoff = true\n+\tsignature = \"Hello, world!\\n\"\n+\tthread = shallow\n ------------\n \n+The individual variables are as follows:\n+\n+@@CONFIG(format.headers)@@\n+@@CONFIG(format.subjectprefix)@@\n+@@CONFIG(format.suffix)@@\n+@@CONFIG(format.numbered)@@\n+@@CONFIG(format.to)@@\n+@@CONFIG(format.cc)@@\n+@@CONFIG(format.attach)@@\n+@@CONFIG(format.signoff)@@\n+@@CONFIG(format.signature)@@\n+@@CONFIG(format.thread)@@\n+\n \n EXAMPLES\n --------\ndiff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt\nindex 5474dd7..37af4e3 100644\n--- a/Documentation/git-grep.txt\n+++ b/Documentation/git-grep.txt\n@@ -203,6 +203,13 @@ git grep --all-match -e NODE -e Unexpected::\n \tLooks for a line that has `NODE` or `Unexpected` in\n \tfiles that have lines that match both.\n \n+\n+Configuration\n+-------------\n+\n+@@CONFIG(color.grep)@@\n+@@CONFIG(color.grep.<slot>)@@\n+\n Author\n ------\n Originally written by Linus Torvalds <torvalds@osdl.org>, later\ndiff --git a/Documentation/git-gui.txt b/Documentation/git-gui.txt\nindex 2563710..5c53b36 100644\n--- a/Documentation/git-gui.txt\n+++ b/Documentation/git-gui.txt\n@@ -98,6 +98,22 @@ git gui browser maint::\n \tselected in the browser can be viewed with the internal\n \tblame viewer.\n \n+CONFIGURATION\n+-------------\n+\n+@@CONFIG(gui.commitmsgwidth)@@\n+@@CONFIG(gui.diffcontext)@@\n+@@CONFIG(gui.encoding)@@\n+@@CONFIG(gui.matchtrackingbranch)@@\n+@@CONFIG(gui.newbranchtemplate)@@\n+@@CONFIG(gui.pruneduringfetch)@@\n+@@CONFIG(gui.trustmtime)@@\n+@@CONFIG(gui.spellingdictionary)@@\n+@@CONFIG(gui.fastcopyblame)@@\n+@@CONFIG(gui.copyblamethreshold)@@\n+@@CONFIG(gui.blamehistoryctx)@@\n+\n+\n SEE ALSO\n --------\n linkgit:gitk[1]::\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex e970664..77987b3 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -145,38 +145,12 @@ format.pretty::\n \tDefault for the `--format` option.  (See \"PRETTY FORMATS\" above.)\n \tDefaults to \"medium\".\n \n-i18n.logOutputEncoding::\n-\tEncoding to use when displaying logs.  (See \"Discussion\", above.)\n-\tDefaults to the value of `i18n.commitEncoding` if set, UTF-8\n-\totherwise.\n-\n-log.date::\n-\tDefault format for human-readable dates.  (Compare the\n-\t`--date` option.)  Defaults to \"default\", which means to write\n-\tdates like `Sat May 8 19:35:34 2010 -0500`.\n-\n-log.showroot::\n-\tIf `false`, 'git log' and related commands will not treat the\n-\tinitial commit as a big creation event.  Any root commits in\n-\t`git log -p` output would be shown without a diff attached.\n-\tThe default is `true`.\n-\n-mailmap.file::\n-\tSee linkgit:git-shortlog[1].\n-\n-notes.displayRef::\n-\tWhich refs, in addition to the default set by `core.notesRef`\n-\tor 'GIT_NOTES_REF', to read notes from when showing commit\n-\tmessages with the 'log' family of commands.  See\n-\tlinkgit:git-notes[1].\n-+\n-May be an unabbreviated ref name or a glob and may be specified\n-multiple times.  A warning will be issued for refs that do not exist,\n-but a glob that does not match any refs is silently ignored.\n-+\n-This setting can be disabled by the `--no-standard-notes` option,\n-overridden by the 'GIT_NOTES_DISPLAY_REF' environment variable,\n-and supplemented by the `--show-notes` option.\n+@@CONFIG(i18n.logOutputEncoding)@@\n+@@CONFIG(log.date)@@\n+@@CONFIG(log.decorate)@@\n+@@CONFIG(log.showroot)@@\n+@@CONFIG(mailmap.file)@@\n+@@CONFIG(notes.displayRef)@@\n \n Author\n ------\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex 84043cc..41c7e44 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -275,12 +275,17 @@ include::merge-strategies.txt[]\n \n CONFIGURATION\n -------------\n-include::merge-config.txt[]\n \n-branch.<name>.mergeoptions::\n-\tSets default options for merging into branch <name>. The syntax and\n-\tsupported options are the same as those of 'git merge', but option\n-\tvalues containing whitespace characters are currently not supported.\n+@@CONFIG(merge.conflictstyle)@@\n+@@CONFIG(merge.log)@@\n+@@CONFIG(merge.renameLimit)@@\n+@@CONFIG(merge.stat)@@\n+@@CONFIG(merge.tool)@@\n+@@CONFIG(merge.verbosity)@@\n+@@CONFIG(merge.<driver>.name)@@\n+@@CONFIG(merge.<driver>.driver)@@\n+@@CONFIG(merge.<driver>.recursive)@@\n+@@CONFIG(branch.<name>.mergeoptions)@@\n \n SEE ALSO\n --------\ndiff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt\nindex ab4de10..b169964 100644\n--- a/Documentation/git-pull.txt\n+++ b/Documentation/git-pull.txt\n@@ -165,6 +165,20 @@ If you tried a pull which resulted in a complex conflicts and\n would want to start over, you can recover with 'git reset'.\n \n \n+CONFIGURATION\n+-------------\n+\n+Options that affect 'git pull':\n+\n+@@CONFIG(branch.<name>.remote)@@\n+@@CONFIG(branch.<name>.merge)@@\n+@@CONFIG(branch.<name>.rebase)@@\n+\n+Options that affect the underlying 'git fetch' and 'git merge' are\n+documented in linkgit:git-fetch[1] and linkgit:git-merge[1],\n+respectively.\n+\n+\n SEE ALSO\n --------\n linkgit:git-fetch[1], linkgit:git-merge[1], linkgit:git-config[1]\ndiff --git a/Documentation/git-push.txt b/Documentation/git-push.txt\nindex 658ff2f..6c76f74 100644\n--- a/Documentation/git-push.txt\n+++ b/Documentation/git-push.txt\n@@ -406,6 +406,25 @@ Commits A and B would no longer belong to a branch with a symbolic name,\n and so would be unreachable.  As such, these commits would be removed by\n a `git gc` command on the origin repository.\n \n+CONFIGURATION\n+-------------\n+\n+Variables that affect the sending (local) side:\n+\n+@@CONFIG(push.default)@@\n+@@CONFIG(branch.<name>.remote)@@\n+@@CONFIG(branch.<name>.merge)@@\n+\n+Variables that affect the receiving (remote) side:\n+\n+@@CONFIG(receive.autogc)@@\n+@@CONFIG(receive.fsckObjects)@@\n+@@CONFIG(receive.unpackLimit)@@\n+@@CONFIG(receive.denyDeletes)@@\n+@@CONFIG(receive.denyDeleteCurrent)@@\n+@@CONFIG(receive.denyCurrentBranch)@@\n+@@CONFIG(receive.denyNonFastForwards)@@\n+@@CONFIG(receive.updateserverinfo)@@\n \n Author\n ------\ndiff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\nindex be23ad2..41e0604 100644\n--- a/Documentation/git-rebase.txt\n+++ b/Documentation/git-rebase.txt\n@@ -195,9 +195,8 @@ Alternatively, you can undo the 'git rebase' with\n CONFIGURATION\n -------------\n \n-rebase.stat::\n-\tWhether to show a diffstat of what changed upstream since the last\n-\trebase. False by default.\n+@@CONFIG(rebase.stat)@@\n+\n \n OPTIONS\n -------\ndiff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt\nindex bc1ac77..21628fc 100644\n--- a/Documentation/git-shortlog.txt\n+++ b/Documentation/git-shortlog.txt\n@@ -69,6 +69,12 @@ spelled differently.\n include::mailmap.txt[]\n \n \n+CONFIGURATION\n+-------------\n+\n+@@CONFIG(mailmap.file)@@\n+\n+\n Author\n ------\n Written by Jeff Garzik <jgarzik@pobox.com>\ndiff --git a/Documentation/git-status.txt b/Documentation/git-status.txt\nindex 2fd054c..c001d56 100644\n--- a/Documentation/git-status.txt\n+++ b/Documentation/git-status.txt\n@@ -152,19 +152,11 @@ backslash-escaping is performed. Fourth, there is no branch line.\n CONFIGURATION\n -------------\n \n-The command honors `color.status` (or `status.color` -- they\n-mean the same thing and the latter is kept for backward\n-compatibility) and `color.status.<slot>` configuration variables\n-to colorize its output.\n-\n-If the config variable `status.relativePaths` is set to false, then all\n-paths shown are relative to the repository root, not to the current\n-directory.\n-\n-If `status.submodulesummary` is set to a non zero number or true (identical\n-to -1 or an unlimited number), the submodule summary will be enabled for\n-the long format and a summary of commits for modified submodules will be\n-shown (see --summary-limit option of linkgit:git-submodule[1]).\n+@@CONFIG(color.status)@@\n+@@CONFIG(color.status.<slot>)@@\n+@@CONFIG(status.relativePaths)@@\n+@@CONFIG(status.showUntrackedFiles)@@\n+@@CONFIG(status.submodulesummary)@@\n \n SEE ALSO\n --------\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex 1ed331c..40bb60f 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -258,6 +258,14 @@ to each submodule url is \"submodule.$name.url\".  See linkgit:gitmodules[5]\n for details.\n \n \n+CONFIGURATION\n+-------------\n+\n+@@CONFIG(submodule.<name>.path)@@\n+@@CONFIG(submodule.<name>.url)@@\n+@@CONFIG(submodule.<name>.update)@@\n+\n+\n AUTHOR\n ------\n Written by Lars Hjemli <hjemli@gmail.com>\ndiff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt\nindex 31c78a8..8e264e7 100644\n--- a/Documentation/git-tag.txt\n+++ b/Documentation/git-tag.txt\n@@ -95,15 +95,8 @@ OPTIONS\n \n CONFIGURATION\n -------------\n-By default, 'git tag' in sign-with-default mode (-s) will use your\n-committer identity (of the form \"Your Name <your@email.address>\") to\n-find a key.  If you want to use a different default key, you can specify\n-it in the repository configuration as follows:\n-\n--------------------------------------\n-[user]\n-    signingkey = <gpg-key-id>\n--------------------------------------\n+\n+@@CONFIG(user.signingkey)@@\n \n \n DISCUSSION\ndiff --git a/Documentation/gitk.txt b/Documentation/gitk.txt\nindex 05ac1c7..498a5f1 100644\n--- a/Documentation/gitk.txt\n+++ b/Documentation/gitk.txt\n@@ -100,6 +100,14 @@ Files\n Gitk creates the .gitk file in your $HOME directory to store preferences\n such as display options, font, and colors.\n \n+\n+CONFIGURATION\n+-------------\n+\n+@@CONFIG(gui.encoding)@@\n+@@CONFIG(i18n.commitEncoding)@@\n+\n+\n SEE ALSO\n --------\n 'qgit(1)'::\ndiff --git a/Documentation/merge-config.txt b/Documentation/merge-config.txt\ndeleted file mode 100644\nindex a403155..0000000\n--- a/Documentation/merge-config.txt\n+++ /dev/null\n@@ -1,49 +0,0 @@\n-merge.conflictstyle::\n-\tSpecify the style in which conflicted hunks are written out to\n-\tworking tree files upon merge.  The default is \"merge\", which\n-\tshows a `<<<<<<<` conflict marker, changes made by one side,\n-\ta `=======` marker, changes made by the other side, and then\n-\ta `>>>>>>>` marker.  An alternate style, \"diff3\", adds a `|||||||`\n-\tmarker and the original text before the `=======` marker.\n-\n-merge.log::\n-\tWhether to include summaries of merged commits in newly created\n-\tmerge commit messages. False by default.\n-\n-merge.renameLimit::\n-\tThe number of files to consider when performing rename detection\n-\tduring a merge; if not specified, defaults to the value of\n-\tdiff.renameLimit.\n-\n-merge.stat::\n-\tWhether to print the diffstat between ORIG_HEAD and the merge result\n-\tat the end of the merge.  True by default.\n-\n-merge.tool::\n-\tControls which merge resolution program is used by\n-\tlinkgit:git-mergetool[1].  Valid built-in values are: \"kdiff3\",\n-\t\"tkdiff\", \"meld\", \"xxdiff\", \"emerge\", \"vimdiff\", \"gvimdiff\",\n-\t\"diffuse\", \"ecmerge\", \"tortoisemerge\", \"p4merge\", \"araxis\" and\n-\t\"opendiff\".  Any other value is treated is custom merge tool\n-\tand there must be a corresponding mergetool.<tool>.cmd option.\n-\n-merge.verbosity::\n-\tControls the amount of output shown by the recursive merge\n-\tstrategy.  Level 0 outputs nothing except a final error\n-\tmessage if conflicts were detected. Level 1 outputs only\n-\tconflicts, 2 outputs conflicts and file changes.  Level 5 and\n-\tabove outputs debugging information.  The default is level 2.\n-\tCan be overridden by the 'GIT_MERGE_VERBOSITY' environment variable.\n-\n-merge.<driver>.name::\n-\tDefines a human-readable name for a custom low-level\n-\tmerge driver.  See linkgit:gitattributes[5] for details.\n-\n-merge.<driver>.driver::\n-\tDefines the command that implements a custom low-level\n-\tmerge driver.  See linkgit:gitattributes[5] for details.\n-\n-merge.<driver>.recursive::\n-\tNames a low-level merge driver to be used when\n-\tperforming an internal merge between common ancestors.\n-\tSee linkgit:gitattributes[5] for details.\n-- \n1.7.2.349.gd5452\n"},{"id":"146420","messageId":"AANLkTikPg3icj2u7IedfkHStsK4lBI27KAAzUXVFJeyY@mail.gmail.com","threadId":"24532","inReplyTo":"cover.1280169048.git.trast@student.ethz.ch","subject":"Re: [RFC PATCH 0/24] Documentation: refactor config variable descriptions","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2010-07-26T19:05:51Z","receivedAt":"2010-07-26T19:05:51Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"On Mon, Jul 26, 2010 at 18:48, Thomas Rast <trast@student.ethz.ch> wrote:\n> This little series is a bit of a spinoff from\n>\n>  http://article.gmane.org/gmane.comp.version-control.git/146696\n> and\n>  http://article.gmane.org/gmane.comp.version-control.git/145139\n>\n> Since I didn't want to spam the list with 24 RFC emails, I squashed\n> all the manpage-specific patches into one for this submission.  You\n> can find the originals at\n>\n>  git://repo.or.cz/git/trast.git t/doc-config-extraction\n>\n> Judging from its size it's quite possible that\n>\n>  [1/24] Documentation: Move variables from config.txt to separate file\n>\n> won't make it through to the list, either, and -M doesn't help, so you\n> may have to look it up at the above repository too.\n>\n>\n> Work so far:\n>\n> I moved the variables from config.txt and merge-config.txt to a new\n> file, and made a little helper script that expands @@CONFIG(key)@@ in\n> the asciidoc files, driven by the Makefile of course.\n>\n> I then went over the manpages in the \"Main Porcelain Commands\" list of\n> git(1) and either (easy case) added a \"CONFIGURATION\" section with the\n> relevant variables or (hard case) tried to refactor the descriptions\n> so that they are only kept in one place.\n>\n> Ævar kindly rewrote the Perl script in a more readable and error-safe\n> style, which I squashed for this posting.  It's still a separate patch\n> at the above link, too.\n\nThis whole series does some much needed improvement on config documentation.\n\nAcked-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n\n> Further directions:\n>\n> I'm a bit hesitant to go in Peff's suggested direction of outright\n> removing all variables from git-config(1).  I would prefer to both\n> have the short list and group them by some category system, if that\n> happens to work out.  Perhaps the categorized list can eventually be\n> removed once we can verify that all variables are documented in\n> another manpage.\n>\n>\n> Known omissions/todos:\n>\n> * git-gc has an elaborate prose section to the same effect that I\n>  wasn't quite ready to tear apart yet\n>\n> * git-notes has excellent custom descriptions from Jonathan's series\n>  that I didn't want to refactor\n>\n> * The description of format.pretty in git-log.txt is unsatisfactory\n>\n> * check-docs or some other make target should verify that no manpage\n>  links to itself\n\nAll these can be done later.\n"},{"id":"146424","messageId":"20100726193841.GB1043@burratino","threadId":"24532","inReplyTo":"75c9db91f5ab43ebb60cace0d20389462a2ab02c.1280169048.git.trast@student.ethz.ch","subject":"Re: [PATCH 1/24] Documentation: Move variables from config.txt to separate file","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-07-26T19:38:41Z","receivedAt":"2010-07-26T19:38:41Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Thomas Rast wrote:\n\n>  Documentation/config-vars.txt | 1691 ++++++++++++++++++++++++++++++++++++++++\n>  Documentation/config.txt      | 1693 +----------------------------------------\n\nScary.  Does -B -M -C -C -C make it any better?\n"},{"id":"146425","messageId":"20100726195144.GC1043@burratino","threadId":"24532","inReplyTo":"049043aa444288fd9409a3706fe3190fd679cb7d.1280169048.git.trast@student.ethz.ch","subject":"Re: [PATCH 2/24] Documentation: Add variable-substitution script","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-07-26T19:51:44Z","receivedAt":"2010-07-26T19:51:44Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Thomas Rast wrote:\n\n>   ./subst-config.perl <vars> <in> <out>\n> \n> It first reads <vars> for variable-documenting blocks.  A line\n> consisting of '<name>::' starts the block for <name>, except inside a\n> '--' delimited block (which is used to generate sub-lists).  A block\n> extends until the first blank line, which is what asciidoc also looks\n> for.\n> \n> Then it copies from <in> to <out>, substituting lines of the form\n> \n>   @@CONFIG(<name>)@@\n> \n> with the documentation block for <name>.\n\nNeat.  Thanks for picking this up.  \n\nI would like to make the git-config(1) man page more like the command\nlist in git(1) and less like a concatenation of CONFIGURATION\nsections, but regardless, this is a good first step.\n\n> diff --git a/Documentation/config-vars.txt b/Documentation/config-vars.txt\n> index b82fada..3fcefe9 100644\n> --- a/Documentation/config-vars.txt\n> +++ b/Documentation/config-vars.txt\n> @@ -689,6 +689,7 @@ diff.mnemonicprefix::\n>  \tstandard \"a/\" and \"b/\" depending on what is being compared.  When\n>  \tthis configuration is in effect, reverse diff output also swaps\n>  \tthe order of the prefixes:\n> +\n>  diff.noprefix::\n>  \tIf set, 'git diff' does not show any source or destination prefix.\n>  `git diff`;;\n\nDoes this have an effect on the resulting markup?  It looks like an\nindependent syntax fix.\n\n> +++ b/Documentation/subst-config.perl\n> @@ -0,0 +1,74 @@\n[...]\n> +if (!$rc or (!-r $varlist or !-r $input)) {\n> +    print \"$0 --varlist=<varlist> --input=<in> --output=<out>\\n\";\n> +    exit 1;\n> +}\n\nSo the commit message is out of date (the new usage is more clear,\nanyway).\n\n> +%.txt.cv : %.txt subst-config.perl config-vars.txt\n\nThe asciidoc markup is supposed to itself be suitable documentation.\nMaybe eventually we will have to drop that pretence and generate .txt\nfiles at build time.\n\nAcked-by: Jonathan Nieder <jrnieder@gmail.com>\n"},{"id":"146426","messageId":"20100726195552.GA1451@burratino","threadId":"24532","inReplyTo":"a0be121e0b89f010273f3a3de9ad054bcec26d6c.1280169048.git.trast@student.ethz.ch","subject":"Re: [PATCH 3-24/24] Documentation: include configuration options in manpages","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-07-26T19:55:52Z","receivedAt":"2010-07-26T19:55:52Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Thomas Rast wrote:\n\n> +++ b/Documentation/git-add.txt\n> @@ -148,10 +148,8 @@ subdirectories.\n>  Configuration\n>  -------------\n>  \n> -The optional configuration variable `core.excludesfile` indicates a path to a\n> -file containing patterns of file names to exclude from git-add, similar to\n> -$GIT_DIR/info/exclude.  Patterns in the exclude file are used in addition to\n> -those in info/exclude.  See linkgit:gitrepository-layout[5].\n> +@@CONFIG(add.ignore-errors)@@\n> +@@CONFIG(core.excludesfile)@@\n\nHmm, the packrat in me does not like cavalierly throwing away text like\nthis. :)\n\n[...]\n> +++ b/Documentation/git-archive.txt\n> @@ -93,12 +93,8 @@ zip\n>  CONFIGURATION\n>  -------------\n>  \n> -tar.umask::\n> -\tThis variable can be used to restrict the permission bits of\n> -\ttar archive entries.  The default is 0002, which turns off the\n> -\tworld write bit.  The special value \"user\" indicates that the\n> -\tarchiving user's umask will be used instead.  See umask(2) for\n> -\tdetails.\n> +@@CONFIG(tar.umask)@@\n> +\n\nCan this genre of change be automated?\n\n[...]\n> +++ b/Documentation/git-branch.txt\n> @@ -222,6 +222,14 @@ but different purposes:\n>  - `--no-merged` is used to find branches which are candidates for merging\n>    into HEAD, since those branches are not fully contained by HEAD.\n>  \n> +\n> +CONFIGURATION\n> +-------------\n> +\n> +@@CONFIG(branch.autosetupmerge)@@\n> +@@CONFIG(branch.autosetuprebase)@@\n> +\n\nObviously a good thing.\n\nThanks.\nJonathan\n"},{"id":"146428","messageId":"AANLkTikANkubcJ2x5lDLKsKSiOAfMC1QaIoaTaEotN_l@mail.gmail.com","threadId":"24532","inReplyTo":"20100726193841.GB1043@burratino","subject":"Re: [PATCH 1/24] Documentation: Move variables from config.txt to separate file","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2010-07-26T20:18:00Z","receivedAt":"2010-07-26T20:18:00Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"On Mon, Jul 26, 2010 at 19:38, Jonathan Nieder <jrnieder@gmail.com> wrote:\n> Thomas Rast wrote:\n>\n>>  Documentation/config-vars.txt | 1691 ++++++++++++++++++++++++++++++++++++++++\n>>  Documentation/config.txt      | 1693 +----------------------------------------\n>\n> Scary.  Does -B -M -C -C -C make it any better?\n\nIt makes it even scarier:\n\n Documentation/{config.txt => config-vars.txt} |  223 ++--\n Documentation/config.txt                      | 1923 ++-----------------------\n"},{"id":"146429","messageId":"AANLkTinv02tPIUObk6SUpAN2WA7BOK9aU73MWXamZRte@mail.gmail.com","threadId":"24532","inReplyTo":"20100726195144.GC1043@burratino","subject":"Re: [PATCH 2/24] Documentation: Add variable-substitution script","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2010-07-26T20:27:31Z","receivedAt":"2010-07-26T20:27:31Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"On Mon, Jul 26, 2010 at 19:51, Jonathan Nieder <jrnieder@gmail.com> wrote:\n> Thomas Rast wrote:\n\n> I would like to make the git-config(1) man page more like the command\n> list in git(1) and less like a concatenation of CONFIGURATION\n> sections, but regardless, this is a good first step.\n\nYeah, I think git-config(1) shouldn't have the huge listing either,\nbut that's something for a later series to tackle.\n\n>> +++ b/Documentation/subst-config.perl\n>> @@ -0,0 +1,74 @@\n> [...]\n>> +if (!$rc or (!-r $varlist or !-r $input)) {\n>> +    print \"$0 --varlist=<varlist> --input=<in> --output=<out>\\n\";\n>> +    exit 1;\n>> +}\n>\n> So the commit message is out of date (the new usage is more clear,\n> anyway).\n\nThe history makes more sense in Thomas's git repository. I changed the\nusage in a later commit, but that commit was squashed.\n"},{"id":"146433","messageId":"m3wrsikkol.fsf@localhost.localdomain","threadId":"24532","inReplyTo":"049043aa444288fd9409a3706fe3190fd679cb7d.1280169048.git.trast@student.ethz.ch","subject":"Re: [PATCH 2/24] Documentation: Add variable-substitution script","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2010-07-26T21:17:57Z","receivedAt":"2010-07-26T21:17:57Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Thomas Rast <trast@student.ethz.ch> writes:\n\n> diff --git a/Documentation/subst-config.perl b/Documentation/subst-config.perl\n> new file mode 100755\n> index 0000000..a981670\n> --- /dev/null\n> +++ b/Documentation/subst-config.perl\n> @@ -0,0 +1,74 @@\n> +#!/usr/bin/perl\n> +use 5.006002;\n> +use strict;\n> +use warnings;\n> +use Getopt::Long;\n> +\n> +Getopt::Long::Configure qw/ pass_through /;\n> +\n> +my $rc = GetOptions(\n> +    \"varlist=s\" => \\my $varlist,\n> +    \"input=s\"   => \\my $input,\n> +    \"output=s\"  => \\my $output,\n> +);\n> +\n> +if (!$rc or (!-r $varlist or !-r $input)) {\n> +    print \"$0 --varlist=<varlist> --input=<in> --output=<out>\\n\";\n> +    exit 1;\n> +}\n> +\n> +my $vars = read_varlist($varlist);                       # [1]\n> +substitute_variables($vars, $input, $output);            # [2]\n> +exit 0;\n> +\n> +sub read_varlist {\n> +    my ($file) = @_;\n> +\n> +    open my $fh, \"<\", $varlist or die \"cannot open $varlist: $!\";\n\nNITPICK\n\nYou are passing global variable $varlist to this function as parameter\n$file, see place marked [1].  Why don't you use there $file instead of\n$varlist?  Alternatively, why don't you name parameter as $varlist?\n\n> +sub substitute_variables {\n> +    my ($varlist, $in, $out) = @_;\n> +\n> +    open my $infh, \"<\", $input or die \"Can't open $in for reading: $!\";\n> +    open my $outfh, \">\", $output or die \"Can't open $out for reading: $!\";\n\nSame here: $input or $in, $output or $out?\n\n> +\n> +    while (<$infh>) {\n> +        if (/^\\@\\@CONFIG\\((\\S+)\\)\\@\\@$/) {\n> +            my $v = lc $1;\n> +            die \"Key $v not documented\" unless exists $varlist->{$v};\n> +            print $outfh @{$varlist->{$v}};\n> +            print $outfh \"\\n\";\n> +        } else {\n> +            print $outfh $_;\n> +        }\n> +    }\n> +\n> +    close $infh or die \"closing input failed: $!\";\n> +    close $outfh or die \"closing output failed: $!\";\n> +\n> +    return;\n> +}\n\nAlso, could you consitently start error messages (in die \"sth\") with\ncapital letter (upper-case), or with lower-case letter?\n\n-- \nJakub Narebski\nPoland\nShadeHawk on #git\n"},{"id":"146435","messageId":"AANLkTinM8w4MiwdNmiUzLDRvR-NqSxNn0I1avQDt9QtR@mail.gmail.com","threadId":"24532","inReplyTo":"m3wrsikkol.fsf@localhost.localdomain","subject":"Re: [PATCH 2/24] Documentation: Add variable-substitution script","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2010-07-26T21:49:36Z","receivedAt":"2010-07-26T21:49:36Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"On Mon, Jul 26, 2010 at 21:17, Jakub Narebski <jnareb@gmail.com> wrote:\n\nWell caught. Those were on me, here's the fixed up version (in my\nbranch, which Thomas can pull in to his):\n\n#!/usr/bin/perl\nuse 5.006002;\nuse strict;\nuse warnings;\nuse Getopt::Long;\n\nGetopt::Long::Configure qw/ pass_through /;\n\nmy $rc = GetOptions(\n\t\"varlist=s\" => \\my $varlist,\n\t\"input=s\"\t=> \\my $input,\n\t\"output=s\"\t=> \\my $output,\n);\n\nif (!$rc or (!-r $varlist or !-r $input)) {\n\tprint \"$0 --varlist=<varlist> --input=<in> --output=<out>\\n\";\n\texit 1;\n}\n\nmy $vars = read_varlist($varlist);\nsubstitute_variables($vars, $input, $output);\nexit 0;\n\nsub read_varlist {\n\tmy ($file) = @_;\n\n\topen my $fh, \"<\", $file or die \"Can't open $file: $!\";\n\tmy %vars;\n\n\tmy ($v, $last_v);\n\tmy $in_block = 0;\n\twhile (<$fh>) {\n\t\tif (/^(\\S+)::/) {\n\t\t\t$v = lc $1;\n\t\t\t$in_block = 0;\n\t\t\tpush @{$vars{$v}}, $_;\n\t\t} elsif (/^$/ && !$in_block) {\n\t\t\tif (defined $last_v && !$#{$vars{$last_v}}) {\n\t\t\t\t$vars{$last_v} = $vars{$v};\n\t\t\t}\n\t\t\t$last_v = $v;\n\t\t} elsif (defined $v) {\n\t\t\tpush @{$vars{$v}}, $_;\n\t\t\t$in_block = !$in_block if /^--$/;\n\t\t}\n\t}\n\n\tclose $fh or die \"Closing $file failed: $!\";\n\n\treturn \\%vars\n}\n\nsub substitute_variables {\n\tmy ($varlist, $in, $out) = @_;\n\n\topen my $infh, \"<\", $in or die \"Can't open $in: $!\";\n\topen my $outfh, \">\", $out or die \"Can't open $out: $!\";\n\n\twhile (<$infh>) {\n\t\tif (/^\\@\\@CONFIG\\((\\S+)\\)\\@\\@$/) {\n\t\t\tmy $v = lc $1;\n\t\t\tdie \"Key $v not documented\" unless exists $varlist->{$v};\n\t\t\tprint $outfh @{$varlist->{$v}};\n\t\t\tprint $outfh \"\\n\";\n\t\t} else {\n\t\t\tprint $outfh $_;\n\t\t}\n\t}\n\n\tclose $infh or die \"Closing $in failed: $!\";\n\tclose $outfh or die \"Closing $out failed: $!\";\n\n\treturn;\n}\n"},{"id":"146436","messageId":"AANLkTinxEFxOcTeDTBz6fSxAGaqSlHgq0dQvrYYgWH78@mail.gmail.com","threadId":"24532","inReplyTo":"cover.1280169048.git.trast@student.ethz.ch","subject":"Re: [RFC PATCH 0/24] Documentation: refactor config variable descriptions","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2010-07-26T22:25:32Z","receivedAt":"2010-07-26T22:25:32Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"On Mon, Jul 26, 2010 at 18:48, Thomas Rast <trast@student.ethz.ch> wrote:\n> This little series is a bit of a spinoff from\n\nHere are some minor but needed fixups (also in my branch at\nhttp://github.com/avar/git/compare/t/doc-config-extraction)\n\nFrom 522a0e384c1e8b29339aecb8cbf0cccdf42ce3ce Mon Sep 17 00:00:00 2001\nFrom: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= <avarab@gmail.com>\nDate: Mon, 26 Jul 2010 21:56:30 +0000\nSubject: [PATCH 1/2] gitignore: Add *.cv files made by var substitution script\nMIME-Version: 1.0\nContent-Type: text/plain; charset=UTF-8\nContent-Transfer-Encoding: 8bit\n\nIgnore the *.cv files being generated as of the \"Documentation: Add\nvariable-substitution script\" commit.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/.gitignore |    1 +\n 1 files changed, 1 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/.gitignore b/Documentation/.gitignore\nindex 1c3a9fe..623f1d1 100644\n--- a/Documentation/.gitignore\n+++ b/Documentation/.gitignore\n@@ -3,6 +3,7 @@\n *.[1-8]\n *.made\n *.texi\n+*.cv\n git.info\n gitman.info\n howto-index.txt\n-- \n1.7.1\n\n\nFrom 2cdb7349fd65b246cdd01cfcd7444ed3c5e6120b Mon Sep 17 00:00:00 2001\nFrom: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= <avarab@gmail.com>\nDate: Mon, 26 Jul 2010 22:20:48 +0000\nSubject: [PATCH 2/2] Documentation/Makefile: Specify -f user-manual.conf\nMIME-Version: 1.0\nContent-Type: text/plain; charset=UTF-8\nContent-Transfer-Encoding: 8bit\n\nThe user-manual.xml target was broken in the \"Add\nvariable-substitution script\" commit.\n\nIt broke because asciidoc(1) will implicitly search a configuration\nfile alongsite the .txt file it's generating, but that didn't work\nwith the preprocessed .txt.cv file (which would need a\nuser-manual.txt.conf file)\n\nFix that by specifying the path to the config file explicitly like the\nother asciidoc invocations do.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/Makefile |    3 ++-\n 1 files changed, 2 insertions(+), 1 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex c20d580..8b1e797 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -269,7 +269,8 @@ manpage-base-url.xsl: manpage-base-url.xsl.in\n\n user-manual.xml: user-manual.txt.cv user-manual.conf\n                  $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n-                 $(ASCIIDOC) $(ASCIIDOC_EXTRA) -b docbook -d book -o\n$@+ $< && \\\n+                 $(ASCIIDOC) $(ASCIIDOC_EXTRA) -b docbook -d book -f\nuser-manual.conf \\\n+                             -o $@+ $< && \\\n                              mv $@+ $@\n\n technical/api-index.txt: technical/api-index-skel.txt \\\n-- \n1.7.1\n"},{"id":"146453","messageId":"AANLkTi=Ykc1UQDo_dqUxGmmPKRunRbpqd2qfpetEC7p1@mail.gmail.com","threadId":"24532","inReplyTo":"AANLkTikANkubcJ2x5lDLKsKSiOAfMC1QaIoaTaEotN_l@mail.gmail.com","subject":"Re: [PATCH 1/24] Documentation: Move variables from config.txt to separate file","fromName":"Sverre Rabbelier","fromEmail":"srabbelier@gmail.com","sentAt":"2010-07-27T06:48:17Z","receivedAt":"2010-07-27T06:48:17Z","isPatch":true,"sender":{"key":"srabbelier@gmail.com","avatar":"https://avatars.githubusercontent.com/u/3098?v=4"},"body":"Heya,\n\nOn Mon, Jul 26, 2010 at 15:18, Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote:\n> On Mon, Jul 26, 2010 at 19:38, Jonathan Nieder <jrnieder@gmail.com> wrote:\n>> Scary.  Does -B -M -C -C -C make it any better?\n>\n> It makes it even scarier:\n\nSo, should we somehow allow the user to tell us that yes, really, we\nwant to treat these two files as a move for the purpose of generating\na patch diff?\n\n-- \nCheers,\n\nSverre Rabbelier\n"},{"id":"146644","messageId":"7vtynj4j1q.fsf@alter.siamese.dyndns.org","threadId":"24532","inReplyTo":"AANLkTikANkubcJ2x5lDLKsKSiOAfMC1QaIoaTaEotN_l@mail.gmail.com","subject":"Re: [PATCH 1/24] Documentation: Move variables from config.txt to separate file","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-07-28T17:23:29Z","receivedAt":"2010-07-28T17:23:29Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:\n\n> On Mon, Jul 26, 2010 at 19:38, Jonathan Nieder <jrnieder@gmail.com> wrote:\n>> Thomas Rast wrote:\n>>\n>>>  Documentation/config-vars.txt | 1691 ++++++++++++++++++++++++++++++++++++++++\n>>>  Documentation/config.txt      | 1693 +----------------------------------------\n>>\n>> Scary.  Does -B -M -C -C -C make it any better?\n>\n> It makes it even scarier:\n>\n>  Documentation/{config.txt => config-vars.txt} |  223 ++--\n>  Documentation/config.txt                      | 1923 ++-----------------------\n\nIs it scary?\n\nIf bulk of config.txt has been moved to config-vars.txt, but either lines\nthe moved to config-vars.txt have further edits or more lines have been\nadded to the file, while the remainder of config.txt had some other\nchanges, the above two is more or less exactly what I would expect to see.\n"}]}