Greg Price <price@xxxxxxx> writes: > On Wed, Mar 06, 2013 at 09:10:57AM -0800, Junio C Hamano wrote: >> I do not know if mentioning what -A does in the description for -u >> (and vice versa) makes it easier to understand or more confusing >> (not rhetorical: I suspect some may find it easier and others not). >> >> But "and the default behaviour will..." here _is_ confusing. After >> reading this patch three times, I still cannot tell what "default" >> you are trying to describe. Is it "-u" without arguments? Is it >> "add" without "-u" nor "-A"? Is it something else??? > > I meant the behavior without -A or -u. This could be fixed directly > by s/the default behavior will/with neither -A nor -u we/. When we have bulletted list that enumerates options and describes what each option does and how each option affects the behaviour, I'd prefer to see us *not* talking about what happens when you do *not* give that option, unless it makes it hard to understand that option without such an extra description. The overall description of what the command does without the options should go to the top level. > Here's a crack at making those distinctions clear. I've also tried to > make the descriptions as parallel as possible, as what they're saying > is very similar. > > -u:: > --update:: > Update the index just where it already has an entry matching > <pathspec>. Good; this was the short phrasing I was looking for but couldn't come up with myself without repeating "the index" over and over. > Then follow both with the "If no <pathspec>" paragraph. I just > noticed that the paragraph actually needs a small modification to fit > '-A', too. New patch below. > > Greg > > From: Greg Price <price@xxxxxxx> > Date: Thu, 7 Mar 2013 02:08:21 -0800 > Subject: [PATCH] add: Clarify documentation of -A and -u (for future reference) Drop the three lines and have "-- >8 --" here. [patch kept unsnipped for others'] > The documentation of '-A' and '-u' is very confusing for someone who > doesn't already know what they do. Describe them with fewer words and > clearer parallelism to each other and to the behavior of plain 'add'. > > Also mention the default <pathspec> for '-A' as well as '-u', because > it applies to both. > > Signed-off-by: Greg Price <price@xxxxxxx> > --- > Documentation/git-add.txt | 22 ++++++++++++---------- > 1 file changed, 12 insertions(+), 10 deletions(-) > > diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt > index 388a225..b0944e5 100644 > --- a/Documentation/git-add.txt > +++ b/Documentation/git-add.txt > @@ -100,12 +100,9 @@ apply to the index. See EDITING PATCHES below. > > -u:: > --update:: > - Only match <pathspec> against already tracked files in > - the index rather than the working tree. That means that it > - will never stage new files, but that it will stage modified > - new contents of tracked files and that it will remove files > - from the index if the corresponding files in the working tree > - have been removed. > + Update the index just where it already has an entry matching > + <pathspec>. This removes as well as modifies index entries to > + match the working tree, but adds no new files. > + > If no <pathspec> is given, the current version of Git defaults to > "."; in other words, update all tracked files in the current directory > @@ -114,10 +111,15 @@ of Git, hence the form without <pathspec> should not be used. > > -A:: > --all:: > - Like `-u`, but match <pathspec> against files in the > - working tree in addition to the index. That means that it > - will find new files as well as staging modified content and > - removing files that are no longer in the working tree. > + Update the index not only where the working tree has a file > + matching <pathspec> but also where the index already has an > + entry. This adds, modifies, and removes index entries to > + match the working tree. > ++ > +If no <pathspec> is given, the current version of Git defaults to > +"."; in other words, update all files in the current directory > +and its subdirectories. This default will change in a future version > +of Git, hence the form without <pathspec> should not be used. > > -N:: > --intent-to-add:: -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html