[PATCH] doc: use 'title' consistently

[PATCH] doc: use 'title' consistently

[M Hickford via GitGitGadget]

From: M Hickford <mirth.hickford@gmail.com>

The first line of a commit message is variously called 'title' or
'subject'.

Prefer 'title' unless discussing email.

Signed-off-by: M Hickford <mirth.hickford@gmail.com>
---
    doc: use 'title' consistently

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1893%2Fhickford%2Ftitle-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1893/hickford/title-v1
Pull-Request: https://github.com/git/git/pull/1893

 Documentation/git-commit.txt | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 602e2f1200b..70a5e4a181c 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -98,8 +98,8 @@ OPTIONS
 	replaces the log message of _<commit>_ with its own log message
 	but makes no changes to the content of _<commit>_.
 +
-The commit created by plain `--fixup=<commit>` has a subject
-composed of "fixup!" followed by the subject line from _<commit>_,
+The commit created by plain `--fixup=<commit>` has a title
+composed of "fixup!" followed by the title of _<commit>_,
 and is recognized specially by `git rebase --autosquash`. The `-m`
 option may be used to supplement the log message of the created
 commit, but the additional commentary will be thrown away once the
@@ -107,7 +107,7 @@ commit, but the additional commentary will be thrown away once the
 `git rebase --autosquash`.
 +
 The commit created by `--fixup=amend:<commit>` is similar but its
-subject is instead prefixed with "amend!". The log message of
+title is instead prefixed with "amend!". The log message of
 _<commit>_ is copied into the log message of the "amend!" commit and
 opened in an editor so it can be refined. When `git rebase
 --autosquash` squashes the "amend!" commit into _<commit>_, the
@@ -128,7 +128,7 @@ See linkgit:git-rebase[1] for details.
 
 `--squash=<commit>`::
 	Construct a commit message for use with `git rebase --autosquash`.
-	The commit message subject line is taken from the specified
+	The commit message title is taken from the specified
 	commit with a prefix of "squash! ".  Can be used with additional
 	commit message options (`-m`/`-c`/`-C`/`-F`). See
 	linkgit:git-rebase[1] for details.

base-commit: e2067b49ecaef9b7f51a17ce251f9207f72ef52d
-- 
gitgitgadget

Re: [PATCH] doc: use 'title' consistently

[Junio C Hamano]

"M Hickford via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: M Hickford <mirth.hickford@gmail.com>
>
> The first line of a commit message is variously called 'title' or
> 'subject'.
>
> Prefer 'title' unless discussing email.

We do use them interchangeably, but I agree that 'title' is a more
generic term than 'subject'.  There are a few other commands that
we may want to pay attenion to.

 - "git log --help" talks about "--oneline" and "--pretty=oneline",
   and they refer to "<title-line>", so we are good there.

 - "git shortlog" also says it groups the commits by author and
   title.

 - "git rebase --help" talks about "(commit) subject" when it
   discusses what appears in the todo-file, without referring to
   "title" at all.

We may want to update "git rebase" documentation to match what
happens in this patch at the same time, especially because it is its
interactive mode that "git rebase --help" uses "subject" to refer to
each commit's title.

Will queue.  Thanks.


> Signed-off-by: M Hickford <mirth.hickford@gmail.com>
> ---
>     doc: use 'title' consistently
>
> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1893%2Fhickford%2Ftitle-v1
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1893/hickford/title-v1
> Pull-Request: https://github.com/git/git/pull/1893
>
>  Documentation/git-commit.txt | 8 ++++----
>  1 file changed, 4 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
> index 602e2f1200b..70a5e4a181c 100644
> --- a/Documentation/git-commit.txt
> +++ b/Documentation/git-commit.txt
> @@ -98,8 +98,8 @@ OPTIONS
>  	replaces the log message of _<commit>_ with its own log message
>  	but makes no changes to the content of _<commit>_.
>  +
> -The commit created by plain `--fixup=<commit>` has a subject
> -composed of "fixup!" followed by the subject line from _<commit>_,
> +The commit created by plain `--fixup=<commit>` has a title
> +composed of "fixup!" followed by the title of _<commit>_,
>  and is recognized specially by `git rebase --autosquash`. The `-m`
>  option may be used to supplement the log message of the created
>  commit, but the additional commentary will be thrown away once the
> @@ -107,7 +107,7 @@ commit, but the additional commentary will be thrown away once the
>  `git rebase --autosquash`.
>  +
>  The commit created by `--fixup=amend:<commit>` is similar but its
> -subject is instead prefixed with "amend!". The log message of
> +title is instead prefixed with "amend!". The log message of
>  _<commit>_ is copied into the log message of the "amend!" commit and
>  opened in an editor so it can be refined. When `git rebase
>  --autosquash` squashes the "amend!" commit into _<commit>_, the
> @@ -128,7 +128,7 @@ See linkgit:git-rebase[1] for details.
>  
>  `--squash=<commit>`::
>  	Construct a commit message for use with `git rebase --autosquash`.
> -	The commit message subject line is taken from the specified
> +	The commit message title is taken from the specified
>  	commit with a prefix of "squash! ".  Can be used with additional
>  	commit message options (`-m`/`-c`/`-C`/`-F`). See
>  	linkgit:git-rebase[1] for details.
>
> base-commit: e2067b49ecaef9b7f51a17ce251f9207f72ef52d

