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

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 13, 2025, 20:27 UTC
Message-ID: <xmqq5xldoaj6.fsf@gitster.g>
In-Reply-To: <pull.1893.git.git.1739477118350.gitgitgadget@gmail.com>

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

Show 6 quoted lines

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

Show 46 quoted lines

> 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