Merge branch 'jc/conf-var-doc'

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

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 49089de5c0024202493867e545d3d6b87c98571d..7636199fe8815b09730cd0877f230797ada364ed 100644 (file)
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -418,6 +418,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 ae6791db128130080915bf127cfa66b850921f43..440784cbdd4eaca18e295e382b7568146c0c1e78 100644 (file)
--- 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::
@@ -2306,7 +2305,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::
@@ -2346,7 +2345,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::