[PATCH] config: document blame configuration

[PATCH] config: document blame configuration

[Stefan Beller]

The options are currently only referenced by the git-blame man page,
also explain them in git-config, which is the canonical page to
contain all config options.

Signed-off-by: Stefan Beller <sbeller@google.com>
---
 Documentation/config.txt | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 1ac0ae6adb..b18cead6aa 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -949,6 +949,23 @@ apply.whitespace::
 	Tells 'git apply' how to handle whitespaces, in the same way
 	as the `--whitespace` option. See linkgit:git-apply[1].
 
+blame.root::
+	Do not treat root commits as boundaries in `git-blame`.
+	This option defaults to false.
+
+blame.blankboundary::
+	Show blank SHA-1 for boundary commits in `git-blame`.
+	This option defaults to false.
+
+blame.showemail::
+	Show the author email instead of author name in `git-blame`.
+	This option defaults to false.
+
+blame.date::
+	Specifies the format used to output dates in `git-blame`.
+	If unset the iso format is used. For supported values,
+	see the discussion of the --date option at linkgit:git-log[1].
+
 branch.autoSetupMerge::
 	Tells 'git branch' and 'git checkout' to set up new branches
 	so that linkgit:git-pull[1] will appropriately merge from the
-- 
2.15.0.7.g980e40477f

Re: [PATCH] config: document blame configuration

[SZEDER Gábor]

> The options are currently only referenced by the git-blame man page,
> also explain them in git-config, which is the canonical page to
> contain all config options.

Good idea.

> Signed-off-by: Stefan Beller <sbeller@google.com>
> ---
>  Documentation/config.txt | 17 +++++++++++++++++
>  1 file changed, 17 insertions(+)
> 
> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index 1ac0ae6adb..b18cead6aa 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -949,6 +949,23 @@ apply.whitespace::
>  	Tells 'git apply' how to handle whitespaces, in the same way
>  	as the `--whitespace` option. See linkgit:git-apply[1].
>  
> +blame.root::

This is blame.showRoot, isn't it?

> +	Do not treat root commits as boundaries in `git-blame`.

You consistently write `git-blame`, i.e. with dash and between
backticks.  The patch context mentions five git commands: two of them
are linkgit macros, but the other three are all written without dash
and between single quotes.  I think it should be written without dash,
but I'm not sure about single quotes vs. backticks.  grep tells me
they are both widespread for enclosing git commands.

> +	This option defaults to false.
> +
> +blame.blankboundary::

Config variables are usually written in camelCase in the
documentation, see e.g. branch.autoSetupMerge in the patch context
below.

> +	Show blank SHA-1 for boundary commits in `git-blame`.

Perhaps "Show blank object ID", since we're moving away from SHA-1?

> +	This option defaults to false.
> +
> +blame.showemail::

Again camelCase.

> +	Show the author email instead of author name in `git-blame`.
> +	This option defaults to false.
> +
> +blame.date::
> +	Specifies the format used to output dates in `git-blame`.
> +	If unset the iso format is used. For supported values,
> +	see the discussion of the --date option at linkgit:git-log[1].

Should '--date' be enclosed in... single quotes or backticks?  I don't
know.

> +
>  branch.autoSetupMerge::
>  	Tells 'git branch' and 'git checkout' to set up new branches
>  	so that linkgit:git-pull[1] will appropriately merge from the
> -- 
> 2.15.0.7.g980e40477f
> 
> 

[PATCHv2] config: document blame configuration

[Stefan Beller]

The options are currently only referenced by the git-blame man page,
also explain them in git-config, which is the canonical page to
contain all config options.

Signed-off-by: Stefan Beller <sbeller@google.com>
---

 * correct option to blame.showRoot
 * camelCased other options
 * use linkgit:git-<command>[1] instead of `git-cmd` as that
   is correct, but maybe overused.
 * --date is `backticked` now.

 Documentation/config.txt | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 1ac0ae6adb..ba0156b1e8 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -949,6 +949,23 @@ apply.whitespace::
 	Tells 'git apply' how to handle whitespaces, in the same way
 	as the `--whitespace` option. See linkgit:git-apply[1].
 
