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