| Message ID | 20190131092112.6197-1-pclouds@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | git-commit.txt: better description what it does | expand |
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".
On Thu, Jan 31, 2019 at 5:49 PM Eric Sunshine <sunshine@sunshineco.com> wrote: > > 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". 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?
On Thu, Jan 31, 2019 at 6:04 AM Duy Nguyen <pclouds@gmail.com> wrote: > On Thu, Jan 31, 2019 at 5:49 PM Eric Sunshine <sunshine@sunshineco.com> wrote: > > On Thu, Jan 31, 2019 at 4:21 AM Nguyễn Thái Ngọc Duy <pclouds@gmail.com> wrote: > > > +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. > > > + > > > +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? It could be left out or incorporated directly into the DESCRIPTION section with a link to the much more thorough discussion of detached HEAD in git-checkout documentation. Here's my attempt at rewriting DESCRIPTION (and dropping NOTES altogether): Create a new commit containing the current contents of the index and the given log message describing the changes. The new commit is a direct child of HEAD, usually the tip of the current branch, and the branch is updated to point to it (unless no branch is associated with the working tree, in which case HEAD is "detached" as described in linkgit:git-checkout[1]). (I also streamlined the above a bit from what you had composed.)
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index f970a43422..8148ba10b3 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -17,16 +17,19 @@ SYNOPSIS DESCRIPTION ----------- -Stores the current contents of the index in a new commit along -with a log message from the user describing the changes. +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). -The content to be added can be specified in several ways: +The content to be committed can be specified in several ways: -1. by using 'git add' to incrementally "add" changes to the - index before using the 'commit' command (Note: even modified - files must be "added"); +1. by using linkgit:git-add[1] to incrementally "add" changes to the + index before using the 'commit' command (Note: even modified files + must be "added"); -2. by using 'git rm' to remove files from the working tree +2. by using linkgit:git-rm[1] to remove files from the working tree and the index, again before using the 'commit' command; 3. by listing files as arguments to the 'commit' command @@ -349,6 +352,18 @@ changes to tracked files. :git-commit: 1 include::date-formats.txt[] +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. + +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. + EXAMPLES -------- When recording your own work, the contents of modified files in