Re: [PATCH] add: Clarify documentation of -A and -u

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

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

> 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@mit.edu>
> Date: Thu, 7 Mar 2013 02:08:21 -0800
> Subject: [PATCH] add: Clarify documentation of -A and -u

> 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@mit.edu>
> ---
>  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::