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@gmail.com> 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@gmail.com>
> > ---
> > 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".