On Thu, Jan 31, 2019 at 5:49 PM Eric Sunshine <sunshine@xxxxxxxxxxxxxx> wrote: > > 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". I felt some more explanation was needed when I mentioned about updating current branch in the description, but then what happens when there's no branch (aka detached HEAD)? There is still some updates. If you consider HEAD a branch, then it's ok, but otherwise something is missing. But perhaps this is the kind of details that could be left out? -- Duy