Re: [PATCH] doc: use 'title' consistently

[M Hickford]

> We may want to update "git rebase" documentation to match what
> happens in this patch at the same time, especially because it is its
> interactive mode that "git rebase --help" uses "subject" to refer to
> each commit's title.

Good idea. I'll prepare patch v2.

[PATCH v2] doc: use 'title' consistently

[M Hickford via GitGitGadget]

From: M Hickford <mirth.hickford@gmail.com>

The first line of a commit message is variously called 'title' or
'subject'.

Prefer 'title' unless discussing email.

Signed-off-by: M Hickford <mirth.hickford@gmail.com>
---
    doc: use 'title' consistently
    
    Patch v2 includes git-rebase.txt

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1893%2Fhickford%2Ftitle-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1893/hickford/title-v2
Pull-Request: https://github.com/git/git/pull/1893

Range-diff vs v1:

 1:  4e31627a4c4 ! 1:  0bca7a06d11 doc: use 'title' consistently
     @@ Commit message
      
          Signed-off-by: M Hickford <mirth.hickford@gmail.com>
      
     - ## Documentation/git-commit.txt ##
     -@@ Documentation/git-commit.txt: OPTIONS
     + ## Documentation/git-commit.adoc ##
     +@@ Documentation/git-commit.adoc: OPTIONS
       	replaces the log message of _<commit>_ with its own log message
       	but makes no changes to the content of _<commit>_.
       +
     @@ Documentation/git-commit.txt: OPTIONS
       and is recognized specially by `git rebase --autosquash`. The `-m`
       option may be used to supplement the log message of the created
       commit, but the additional commentary will be thrown away once the
     -@@ Documentation/git-commit.txt: commit, but the additional commentary will be thrown away once the
     +@@ Documentation/git-commit.adoc: commit, but the additional commentary will be thrown away once the
       `git rebase --autosquash`.
       +
       The commit created by `--fixup=amend:<commit>` is similar but its
     @@ Documentation/git-commit.txt: commit, but the additional commentary will be thro
       _<commit>_ is copied into the log message of the "amend!" commit and
       opened in an editor so it can be refined. When `git rebase
       --autosquash` squashes the "amend!" commit into _<commit>_, the
     -@@ Documentation/git-commit.txt: See linkgit:git-rebase[1] for details.
     +@@ Documentation/git-commit.adoc: See linkgit:git-rebase[1] for details.
       
       `--squash=<commit>`::
       	Construct a commit message for use with `git rebase --autosquash`.
     @@ Documentation/git-commit.txt: See linkgit:git-rebase[1] for details.
       	commit with a prefix of "squash! ".  Can be used with additional
       	commit message options (`-m`/`-c`/`-C`/`-F`). See
       	linkgit:git-rebase[1] for details.
     +
     + ## Documentation/git-rebase.adoc ##
     +@@ Documentation/git-rebase.adoc: See also INCOMPATIBLE OPTIONS below.
     + --no-autosquash::
     + 	Automatically squash commits with specially formatted messages into
     + 	previous commits being rebased.  If a commit message starts with
     +-	"squash! ", "fixup! " or "amend! ", the remainder of the subject line
     ++	"squash! ", "fixup! " or "amend! ", the remainder of the title
     + 	is taken as a commit specifier, which matches a previous commit if it
     +-	matches the subject line or the hash of that commit.  If no commit
     ++	matches the title or the hash of that commit.  If no commit
     + 	matches fully, matches of the specifier with the start of commit
     +-	subjects are considered.
     ++	titles are considered.
     + +
     + In the rebase todo list, the actions of squash, fixup and amend commits are
     + changed from `pick` to `squash`, `fixup` or `fixup -C`, respectively, and they
     +@@ Documentation/git-rebase.adoc: be used to review and edit the todo list before proceeding.
     + The recommended way to create commits with squash markers is by using the
     + `--squash`, `--fixup`, `--fixup=amend:` or `--fixup=reword:` options of
     + linkgit:git-commit[1], which take the target commit as an argument and
     +-automatically fill in the subject line of the new commit from that.
     ++automatically fill in the title of the new commit from that.
     + +
     + Setting configuration variable `rebase.autoSquash` to true enables
     + auto-squashing by default for interactive rebase.  The `--no-autosquash`


 Documentation/git-commit.adoc | 8 ++++----
 Documentation/git-rebase.adoc | 8 ++++----
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/Documentation/git-commit.adoc b/Documentation/git-commit.adoc
index dfb78169cb7..dc219025f1e 100644
--- a/Documentation/git-commit.adoc
+++ b/Documentation/git-commit.adoc
@@ -98,8 +98,8 @@ OPTIONS
 	replaces the log message of _<commit>_ with its own log message
 	but makes no changes to the content of _<commit>_.
 +
