[v2,5/6] doc: commit: unify <pathspec> description

Commit Message

Linus Arver via GitGitGadget Nov. 6, 2019, 3:51 p.m. UTC

From: Alexandr Miloslavskiy <[e-mail]>

Synchronize it to `git add`, which has a pretty good description.
This also better disambiguates <file>... header.

Signed-off-by: Alexandr Miloslavskiy <[e-mail]>
---
 Documentation/git-commit.txt | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

Comments

Junio C Hamano Nov. 19, 2019, 6:16 a.m. UTC | #1

"Alexandr Miloslavskiy via GitGitGadget" <[e-mail]>
writes:
> +<pathspec>...::
> +	When pathspec is given on the command line, commit the contents of
> +	the files that match the pathspec without recording the changes
> +	already added to the index. The contents of these files are also
> +	staged for the next commit on top of what have been staged before.
> ++
> +For more details about the <pathspec> syntax, see the 'pathspec' entry
> +in linkgit:gitglossary[7].

What you added in [PATCH 3/6] (git reset doc) sends a slightly
different message, i.e.

    The <pathspec> is used to limit the paths affected by the operation
    (see the entry for 'pathspec' in linkgit:gitglossary[7] for more details).

and I think that was more appropriate than what we see here.  You
are referring your readers to the glossary entry not just for the
syntax but also the entire concept of <pathspec>.

IOW, it would be needed to drop "syntax" from "about the <pathspec>
syntax" from here to match the update to "git reset" documentation.

Thanks.

Alexandr Miloslavskiy Nov. 19, 2019, 4:53 p.m. UTC | #2

On 19.11.2019 7:16, Junio C Hamano wrote:
>> +For more details about the <pathspec> syntax, see the 'pathspec' entry
>> +in linkgit:gitglossary[7].
> 
> What you added in [PATCH 3/6] (git reset doc) sends a slightly
> different message, i.e.
> 
>      The <pathspec> is used to limit the paths affected by the operation
>      (see the entry for 'pathspec' in linkgit:gitglossary[7] for more details).
> 
> and I think that was more appropriate than what we see here.  You
> are referring your readers to the glossary entry not just for the
> syntax but also the entire concept of <pathspec>.
> 
> IOW, it would be needed to drop "syntax" from "about the <pathspec>
> syntax" from here to match the update to "git reset" documentation.

I shortened it even more in V3, I think it's better now?

Alexandr Miloslavskiy Nov. 19, 2019, 5:02 p.m. UTC | #3

On 19.11.2019 7:16, Junio C Hamano wrote:

>> +For more details about the <pathspec> syntax, see the 'pathspec' entry
>> +in linkgit:gitglossary[7].
> 
> What you added in [PATCH 3/6] (git reset doc) sends a slightly
> different message, i.e.
> 
>      The <pathspec> is used to limit the paths affected by the operation
>      (see the entry for 'pathspec' in linkgit:gitglossary[7] for more details).
> 
> and I think that was more appropriate than what we see here.  You
> are referring your readers to the glossary entry not just for the
> syntax but also the entire concept of <pathspec>.

This has shown me that I didn't synchronize docs enough. I have studied 
docs for other commands and found out that most of them list <pathspec> 
in a separate paragraph under options.

I find it very reasonable, because that's where I would normally expect 
it as a reader, together with other options.

So I adjusted 'git-reset' docs to also list <pathspec> under options.

Patch

diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index afa7b75a23..915c212a0d 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -13,7 +13,7 @@  SYNOPSIS
 	   [-F <file> | -m <msg>] [--reset-author] [--allow-empty]
 	   [--allow-empty-message] [--no-verify] [-e] [--author=<author>]
 	   [--date=<date>] [--cleanup=<mode>] [--[no-]status]
-	   [-i | -o] [-S[<keyid>]] [--] [<file>...]
+	   [-i | -o] [-S[<keyid>]] [--] [<pathspec>...]
 
 DESCRIPTION
 -----------
@@ -345,12 +345,14 @@  changes to tracked files.
 \--::
 	Do not interpret any more arguments as options.
 
-<file>...::
-	When files are given on the command line, the command
-	commits the contents of the named files, without
-	recording the changes already staged.  The contents of
-	these files are also staged for the next commit on top
-	of what have been staged before.
+<pathspec>...::
+	When pathspec is given on the command line, commit the contents of
+	the files that match the pathspec without recording the changes
+	already added to the index. The contents of these files are also
+	staged for the next commit on top of what have been staged before.
++
+For more details about the <pathspec> syntax, see the 'pathspec' entry
+in linkgit:gitglossary[7].
 
 :git-commit: 1
 include::date-formats.txt[]