Duy Nguyen <pclo...@gmail.com> writes: >> At the least I think we should clarify this in the document. > > How about something like this? Would it help? > > -- 8< -- > Subject: [PATCH] git-commit.txt: clarify --patch mode with pathspec > > How pathspec is used, with and without --interactive/--patch, is > different. But this is not clear from the document. These changes hint > the user to keep reading (to option #5) instead of stopping at #2 and > assuming --patch/--interactive behaves the same way. > > And since all the options listed here always mention how the index is > involved (or not) in the final commit, add that bit for #5 as well. This > "on top of the index" is implied when you head over git-add(1), but if > you just go straight to the "Interactive mode" and not read what git-add > is for, you may miss it. > > Signed-off-by: Nguyễn Thái Ngọc Duy <pclo...@gmail.com> > ---
Excellent. > Documentation/git-commit.txt | 6 ++++-- > 1 file changed, 4 insertions(+), 2 deletions(-) > > diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt > index b0a294d..f2ab0ee 100644 > --- a/Documentation/git-commit.txt > +++ b/Documentation/git-commit.txt > @@ -29,7 +29,8 @@ The content to be added can be specified in several ways: > 2. by using 'git rm' 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, in which > +3. by listing files as arguments to the 'commit' command > + (without --interactive or --patch switch), in which > case the commit will ignore changes staged in the index, and instead > record the current content of the listed files (which must already > be known to Git); > @@ -41,7 +42,8 @@ The content to be added can be specified in several ways: > actual commit; > > 5. by using the --interactive or --patch switches with the 'commit' command > - to decide one by one which files or hunks should be part of the commit, > + to decide one by one which files or hunks should be part of the commit > + in addition to contents in the index, > before finalizing the operation. See the ``Interactive Mode'' section of > linkgit:git-add[1] to learn how to operate these modes. When re-reading these 5 bullet points, I feel there may be some unrelated updates needed to clarify (e.g. it is unclear when reading the description pretending to be a newbie, if it is the "changes" that is recorded in the index, or if it is the "state"; the answer is the latter but if the reader's world model is still the former, the description can mislead to expect a different behaviour). But regardless of such remaining potential issues, this is a clearly good change. Thanks.
