summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorJunio C Hamano <gitster@pobox.com>2015-03-05 21:13:05 (GMT)
committerJunio C Hamano <gitster@pobox.com>2015-03-05 21:13:05 (GMT)
commitc11c154f429f23f1c30f2aa067ff8bf6c1b982fe (patch)
treea602dec0fd795d93525b61c79c77f3152efc0972 /Documentation
parent518d1c349bda5652a6884127f1d7f5722d557bc8 (diff)
parent35840a3e789dd67528caefc146deb698bd6ac7a5 (diff)
downloadgit-c11c154f429f23f1c30f2aa067ff8bf6c1b982fe.zip
git-c11c154f429f23f1c30f2aa067ff8bf6c1b982fe.tar.gz
git-c11c154f429f23f1c30f2aa067ff8bf6c1b982fe.tar.bz2
Merge branch 'jc/conf-var-doc' into maint
Longstanding configuration variable naming rules has been added to the documentation. * jc/conf-var-doc: CodingGuidelines: describe naming rules for configuration variables config.txt: mark deprecated variables more prominently config.txt: clarify that add.ignore-errors is deprecated
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/CodingGuidelines23
-rw-r--r--Documentation/config.txt15
2 files changed, 30 insertions, 8 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 894546d..0f8cccf 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -413,6 +413,29 @@ Error Messages
- Say what the error is first ("cannot open %s", not "%s: cannot open")
+Externally Visible Names
+
+ - For configuration variable names, follow the existing convention:
+
+ . The section name indicates the affected subsystem.
+
+ . The subsection name, if any, indicates which of an unbounded set
+ of things to set the value for.
+
+ . The variable name describes the effect of tweaking this knob.
+
+ The section and variable names that consist of multiple words are
+ formed by concatenating the words without punctuations (e.g. `-`),
+ and are broken using bumpyCaps in documentation as a hint to the
+ reader.
+
+ When choosing the variable namespace, do not use variable name for
+ specifying possibly unbounded set of things, most notably anything
+ an end user can freely come up with (e.g. branch names). Instead,
+ use subsection names or variable values, like the existing variable
+ branch.<name>.description does.
+
+
Writing Documentation:
Most (if not all) of the documentation pages are written in the
diff --git a/Documentation/config.txt b/Documentation/config.txt
index 04e2a71..b22a7a7 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -683,14 +683,13 @@ core.abbrev::
for abbreviated object names to stay unique for sufficiently long
time.
-add.ignore-errors::
add.ignoreErrors::
+add.ignore-errors (deprecated)::
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]. Older versions of Git accept only
- `add.ignore-errors`, which does not follow the usual naming
- convention for configuration variables. Newer versions of Git
- honor `add.ignoreErrors` as well.
+ option of linkgit:git-add[1]. `add.ignore-errors` is deprecated,
+ as it does not follow the usual naming convention for configuration
+ variables.
alias.*::
Command aliases for the linkgit:git[1] command wrapper - e.g.
@@ -1960,7 +1959,7 @@ pack.useBitmaps::
true. You should not generally need to turn this off unless
you are debugging pack bitmaps.
-pack.writebitmaps::
+pack.writebitmaps (deprecated)::
This is a deprecated synonym for `repack.writeBitmaps`.
pack.writeBitmapHashCache::
@@ -2297,7 +2296,7 @@ sendemail.smtpencryption::
See linkgit:git-send-email[1] for description. Note that this
setting is not subject to the 'identity' mechanism.
-sendemail.smtpssl::
+sendemail.smtpssl (deprecated)::
Deprecated alias for 'sendemail.smtpencryption = ssl'.
sendemail.smtpsslcertpath::
@@ -2337,7 +2336,7 @@ sendemail.validate::
sendemail.xmailer::
See linkgit:git-send-email[1] for description.
-sendemail.signedoffcc::
+sendemail.signedoffcc (deprecated)::
Deprecated alias for 'sendemail.signedoffbycc'.
showbranch.default::