Documentation: refactor config variable descriptions
cover Documentation: refactor config variable descriptions
This little series is a bit of a spinoff from
http://article.gmane.org/gmane.comp.version-control.git/146696
and
http://article.gmane.org/gmane.comp.version-control.git/145139
Since I didn't want to spam the list with 24 RFC emails, I squashed all the manpage-specific patches into one for this submission. You can find the originals at
git://repo.or.cz/git/trast.git t/doc-config-extraction
Judging from its size it's quite possible that
[1/24] Documentation: Move variables from config.txt to separate file
won't make it through to the list, either, and -M doesn't help, so you may have to look it up at the above repository too.
Work so far:
I moved the variables from config.txt and merge-config.txt to a new file, and made a little helper script that expands @@CONFIG(key)@@ in the asciidoc files, driven by the Makefile of course.
I then went over the manpages in the "Main Porcelain Commands" list of git(1) and either (easy case) added a "CONFIGURATION" section with the relevant variables or (hard case) tried to refactor the descriptions so that they are only kept in one place.
Ævar kindly rewrote the Perl script in a more readable and error-safe style, which I squashed for this posting. It's still a separate patch at the above link, too.
Further directions:
I'm a bit hesitant to go in Peff's suggested direction of outright removing all variables from git-config(1). I would prefer to both have the short list and group them by some category system, if that happens to work out. Perhaps the categorized list can eventually be removed once we can verify that all variables are documented in another manpage.
Known omissions/todos:
* git-gc has an elaborate prose section to the same effect that I wasn't quite ready to tear apart yet
* git-notes has excellent custom descriptions from Jonathan's series that I didn't want to refactor
* The description of format.pretty in git-log.txt is unsatisfactory
* check-docs or some other make target should verify that no manpage links to itself
Thomas Rast (3):
Documentation: Move variables from config.txt to separate file
Documentation: Add variable-substitution script
Documentation: include configuration options in manpages
Documentation/Makefile | 14 +- Documentation/config-vars.txt | 1761 ++++++++++++++++++++++++++++++++++++ Documentation/config.txt | 1693 +---------------------------------- Documentation/git-add.txt | 6 +- Documentation/git-am.txt | 18 + Documentation/git-archive.txt | 8 +- Documentation/git-branch.txt | 8 + Documentation/git-checkout.txt | 8 + Documentation/git-clean.txt | 6 + Documentation/git-commit.txt | 7 + Documentation/git-diff.txt | 12 + Documentation/git-fetch.txt | 12 + Documentation/git-format-patch.txt | 22 +- Documentation/git-grep.txt | 7 + Documentation/git-gui.txt | 16 + Documentation/git-log.txt | 38 +- Documentation/git-merge.txt | 15 +- Documentation/git-pull.txt | 14 + Documentation/git-push.txt | 19 + Documentation/git-rebase.txt | 5 +- Documentation/git-shortlog.txt | 6 + Documentation/git-status.txt | 18 +- Documentation/git-submodule.txt | 8 + Documentation/git-tag.txt | 11 +- Documentation/gitk.txt | 8 + Documentation/merge-config.txt | 49 - Documentation/subst-config.perl | 74 ++ 27 files changed, 2042 insertions(+), 1821 deletions(-) create mode 100644 Documentation/config-vars.txt delete mode 100644 Documentation/merge-config.txt create mode 100755 Documentation/subst-config.perl
Signature · 1 line
1.7.2.349.gd5452
PATCH 2/24 Documentation: Add variable-substitution script
The new subst-config.perl is run by the Makefile as
./subst-config.perl <vars> <in> <out>
It first reads <vars> for variable-documenting blocks. A line consisting of '<name>::' starts the block for <name>, except inside a '--' delimited block (which is used to generate sub-lists). A block extends until the first blank line, which is what asciidoc also looks for.
Then it copies from <in> to <out>, substituting lines of the form
@@CONFIG(<name>)@@
with the documentation block for <name>.
Ævar kindly implemented the following, squashed into this patch:
- Print a usage message when argument prerequisites aren't met
- Use Getopt::Long instead of manually looking at @ARGV
- use warnings, not -w
- Split the parsing & substituting functionality into subroutines
--- Documentation/Makefile | 14 +++++--- Documentation/config-vars.txt | 1 + Documentation/subst-config.perl | 74 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 84 insertions(+), 5 deletions(-) create mode 100755 Documentation/subst-config.perl
Documentation/Makefile +9 -5
@@ -239,12 +239,16 @@ cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT) clean: $(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7 $(RM) *.texi *.texi+ *.texi++ git.info gitman.info + $(RM) *.txt.cv $(RM) howto-index.txt howto/*.html doc.dep $(RM) technical/api-*.html technical/api-index.txt $(RM) $(cmds_txt) *.made $(RM) manpage-base-url.xsl -$(MAN_HTML): %.html : %.txt +%.txt.cv : %.txt subst-config.perl config-vars.txt + $(QUIET_GEN) ./subst-config.perl --varlist=config-vars.txt --input=$< --output=$@ + +$(patsubst %.txt,%.txt.cv,$(MAN_HTML)): %.html : %.txt.cv $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ $(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf \ $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \
@@ -257,13 +261,13 @@ manpage-base-url.xsl: manpage-base-url.xsl.in $(QUIET_XMLTO)$(RM) $@ && \ xmlto -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< -%.xml : %.txt +%.xml : %.txt.cv $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ $(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \ $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \ mv $@+ $@ -user-manual.xml: user-manual.txt user-manual.conf +user-manual.xml: user-manual.txt.cv user-manual.conf $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ $(ASCIIDOC) $(ASCIIDOC_EXTRA) -b docbook -d book -o $@+ $< && \ mv $@+ $@
@@ -320,8 +324,8 @@ howto-index.txt: howto-index.sh $(wildcard howto/*.txt) '$(SHELL_PATH_SQ)' ./howto-index.sh $(wildcard howto/*.txt) >$@+ && \ mv $@+ $@ -$(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt - $(QUIET_ASCIIDOC)$(ASCIIDOC) $(ASCIIDOC_EXTRA) -b xhtml11 $*.txt +$(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt.cv + $(QUIET_ASCIIDOC)$(ASCIIDOC) $(ASCIIDOC_EXTRA) -b xhtml11 $*.txt.cv WEBDOC_DEST = /pub/software/scm/git/docs
Documentation/config-vars.txt +1 -0
@@ -689,6 +689,7 @@ diff.mnemonicprefix:: standard "a/" and "b/" depending on what is being compared. When this configuration is in effect, reverse diff output also swaps the order of the prefixes: + diff.noprefix:: If set, 'git diff' does not show any source or destination prefix. `git diff`;;
Documentation/subst-config.perl new file +74 -0
74 lines not on this page · raw message
Signature · 1 line
1.7.2.349.gd5452
Re: [PATCH 2/24] Documentation: Add variable-substitution script
Quoted 8 lines · Thomas Rast
./subst-config.perl <vars> <in> <out>
It first reads <vars> for variable-documenting blocks. A line consisting of '<name>::' starts the block for <name>, except inside a '--' delimited block (which is used to generate sub-lists). A block extends until the first blank line, which is what asciidoc also looks for.
Quoted 5 lines
Then it copies from <in> to <out>, substituting lines of the form
@@CONFIG(<name>)@@
with the documentation block for <name>.
Neat. Thanks for picking this up.
I would like to make the git-config(1) man page more like the command list in git(1) and less like a concatenation of CONFIGURATION sections, but regardless, this is a good first step.
Documentation/config-vars.txt diff.mnemonicprefix:: · line 695
Quoted 12 lines
Documentation/config-vars.txt +1
-0@@ -689,6 +689,7 @@ diff.mnemonicprefix:: standard "a/" and "b/" depending on what is being compared. When this configuration is in effect, reverse diff output also swaps the order of the prefixes: + diff.noprefix:: If set, 'git diff' does not show any source or destination prefix. `git diff`;;
Does this have an effect on the resulting markup? It looks like an independent syntax fix.
Quoted 2 lines
+++ b/Documentation/subst-config.perl
Documentation/config-vars.txt +0
-0@@ -0,0 +1,74 @@
[...]
Documentation/config-vars.txt
Quoted 4 lines
Documentation/config-vars.txt +4
-0+if (!$rc or (!-r $varlist or !-r $input)) { + print "$0 --varlist=<varlist> --input=<in> --output=<out>\n"; + exit 1; +}
So the commit message is out of date (the new usage is more clear, anyway).
Quoted 1 line
+%.txt.cv : %.txt subst-config.perl config-vars.txt
The asciidoc markup is supposed to itself be suitable documentation. Maybe eventually we will have to drop that pretence and generate .txt files at build time.
Re: [PATCH 2/24] Documentation: Add variable-substitution script
Quoted 5 lines · Jonathan Nieder
Thomas Rast wrote:
I would like to make the git-config(1) man page more like the command list in git(1) and less like a concatenation of CONFIGURATION sections, but regardless, this is a good first step.
Yeah, I think git-config(1) shouldn't have the huge listing either, but that's something for a later series to tackle.
Quoted 10 lines
Quoted 2 lines
+++ b/Documentation/subst-config.perl
(quoted diff) +0
-0@@ -0,0 +1,74 @@[...]
Documentation/subst-config.perl line 18
Quoted 4 lines
Documentation/subst-config.perl new file +4
-0+if (!$rc or (!-r $varlist or !-r $input)) { + print "$0 --varlist=<varlist> --input=<in> --output=<out>\n"; + exit 1; +}So the commit message is out of date (the new usage is more clear, anyway).
The history makes more sense in Thomas's git repository. I changed the usage in a later commit, but that commit was squashed.
Re: [PATCH 2/24] Documentation: Add variable-substitution script
In reply to Thomas RastQuoted 23 lines · Thomas Rast
Documentation/subst-config.perl new file +17
-0@@ -0,0 +1,74 @@ +#!/usr/bin/perl +use 5.006002; +use strict; +use warnings; +use Getopt::Long; + +Getopt::Long::Configure qw/ pass_through /; + +my $rc = GetOptions( + "varlist=s" => \my $varlist, + "input=s" => \my $input, + "output=s" => \my $output, +); + +if (!$rc or (!-r $varlist or !-r $input)) { + print "$0 --varlist=<varlist> --input=<in> --output=<out>\n"; + exit 1;
Documentation/subst-config.perl line 27
Quoted 10 lines
Documentation/subst-config.perl new file +10
-0+} + +my $vars = read_varlist($varlist); # [1] +substitute_variables($vars, $input, $output); # [2] +exit 0; + +sub read_varlist { + my ($file) = @_; + + open my $fh, "<", $varlist or die "cannot open $varlist: $!";
NITPICK
You are passing global variable $varlist to this function as parameter $file, see place marked [1]. Why don't you use there $file instead of $varlist? Alternatively, why don't you name parameter as $varlist?
Documentation/subst-config.perl line 57
Quoted 5 lines
Documentation/subst-config.perl new file +5
-0+sub substitute_variables { + my ($varlist, $in, $out) = @_; + + open my $infh, "<", $input or die "Can't open $in for reading: $!"; + open my $outfh, ">", $output or die "Can't open $out for reading: $!";
Same here: $input or $in, $output or $out?
Quoted 7 lines
Documentation/subst-config.perl new file +7
-0+ + while (<$infh>) { + if (/^\@\@CONFIG\((\S+)\)\@\@$/) { + my $v = lc $1; + die "Key $v not documented" unless exists $varlist->{$v}; + print $outfh @{$varlist->{$v}}; + print $outfh "\n";
Documentation/subst-config.perl line 74
Quoted 10 lines
Documentation/subst-config.perl new file +10
-0+ } else { + print $outfh $_; + } + } + + close $infh or die "closing input failed: $!"; + close $outfh or die "closing output failed: $!"; + + return; +}
Also, could you consitently start error messages (in die "sth") with capital letter (upper-case), or with lower-case letter?
Signature · 3 lines
Jakub Narebski Poland ShadeHawk on #git
Re: [PATCH 2/24] Documentation: Add variable-substitution script
On Mon, Jul 26, 2010 at 21:17, Jakub Narebski <[email protected]> wrote:
Well caught. Those were on me, here's the fixed up version (in my branch, which Thomas can pull in to his):
#!/usr/bin/perl
use 5.006002;
use strict;
use warnings;
use Getopt::Long;
Getopt::Long::Configure qw/ pass_through /;
my $rc = GetOptions(
"varlist=s" => \my $varlist, "input=s" => \my $input, "output=s" => \my $output,
);
if (!$rc or (!-r $varlist or !-r $input)) {
print "$0 --varlist=<varlist> --input=<in> --output=<out>\n";
exit 1;
}my $vars = read_varlist($varlist);substitute_variables($vars, $input, $output);
exit 0;
sub read_varlist {
my ($file) = @_;
open my $fh, "<", $file or die "Can't open $file: $!";
my %vars;
my ($v, $last_v);
my $in_block = 0;
while (<$fh>) {
if (/^(\S+)::/) {
$v = lc $1;
$in_block = 0;
push @{$vars{$v}}, $_;
} elsif (/^$/ && !$in_block) {
if (defined $last_v && !$#{$vars{$last_v}}) {
$vars{$last_v} = $vars{$v};
}
$last_v = $v;
} elsif (defined $v) {
push @{$vars{$v}}, $_;
$in_block = !$in_block if /^--$/;
}
}
close $fh or die "Closing $file failed: $!";
return \%vars
}sub substitute_variables {
my ($varlist, $in, $out) = @_;
open my $infh, "<", $in or die "Can't open $in: $!";
open my $outfh, ">", $out or die "Can't open $out: $!";
while (<$infh>) {
if (/^\@\@CONFIG\((\S+)\)\@\@$/) {
my $v = lc $1;
die "Key $v not documented" unless exists $varlist->{$v};
print $outfh @{$varlist->{$v}};
print $outfh "\n";
} else {
print $outfh $_;
}
}
close $infh or die "Closing $in failed: $!";
close $outfh or die "Closing $out failed: $!";
return;
}A message that is not in the archive (sent off-list or not yet received): 75c9db91f5ab43ebb60cace0d20389462a2ab02c.1280169048.git.trast@student.ethz.ch
Re: [PATCH 1/24] Documentation: Move variables from config.txt to separate file
Quoted 2 lines · Thomas Rast
Documentation/config-vars.txt | 1691 ++++++++++++++++++++++++++++++++++++++++ Documentation/config.txt | 1693 +----------------------------------------
Scary. Does -B -M -C -C -C make it any better?
Re: [PATCH 1/24] Documentation: Move variables from config.txt to separate file
Quoted 6 lines · Jonathan Nieder
Quoted 2 lines · Thomas Rast
Documentation/config-vars.txt | 1691 ++++++++++++++++++++++++++++++++++++++++
Documentation/config.txt| 1693 +----------------------------------------Scary. Does -B -M -C -C -C make it any better?
It makes it even scarier:
Documentation/{config.txt => config-vars.txt} | 223 ++--
Documentation/config.txt | 1923 ++-----------------------Re: [PATCH 1/24] Documentation: Move variables from config.txt to separate file
Heya,
Quoted 4 lines · Ævar Arnfjörð Bjarmason
Quoted 1 line · Jonathan Nieder
Scary. Does -B -M -C -C -C make it any better?
It makes it even scarier:
So, should we somehow allow the user to tell us that yes, really, we want to treat these two files as a move for the purpose of generating a patch diff?
Signature · 3 lines
Cheers, Sverre Rabbelier
Re: [PATCH 1/24] Documentation: Move variables from config.txt to separate file
In reply to Ævar Arnfjörð BjarmasonQuoted 6 lines · Ævar Arnfjörð Bjarmason
Quoted 5 lines · Jonathan Nieder
Quoted 2 lines · Thomas Rast
Documentation/config-vars.txt | 1691 ++++++++++++++++++++++++++++++++++++++++
Documentation/config.txt | 1693 +----------------------------------------
Quoted 6 lines
Quoted 1 line
Scary. Does -B -M -C -C -C make it any better?
It makes it even scarier:
Documentation/{config.txt => config-vars.txt} | 223 ++-- Documentation/config.txt | 1923 ++-----------------------
Is it scary?
If bulk of config.txt has been moved to config-vars.txt, but either lines the moved to config-vars.txt have further edits or more lines have been added to the file, while the remainder of config.txt had some other changes, the above two is more or less exactly what I would expect to see.
Quoted 26 lines · Thomas Rast
This little series is a bit of a spinoff from
http://article.gmane.org/gmane.comp.version-control.git/146696
and
http://article.gmane.org/gmane.comp.version-control.git/145139Since I didn't want to spam the list with 24 RFC emails, I squashed all the manpage-specific patches into one for this submission. You can find the originals at
git://repo.or.cz/git/trast.git t/doc-config-extraction
Judging from its size it's quite possible that
[1/24] Documentation: Move variables from config.txt to separate file
won't make it through to the list, either, and -M doesn't help, so you may have to look it up at the above repository too.
Work so far:
I moved the variables from config.txt and merge-config.txt to a new file, and made a little helper script that expands @@CONFIG(key)@@ in the asciidoc files, driven by the
Makefileof course.
Quoted 8 lines
I then went over the manpages in the "Main Porcelain Commands" list of git(1) and either (easy case) added a "CONFIGURATION" section with the relevant variables or (hard case) tried to refactor the descriptions so that they are only kept in one place.
Ævar kindly rewrote the Perl script in a more readable and error-safe style, which I squashed for this posting. It's still a separate patch at the above link, too.
This whole series does some much needed improvement on config documentation.
Quoted 15 lines
Further directions:
I'm a bit hesitant to go in Peff's suggested direction of outright removing all variables from git-config(1). I would prefer to both have the short list and group them by some category system, if that happens to work out. Perhaps the categorized list can eventually be removed once we can verify that all variables are documented in another manpage.
Known omissions/todos:
* git-gc has an elaborate prose section to the same effect that I wasn't quite ready to tear apart yet
Quoted 7 lines
* git-notes has excellent custom descriptions from Jonathan's series that I didn't want to refactor
* The description of format.pretty in git-log.txt is unsatisfactory
* check-docs or some other make target should verify that no manpage links to itself
All these can be done later.
Quoted 1 line · Thomas Rast
This little series is a bit of a spinoff from
Here are some minor but needed fixups (also in my branch at
http://github.com/avar/git/compare/t/doc-config-extraction)
From 522a0e384c1e8b29339aecb8cbf0cccdf42ce3ce Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= <[email protected]>
Date: Mon, 26 Jul 2010 21:56:30 +0000
Subject: [PATCH 1/2] gitignore: Add *.cv files made by var substitution script
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Ignore the *.cv files being generated as of the "Documentation: Add variable-substitution script" commit.
--- Documentation/.gitignore | 1 + 1 files changed, 1 insertions(+), 0 deletions(-)
Documentation/.gitignore +1 -0
@@ -3,6 +3,7 @@ *.[1-8] *.made *.texi +*.cv git.info gitman.info howto-index.txt
Signature · 26 lines
1.7.1 From 2cdb7349fd65b246cdd01cfcd7444ed3c5e6120b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= <[email protected]> Date: Mon, 26 Jul 2010 22:20:48 +0000 Subject: [PATCH 2/2] Documentation/Makefile: Specify -f user-manual.conf MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The user-manual.xml target was broken in the "Add variable-substitution script" commit. It broke because asciidoc(1) will implicitly search a configuration file alongsite the .txt file it's generating, but that didn't work with the preprocessed .txt.cv file (which would need a user-manual.txt.conf file) Fix that by specifying the path to the config file explicitly like the other asciidoc invocations do. Signed-off-by: Ævar Arnfjörð Bjarmason <[email protected]> --- Documentation/Makefile | 3 ++- 1 files changed, 2 insertions(+), 1 deletions(-)
Documentation/Makefile +0 -1
@@ -269,7 +269,8 @@ manpage-base-url.xsl: manpage-base-url.xsl.in user-manual.xml: user-manual.txt.cv user-manual.conf $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ - $(ASCIIDOC) $(ASCIIDOC_EXTRA) -b docbook -d book -o
$@+ $< && \
+ $(ASCIIDOC) $(ASCIIDOC_EXTRA) -b docbook -d book -f
user-manual.conf \
+ -o $@+ $< && \
mv $@+ $@ technical/api-index.txt: technical/api-index-skel.txt \
Signature · 1 line
1.7.1
PATCH 1/1 Documentation: include configuration options in manpages
In reply to Thomas RastThis is a squash of 22 commits. You can find their originals at
git://repo.or.cz/git/trast.git t/doc-config-extraction
--- Documentation/config-vars.txt | 107 +++++++++++++++++++++++++++++------ Documentation/git-add.txt | 6 +- Documentation/git-am.txt | 18 ++++++ Documentation/git-archive.txt | 8 +-- Documentation/git-branch.txt | 8 +++ Documentation/git-checkout.txt | 8 +++ Documentation/git-clean.txt | 6 ++ Documentation/git-commit.txt | 7 ++ Documentation/git-diff.txt | 12 ++++ Documentation/git-fetch.txt | 12 ++++ Documentation/git-format-patch.txt | 22 ++++++- Documentation/git-grep.txt | 7 ++ Documentation/git-gui.txt | 16 +++++ Documentation/git-log.txt | 38 ++----------- Documentation/git-merge.txt | 15 +++-- Documentation/git-pull.txt | 14 +++++ Documentation/git-push.txt | 19 ++++++ Documentation/git-rebase.txt | 5 +- Documentation/git-shortlog.txt | 6 ++ Documentation/git-status.txt | 18 ++---- Documentation/git-submodule.txt | 8 +++ Documentation/git-tag.txt | 11 +--- Documentation/gitk.txt | 8 +++ Documentation/merge-config.txt | 49 ---------------- 24 files changed, 284 insertions(+), 144 deletions(-) delete mode 100644 Documentation/merge-config.txt
Documentation/config-vars.txt +88 -19
@@ -426,7 +426,9 @@ core.sparseCheckout:: add.ignore-errors:: Tells 'git add' to continue adding files when some files cannot be added due to indexing errors. Equivalent to the '--ignore-errors' - option of linkgit:git-add[1]. + option +ifdef::git-config[of linkgit:git-add[1].] +ifndef::git-config[.] alias.*:: Command aliases for the linkgit:git[1] command wrapper - e.g.
@@ -1137,8 +1139,11 @@ i18n.commitEncoding:: porcelains). See e.g. linkgit:git-mailinfo[1]. Defaults to 'utf-8'. i18n.logOutputEncoding:: - Character encoding the commit messages are converted to when - running 'git log' and friends. + Encoding to use when displaying logs. +ifdef::git-log[(See "Discussion", above.)] +ifndef::git-log[See "Discussion" in linkgit:git-log[1].] + Defaults to the value of `i18n.commitEncoding` if set, UTF-8 + otherwise. imap:: The configuration variables in the 'imap' section are described
@@ -1175,10 +1180,11 @@ interactive.singlekey:: ignored if portable keystroke input is not available. log.date:: - Set default date-time mode for the log command. Setting log.date - value is similar to using 'git log'\'s --date option. The value is one of the - following alternatives: {relative,local,default,iso,rfc,short}. - See linkgit:git-log[1]. + Default date-time mode for the log family. The value must be + one of {relative,local,default,iso,rfc,short}. Defaults to + "default". See the `\--date` option +ifdef::git-log[above.] +ifndef::git-log[in linkgit:git-log[1].] log.decorate:: Print out the ref names of any commits that are shown by the log
@@ -1188,10 +1194,16 @@ log.decorate:: This is the same as the log commands '--decorate' option. log.showroot:: - If true, the initial commit will be shown as a big creation event. - This is equivalent to a diff against an empty tree. - Tools like linkgit:git-log[1] or linkgit:git-whatchanged[1], which - normally hide the root commit will now show it. True by default. + If enabled, the initial commit will be shown as a big creation + event (equivalent to a diff against an empty tree). Otherwise + it has an empty diff. Enabled by default. + +mailinfo.scissors:: + When splitting the patch out of an email, remove everything in + body before a scissors line, if such a line is found. A + scissors line is a line that mainly consists of scissors + (either ">8" or "8<") and perforation (dash "-") marks. + See the `\--scissors` option in linkgit:git-mailinfo.txt[]. mailmap.file:: The location of an augmenting mailmap file. The default
@@ -1199,7 +1211,9 @@ mailmap.file:: first, then the mailmap file pointed to by this variable. The location of the mailmap file may be in a repository subdirectory, or somewhere outside of the repository itself. +ifdef::git-config[] See linkgit:git-shortlog[1] and linkgit:git-blame[1]. +endif::git-config[] man.viewer:: Specify the programs that may be used to display help in the
@@ -1214,7 +1228,55 @@ man.<tool>.path:: Override the path for the given tool that may be used to display help in the 'man' format. See linkgit:git-help[1]. -include::merge-config.txt[] +merge.conflictstyle:: + Specify the style in which conflicted hunks are written out to + working tree files upon merge. The default is "merge", which + shows a `<<<<<<<` conflict marker, changes made by one side, + a `=======` marker, changes made by the other side, and then + a `>>>>>>>` marker. An alternate style, "diff3", adds a `|||||||` + marker and the original text before the `=======` marker. + +merge.log:: + Whether to include summaries of merged commits in newly created + merge commit messages. False by default. + +merge.renameLimit:: + The number of files to consider when performing rename detection + during a merge; if not specified, defaults to the value of + diff.renameLimit. + +merge.stat:: + Whether to print the diffstat between ORIG_HEAD and the merge result + at the end of the merge. True by default. + +merge.tool:: + Controls which merge resolution program is used by + linkgit:git-mergetool[1]. Valid built-in values are: "kdiff3", + "tkdiff", "meld", "xxdiff", "emerge", "vimdiff", "gvimdiff", + "diffuse", "ecmerge", "tortoisemerge", "p4merge", "araxis" and + "opendiff". Any other value is treated is custom merge tool + and there must be a corresponding mergetool.<tool>.cmd option. + +merge.verbosity:: + Controls the amount of output shown by the recursive merge + strategy. Level 0 outputs nothing except a final error + message if conflicts were detected. Level 1 outputs only + conflicts, 2 outputs conflicts and file changes. Level 5 and + above outputs debugging information. The default is level 2. + Can be overridden by the 'GIT_MERGE_VERBOSITY' environment variable. + +merge.<driver>.name:: + Defines a human-readable name for a custom low-level + merge driver. See linkgit:gitattributes[5] for details. + +merge.<driver>.driver:: + Defines the command that implements a custom low-level + merge driver. See linkgit:gitattributes[5] for details. + +merge.<driver>.recursive:: + Names a low-level merge driver to be used when + performing an internal merge between common ancestors. + See linkgit:gitattributes[5] for details. mergetool.<tool>.path:: Override the path for the given tool. This is useful in case
@@ -1271,6 +1333,11 @@ globs. The effective value of "core.notesRef" (possibly overridden by GIT_NOTES_REF) is also implicitly added to the list of refs to be displayed. +ifdef::git-log[] ++ +This setting can be disabled by the `--no-standard-notes` option +and supplemented by the `--show-notes` option. +endif::git-log[] notes.rewrite.<command>:: When rewriting commits with <command> (currently `amend` or
@@ -1637,8 +1704,9 @@ tar.umask:: This variable can be used to restrict the permission bits of tar archive entries. The default is 0002, which turns off the world write bit. The special value "user" indicates that the - archiving user's umask will be used instead. See umask(2) and - linkgit:git-archive[1]. + archiving user's umask will be used instead. See umask(2) +ifdef::git-config[and linkgit:git-archive[1].] +ifndef::git-config[for details.] transfer.unpackLimit:: When `fetch.unpackLimit` or `receive.unpackLimit` are
@@ -1680,11 +1748,12 @@ user.name:: environment variables. See linkgit:git-commit-tree[1]. user.signingkey:: - If linkgit:git-tag[1] is not selecting the key you want it to - automatically when creating a signed tag, you can override the - default selection with this variable. This option is passed - unchanged to gpg's --local-user parameter, so you may specify a key - using any method that gpg supports. + By default, 'git tag -s' (-s) will use your committer identity + (of the form "Your Name <[email protected]>") to find a key. + If you want to use a different default key, you can override + the selection with this variable. The value is passed + unchanged to gpg's --local-user parameter, so you may specify + a key using any method that gpg supports. web.browser:: Specify a web browser that may be used by some commands.
Documentation/git-add.txt +2 -4
@@ -148,10 +148,8 @@ subdirectories. Configuration ------------- -The optional configuration variable `core.excludesfile` indicates a path to a -file containing patterns of file names to exclude from git-add, similar to -$GIT_DIR/info/exclude. Patterns in the exclude file are used in addition to -those in info/exclude. See linkgit:gitrepository-layout[5]. +@@CONFIG(add.ignore-errors)@@ +@@CONFIG(core.excludesfile)@@ EXAMPLES
Documentation/git-am.txt +18 -0
@@ -185,6 +185,24 @@ commits that is more easily fixed by changing the mailbox (e.g. errors in the "From:" lines). +CONFIGURATION +------------- + +Variables that affect 'git am' itself: + +@@CONFIG(am.keepcr)@@ +@@CONFIG(i18n.commitEncoding)@@ + +Variables that affect 'git apply', which is used to apply the patches: + +@@CONFIG(apply.ignorewhitespace)@@ +@@CONFIG(apply.whitespace)@@ + +Variables that affect 'git mailinfo': + +@@CONFIG(mailinfo.scissors)@@ + + SEE ALSO -------- linkgit:git-apply[1].
Documentation/git-archive.txt +2 -6
@@ -93,12 +93,8 @@ zip CONFIGURATION ------------- -tar.umask:: - This variable can be used to restrict the permission bits of - tar archive entries. The default is 0002, which turns off the - world write bit. The special value "user" indicates that the - archiving user's umask will be used instead. See umask(2) for - details. +@@CONFIG(tar.umask)@@ + ATTRIBUTES ----------
Documentation/git-branch.txt +8 -0
@@ -222,6 +222,14 @@ but different purposes: - `--no-merged` is used to find branches which are candidates for merging into HEAD, since those branches are not fully contained by HEAD. + +CONFIGURATION +------------- + +@@CONFIG(branch.autosetupmerge)@@ +@@CONFIG(branch.autosetuprebase)@@ + + SEE ALSO -------- linkgit:git-check-ref-format[1],
Documentation/git-checkout.txt +8 -0
@@ -299,6 +299,14 @@ $ git add frotz ------------ +CONFIGURATION +------------- + +@@CONFIG(branch.autosetupmerge)@@ +@@CONFIG(branch.autosetuprebase)@@ +@@CONFIG(merge.conflictstyle)@@ + + Author ------ Written by Linus Torvalds <[email protected]>
Documentation/git-clean.txt +6 -0
@@ -56,6 +56,12 @@ OPTIONS everything from scratch, but keep manually created files. +CONFIGURATION +------------- + +@@CONFIG(clean.requireForce)@@ + + Author ------ Written by Pavel Roskin <[email protected]>
Documentation/git-commit.txt +7 -0
@@ -375,6 +375,13 @@ and `post-commit` hooks. See linkgit:githooks[5] for more information. +CONFIGURATION +------------- + +@@CONFIG(commit.status)@@ +@@CONFIG(commit.template)@@ + + SEE ALSO -------- linkgit:git-add[1],
Documentation/git-diff.txt +12 -0
@@ -157,6 +157,18 @@ $ git diff -R <2> rewrites (very expensive). <2> Output diff in reverse. +CONFIGURATION +------------- + +@@CONFIG(diff.autorefreshindex)@@ +@@CONFIG(diff.external)@@ +@@CONFIG(diff.mnemonicprefix)@@ +@@CONFIG(diff.noprefix)@@ +@@CONFIG(diff.renameLimit)@@ +@@CONFIG(diff.renames)@@ +@@CONFIG(diff.suppressBlankEmpty)@@ +@@CONFIG(diff.wordRegex)@@ + SEE ALSO -------- linkgit:git-difftool[1]::
Documentation/git-fetch.txt +12 -0
@@ -76,6 +76,18 @@ The `pu` branch will be updated even if it is does not fast-forward, because it is prefixed with a plus sign; `tmp` will not be. +CONFIGURATION +------------- + +@@CONFIG(fetch.unpackLimit)@@ +@@CONFIG(core.gitProxy)@@ +@@CONFIG(branch.<name>.remote)@@ +@@CONFIG(branch.<name>.merge)@@ + +The `remote.<name>.*` configuration options also affect git-fetch as +discussed above. + + SEE ALSO -------- linkgit:git-pull[1]
Documentation/git-format-patch.txt +18 -4
@@ -211,10 +211,9 @@ you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`. CONFIGURATION ------------- -You can specify extra mail header lines to be added to each message, -defaults for the subject prefix and file suffix, number patches when -outputting more than one patch, add "To" or "Cc:" headers, configure -attachments, and sign off patches with configuration variables. + +'git format-patch' has a lot of configuration variables. A short +example: ------------ [format]
@@ -226,8 +225,23 @@ attachments, and sign off patches with configuration variables. cc = <email> attach [ = mime-boundary-string ] signoff = true + signature = "Hello, world!\n" + thread = shallow ------------ +The individual variables are as follows: + +@@CONFIG(format.headers)@@ +@@CONFIG(format.subjectprefix)@@ +@@CONFIG(format.suffix)@@ +@@CONFIG(format.numbered)@@ +@@CONFIG(format.to)@@ +@@CONFIG(format.cc)@@ +@@CONFIG(format.attach)@@ +@@CONFIG(format.signoff)@@ +@@CONFIG(format.signature)@@ +@@CONFIG(format.thread)@@ + EXAMPLES --------
Documentation/git-grep.txt +7 -0
@@ -203,6 +203,13 @@ git grep --all-match -e NODE -e Unexpected:: Looks for a line that has `NODE` or `Unexpected` in files that have lines that match both. + +Configuration +------------- + +@@CONFIG(color.grep)@@ +@@CONFIG(color.grep.<slot>)@@ + Author ------ Originally written by Linus Torvalds <[email protected]>, later
Documentation/git-gui.txt +16 -0
@@ -98,6 +98,22 @@ git gui browser maint:: selected in the browser can be viewed with the internal blame viewer. +CONFIGURATION +------------- + +@@CONFIG(gui.commitmsgwidth)@@ +@@CONFIG(gui.diffcontext)@@ +@@CONFIG(gui.encoding)@@ +@@CONFIG(gui.matchtrackingbranch)@@ +@@CONFIG(gui.newbranchtemplate)@@ +@@CONFIG(gui.pruneduringfetch)@@ +@@CONFIG(gui.trustmtime)@@ +@@CONFIG(gui.spellingdictionary)@@ +@@CONFIG(gui.fastcopyblame)@@ +@@CONFIG(gui.copyblamethreshold)@@ +@@CONFIG(gui.blamehistoryctx)@@ + + SEE ALSO -------- linkgit:gitk[1]::
Documentation/git-log.txt +6 -32
@@ -145,38 +145,12 @@ format.pretty:: Default for the `--format` option. (See "PRETTY FORMATS" above.) Defaults to "medium". -i18n.logOutputEncoding:: - Encoding to use when displaying logs. (See "Discussion", above.) - Defaults to the value of `i18n.commitEncoding` if set, UTF-8 - otherwise. - -log.date:: - Default format for human-readable dates. (Compare the - `--date` option.) Defaults to "default", which means to write - dates like `Sat May 8 19:35:34 2010 -0500`. - -log.showroot:: - If `false`, 'git log' and related commands will not treat the - initial commit as a big creation event. Any root commits in - `git log -p` output would be shown without a diff attached. - The default is `true`. - -mailmap.file:: - See linkgit:git-shortlog[1]. - -notes.displayRef:: - Which refs, in addition to the default set by `core.notesRef` - or 'GIT_NOTES_REF', to read notes from when showing commit - messages with the 'log' family of commands. See - linkgit:git-notes[1]. -+ -May be an unabbreviated ref name or a glob and may be specified -multiple times. A warning will be issued for refs that do not exist, -but a glob that does not match any refs is silently ignored. -+ -This setting can be disabled by the `--no-standard-notes` option, -overridden by the 'GIT_NOTES_DISPLAY_REF' environment variable, -and supplemented by the `--show-notes` option. +@@CONFIG(i18n.logOutputEncoding)@@ +@@CONFIG(log.date)@@ +@@CONFIG(log.decorate)@@ +@@CONFIG(log.showroot)@@ +@@CONFIG(mailmap.file)@@ +@@CONFIG(notes.displayRef)@@ Author ------
Documentation/git-merge.txt +10 -5
@@ -275,12 +275,17 @@ include::merge-strategies.txt[] CONFIGURATION ------------- -include::merge-config.txt[] -branch.<name>.mergeoptions:: - Sets default options for merging into branch <name>. The syntax and - supported options are the same as those of 'git merge', but option - values containing whitespace characters are currently not supported. +@@CONFIG(merge.conflictstyle)@@ +@@CONFIG(merge.log)@@ +@@CONFIG(merge.renameLimit)@@ +@@CONFIG(merge.stat)@@ +@@CONFIG(merge.tool)@@ +@@CONFIG(merge.verbosity)@@ +@@CONFIG(merge.<driver>.name)@@ +@@CONFIG(merge.<driver>.driver)@@ +@@CONFIG(merge.<driver>.recursive)@@ +@@CONFIG(branch.<name>.mergeoptions)@@ SEE ALSO --------
Documentation/git-pull.txt +14 -0
@@ -165,6 +165,20 @@ If you tried a pull which resulted in a complex conflicts and would want to start over, you can recover with 'git reset'. +CONFIGURATION +------------- + +Options that affect 'git pull': + +@@CONFIG(branch.<name>.remote)@@ +@@CONFIG(branch.<name>.merge)@@ +@@CONFIG(branch.<name>.rebase)@@ + +Options that affect the underlying 'git fetch' and 'git merge' are +documented in linkgit:git-fetch[1] and linkgit:git-merge[1], +respectively. + + SEE ALSO -------- linkgit:git-fetch[1], linkgit:git-merge[1], linkgit:git-config[1]
Documentation/git-push.txt +19 -0
@@ -406,6 +406,25 @@ Commits A and B would no longer belong to a branch with a symbolic name, and so would be unreachable. As such, these commits would be removed by a `git gc` command on the origin repository. +CONFIGURATION +------------- + +Variables that affect the sending (local) side: + +@@CONFIG(push.default)@@ +@@CONFIG(branch.<name>.remote)@@ +@@CONFIG(branch.<name>.merge)@@ + +Variables that affect the receiving (remote) side: + +@@CONFIG(receive.autogc)@@ +@@CONFIG(receive.fsckObjects)@@ +@@CONFIG(receive.unpackLimit)@@ +@@CONFIG(receive.denyDeletes)@@ +@@CONFIG(receive.denyDeleteCurrent)@@ +@@CONFIG(receive.denyCurrentBranch)@@ +@@CONFIG(receive.denyNonFastForwards)@@ +@@CONFIG(receive.updateserverinfo)@@ Author ------
Documentation/git-rebase.txt +2 -3
@@ -195,9 +195,8 @@ Alternatively, you can undo the 'git rebase' with CONFIGURATION ------------- -rebase.stat:: - Whether to show a diffstat of what changed upstream since the last - rebase. False by default. +@@CONFIG(rebase.stat)@@ + OPTIONS -------
Documentation/git-shortlog.txt +6 -0
@@ -69,6 +69,12 @@ spelled differently. include::mailmap.txt[] +CONFIGURATION +------------- + +@@CONFIG(mailmap.file)@@ + + Author ------ Written by Jeff Garzik <[email protected]>
Documentation/git-status.txt +5 -13
@@ -152,19 +152,11 @@ backslash-escaping is performed. Fourth, there is no branch line. CONFIGURATION ------------- -The command honors `color.status` (or `status.color` -- they -mean the same thing and the latter is kept for backward -compatibility) and `color.status.<slot>` configuration variables -to colorize its output. - -If the config variable `status.relativePaths` is set to false, then all -paths shown are relative to the repository root, not to the current -directory. - -If `status.submodulesummary` is set to a non zero number or true (identical -to -1 or an unlimited number), the submodule summary will be enabled for -the long format and a summary of commits for modified submodules will be -shown (see --summary-limit option of linkgit:git-submodule[1]). +@@CONFIG(color.status)@@ +@@CONFIG(color.status.<slot>)@@ +@@CONFIG(status.relativePaths)@@ +@@CONFIG(status.showUntrackedFiles)@@ +@@CONFIG(status.submodulesummary)@@ SEE ALSO --------
Documentation/git-submodule.txt +8 -0
@@ -258,6 +258,14 @@ to each submodule url is "submodule.$name.url". See linkgit:gitmodules[5] for details. +CONFIGURATION +------------- + +@@CONFIG(submodule.<name>.path)@@ +@@CONFIG(submodule.<name>.url)@@ +@@CONFIG(submodule.<name>.update)@@ + + AUTHOR ------ Written by Lars Hjemli <[email protected]>
Documentation/git-tag.txt +2 -9
@@ -95,15 +95,8 @@ OPTIONS CONFIGURATION ------------- -By default, 'git tag' in sign-with-default mode (-s) will use your -committer identity (of the form "Your Name <[email protected]>") to -find a key. If you want to use a different default key, you can specify -it in the repository configuration as follows: - -------------------------------------- -[user] - signingkey = <gpg-key-id> -------------------------------------- + +@@CONFIG(user.signingkey)@@ DISCUSSION
Documentation/gitk.txt +8 -0
@@ -100,6 +100,14 @@ Files Gitk creates the .gitk file in your $HOME directory to store preferences such as display options, font, and colors. + +CONFIGURATION +------------- + +@@CONFIG(gui.encoding)@@ +@@CONFIG(i18n.commitEncoding)@@ + + SEE ALSO -------- 'qgit(1)'::
Documentation/merge-config.txt deleted +0 -49
49 lines not on this page · raw message
Signature · 1 line
1.7.2.349.gd5452
Re: [PATCH 3-24/24] Documentation: include configuration options in manpages
Documentation/git-add.txt subdirectories. · line 152
Quoted 11 lines · Thomas Rast
+++
b/Documentation/git-add.txtDocumentation/git-add.txt +2
-4@@ -148,10 +148,8 @@ subdirectories. Configuration ------------- -The optional configuration variable `core.excludesfile` indicates a path to a -file containing patterns of file names to exclude from git-add, similar to -$GIT_DIR/info/exclude. Patterns in the exclude file are used in addition to -those in info/exclude. See linkgit:gitrepository-layout[5]. +@@CONFIG(add.ignore-errors)@@ +@@CONFIG(core.excludesfile)@@
Hmm, the packrat in me does not like cavalierly throwing away text like this. :)
[...]
Documentation/git-archive.txt zip · line 97
Quoted 13 lines
Documentation/git-archive.txt +3
-6+++ b/Documentation/git-archive.txt@@ -93,12 +93,8 @@ zip CONFIGURATION ------------- -tar.umask:: - This variable can be used to restrict the permission bits of - tar archive entries. The default is 0002, which turns off the - world write bit. The special value "user" indicates that the - archiving user's umask will be used instead. See umask(2) for - details. +@@CONFIG(tar.umask)@@ +
Can this genre of change be automated?
[...]
Documentation/git-branch.txt but different purposes: · line 231
Quoted 12 lines
Documentation/git-branch.txt +8
-0+++ b/Documentation/git-branch.txt@@ -222,6 +222,14 @@ but different purposes: - `--no-merged` is used to find branches which are candidates for merging into HEAD, since those branches are not fully contained by HEAD. + +CONFIGURATION +------------- + +@@CONFIG(branch.autosetupmerge)@@ +@@CONFIG(branch.autosetuprebase)@@ +
Obviously a good thing.
Thanks.
Jonathan