Web lists-archives.com

Re: [PATCH] git-commit.txt: better description what it does




On Thu, Jan 31, 2019 at 4:21 AM Nguyễn Thái Ngọc Duy <pclouds@xxxxxxxxx> wrote:
> The description of git-commit jumps right into the commit content, which
> is important, but it fails to mention how the commit is "added" to the
> repository. Update the first paragraph saying a bit more about branch
> update to fill this gap.
>
> While at there, add a couple linkgit references when the command is
> first mentioned.
>
> Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@xxxxxxxxx>
> ---
> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
> @@ -17,16 +17,19 @@ SYNOPSIS
>  DESCRIPTION
>  -----------
> +Creates a new commit containing the current contents of the index with
> +a log message from the user describing the changes. The commit is the
> +direct child of the tip of the current branch. The branch is updated
> +to point to the new commit (unless no branch is associated with the
> +working tree, see "NOTES" section).

Okay. The information about the branch being updated makes sense.

> +NOTES
> +-----
> +If a branch is associated with the working tree, 'HEAD' points to this
> +branch. When a new commit is created, the branch is updated to point
> +to the new commit. As a result, resolving 'HEAD' still gives the new
> +commit.

I'm not sure I understand the purpose of the final sentence about HEAD
"still resolving" when you were, just before that, talking about the
branch.

> +If no branch is associated with the working tree (i.e. "detached HEAD"
> +as described in linkgit:git-checkout[1]), 'HEAD' records the object
> +name of the previous commit directly. When a new commit is created, it
> +will be updated to point to the new commit.

I'm having a hard time figuring out what these two paragraphs together
want to say. I _think_ they want to say that HEAD is updated
automatically to point at the latest commit, and that if a branch
points at HEAD, then the branch is is updated along with HEAD,
otherwise if no branch, then it's a "detached HEAD".