+blame.showRoot::
+	Do not treat root commits as boundaries in linkgit:git-blame[1].
+	This option defaults to false.
+
+blame.blankBoundary::
+	Show blank SHA-1 for boundary commits in linkgit:git-blame[1].
+	This option defaults to false.
+
+blame.showEmail::
+	Show the author email instead of author name in linkgit:git-blame[1].
+	This option defaults to false.
+
+blame.date::
+	Specifies the format used to output dates in linkgit:git-blame[1].
+	If unset the iso format is used. For supported values,
+	see the discussion of the `--date` option at linkgit:git-log[1].
+
 branch.autoSetupMerge::
 	Tells 'git branch' and 'git checkout' to set up new branches
 	so that linkgit:git-pull[1] will appropriately merge from the
-- 
2.15.0.7.g980e40477f

Re: [PATCHv2] config: document blame configuration

[SZEDER Gábor]

On Thu, Nov 2, 2017 at 7:10 PM, Stefan Beller <sbeller@google.com> wrote:

> +blame.blankBoundary::
> +       Show blank SHA-1 for boundary commits in linkgit:git-blame[1].

This is still SHA-1 instead of object id (or perhaps "commit object
name" would be even better).
Not sure whether oversight or intentional.

Re: [PATCHv2] config: document blame configuration

[Stefan Beller]

On Thu, Nov 2, 2017 at 6:26 PM, SZEDER Gábor <szeder.dev@gmail.com> wrote:
> On Thu, Nov 2, 2017 at 7:10 PM, Stefan Beller <sbeller@google.com> wrote:
>
>> +blame.blankBoundary::
>> +       Show blank SHA-1 for boundary commits in linkgit:git-blame[1].
>
> This is still SHA-1 instead of object id (or perhaps "commit object
> name" would be even better).
> Not sure whether oversight or intentional.

definitely oversight.

[PATCH] config: document blame configuration

[Stefan Beller]

The options are currently only referenced by the git-blame man page,
also explain them in git-config, which is the canonical page to
contain all config options.

Signed-off-by: Stefan Beller <sbeller@google.com>
---

 Now with 'commit object name'.
 Thanks!
 
 Documentation/config.txt | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 1ac0ae6adb..9593bfabaa 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -949,6 +949,23 @@ apply.whitespace::
 	Tells 'git apply' how to handle whitespaces, in the same way
 	as the `--whitespace` option. See linkgit:git-apply[1].
 
+blame.showRoot::
+	Do not treat root commits as boundaries in linkgit:git-blame[1].
+	This option defaults to false.
+
+blame.blankBoundary::
+	Show blank commit object name for boundary commits in
+	linkgit:git-blame[1]. This option defaults to false.
+
+blame.showEmail::
+	Show the author email instead of author name in linkgit:git-blame[1].
+	This option defaults to false.
+
+blame.date::
+	Specifies the format used to output dates in linkgit:git-blame[1].
+	If unset the iso format is used. For supported values,
+	see the discussion of the `--date` option at linkgit:git-log[1].
+
 branch.autoSetupMerge::
 	Tells 'git branch' and 'git checkout' to set up new branches
 	so that linkgit:git-pull[1] will appropriately merge from the
-- 
2.15.0.7.g980e40477f

Re: [PATCH] config: document blame configuration

[Junio C Hamano]

Stefan Beller <sbeller@google.com> writes:

> The options are currently only referenced by the git-blame man page,
> also explain them in git-config, which is the canonical page to
> contain all config options.
>
> Signed-off-by: Stefan Beller <sbeller@google.com>
> ---

Excellent.  Will queue.  Thanks.