From 394e1505b8c359461c4b7cbbd204f86b185c64a0 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Tue, 27 Jan 2015 12:19:11 -0800 Subject: config.txt: clarify that add.ignore-errors is deprecated The old text gave an impression that even in a new repository using old form might be safer. Only Git from pre 1.7.0 days choke on the correctly named variable, which is ancient by today's standard. We have no intention to remove the support for deprecated ones, but let's make sure that we do not give room for confused questions such as "why does core.sparse-checkout not work, when add.ignore-errors does?" Signed-off-by: Junio C Hamano --- Documentation/config.txt | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/Documentation/config.txt b/Documentation/config.txt index 0a4d22aaf7..69f30d63c2 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -664,14 +664,13 @@ core.abbrev:: for abbreviated object names to stay unique for sufficiently long time. -add.ignore-errors:: add.ignoreErrors:: +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]. 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. -- cgit v1.2.1 From 502e7f9851768974a5b45a9dc00882231dac5c90 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Tue, 27 Jan 2015 12:25:48 -0800 Subject: config.txt: mark deprecated variables more prominently Signed-off-by: Junio C Hamano --- Documentation/config.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Documentation/config.txt b/Documentation/config.txt index 69f30d63c2..8a76d1dc2a 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -665,7 +665,7 @@ core.abbrev:: time. add.ignoreErrors:: -add.ignore-errors:: +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]. `add.ignore-errors` is deprecated, @@ -1923,7 +1923,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:: @@ -2234,7 +2234,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:: @@ -2272,7 +2272,7 @@ sendemail.thread:: sendemail.validate:: See linkgit:git-send-email[1] for description. -sendemail.signedoffcc:: +sendemail.signedoffcc (deprecated):: Deprecated alias for 'sendemail.signedoffbycc'. showbranch.default:: -- cgit v1.2.1 From 35840a3e789dd67528caefc146deb698bd6ac7a5 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Tue, 27 Jan 2015 12:26:03 -0800 Subject: CodingGuidelines: describe naming rules for configuration variables We may want to say something about command line option names in the new section as well, but for now, let's make sure everybody is clear on how to structure and name their configuration variables. The text for the rules are partly taken from the log message of Jonathan's 6b3020a2 (add: introduce add.ignoreerrors synonym for add.ignore-errors, 2010-12-01). Signed-off-by: Junio C Hamano --- Documentation/CodingGuidelines | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 894546dd75..0f8cccf52d 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..description does. + + Writing Documentation: Most (if not all) of the documentation pages are written in the -- cgit v1.2.1