doc: use 'title' consistently

From: M Hickford <[email protected]>

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

Prefer 'title' unless discussing email.

---
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(-)

index 602e2f1200b..70a5e4a181c 100644
@@ -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

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.

Good idea. I'll prepare patch v2.

From: M Hickford <[email protected]>

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

Prefer 'title' unless discussing email.

---
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

- ## 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(-)

index dfb78169cb7..dc219025f1e 100644
@@ -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.

index 133fe8c5e6a..153cb69a4f8 100644
@@ -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

Looking good.

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.