-The commit created by plain `--fixup=<commit>` has a subject
-composed of "fixup!" followed by the subject line from _<commit>_,
+The commit created by plain `--fixup=<commit>` has a title
+composed of "fixup!" followed by the title of _<commit>_,
 and is recognized specially by `git rebase --autosquash`. The `-m`
 option may be used to supplement the log message of the created
 commit, but the additional commentary will be thrown away once the
@@ -107,7 +107,7 @@ commit, but the additional commentary will be thrown away once the
 `git rebase --autosquash`.
 +
 The commit created by `--fixup=amend:<commit>` is similar but its
-subject is instead prefixed with "amend!". The log message of
+title is instead prefixed with "amend!". The log message of
 _<commit>_ is copied into the log message of the "amend!" commit and
 opened in an editor so it can be refined. When `git rebase
 --autosquash` squashes the "amend!" commit into _<commit>_, the
@@ -128,7 +128,7 @@ See linkgit:git-rebase[1] for details.
 
 `--squash=<commit>`::
 	Construct a commit message for use with `git rebase --autosquash`.
-	The commit message subject line is taken from the specified
+	The commit message title is taken from the specified
 	commit with a prefix of "squash! ".  Can be used with additional
 	commit message options (`-m`/`-c`/`-C`/`-F`). See
 	linkgit:git-rebase[1] for details.
diff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc
index 133fe8c5e6a..153cb69a4f8 100644
--- a/Documentation/git-rebase.adoc
+++ b/Documentation/git-rebase.adoc
@@ -599,11 +599,11 @@ See also INCOMPATIBLE OPTIONS below.
 --no-autosquash::
 	Automatically squash commits with specially formatted messages into
 	previous commits being rebased.  If a commit message starts with
-	"squash! ", "fixup! " or "amend! ", the remainder of the subject line
+	"squash! ", "fixup! " or "amend! ", the remainder of the title
 	is taken as a commit specifier, which matches a previous commit if it
-	matches the subject line or the hash of that commit.  If no commit
+	matches the title or the hash of that commit.  If no commit
 	matches fully, matches of the specifier with the start of commit
-	subjects are considered.
+	titles are considered.
 +
 In the rebase todo list, the actions of squash, fixup and amend commits are
 changed from `pick` to `squash`, `fixup` or `fixup -C`, respectively, and they
@@ -613,7 +613,7 @@ be used to review and edit the todo list before proceeding.
 The recommended way to create commits with squash markers is by using the
 `--squash`, `--fixup`, `--fixup=amend:` or `--fixup=reword:` options of
 linkgit:git-commit[1], which take the target commit as an argument and
-automatically fill in the subject line of the new commit from that.
+automatically fill in the title of the new commit from that.
 +
 Setting configuration variable `rebase.autoSquash` to true enables
 auto-squashing by default for interactive rebase.  The `--no-autosquash`

base-commit: 03944513488db4a81fdb4c21c3b515e4cb260b05
-- 
gitgitgadget

Re: [PATCH v2] doc: use 'title' consistently

[Junio C Hamano]

"M Hickford via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: M Hickford <mirth.hickford@gmail.com>
>
> The first line of a commit message is variously called 'title' or
> 'subject'.
>
> Prefer 'title' unless discussing email.
>
> Signed-off-by: M Hickford <mirth.hickford@gmail.com>
> ---
>     doc: use 'title' consistently
>     
>     Patch v2 includes git-rebase.txt

Looking good.

>  Documentation/git-commit.adoc | 8 ++++----
>  Documentation/git-rebase.adoc | 8 ++++----
>  2 files changed, 8 insertions(+), 8 deletions(-)

Will apply with s/adoc/txt/ so that the result becomes obviously
merge-able to 'maint' (even though currently I do not plan to do a
Git 2.48.2 right now, I often do this to make it easy for distro
maintainers to backport obvious fixes to their maintenance tracks).

Thanks.