Re: [PATCH] status: hint the user about -uno if read_directory takes too long

> Torsten Bögershausen<tboegi@web.de>  writes:
>
>> [PATCH] git status: Document that git status -uno is faster
>>
>> In some repostories users expere that "git status" command takes long time.
> expere???  Certainly you did not mean "expect".  "observe",
> "experience", or "see", perhaps?
>
>> The command spends some time searching the file system for untracked files.
>> Document that searching for untracked file may take some time, and docuemnt
>> the option -uno better.
> Good intentions.
>
>> Signed-off-by: Torsten Bögershausen<tboegi@web.de>
>> ---
>>   Documentation/git-status.txt | 7 +++++++
>>   1 file changed, 7 insertions(+)
>>
>> diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
>> index 0412c40..fd36bbd 100644
>> --- a/Documentation/git-status.txt
>> +++ b/Documentation/git-status.txt
>> @@ -58,6 +58,13 @@ The possible options are:
>>   The default can be changed using the status.showUntrackedFiles
>>   configuration variable documented in linkgit:git-config[1].
>>
>> ++
>> +Note: Searching the file system for untracked files may take some time.
>> +git status -uno is faster than git status -uall.
>> +There is a trade-off around the use of -uno between safety and performance.
>> +The default is not to use -uno so that you will not forget to add a
>> file you newly created (i.e safety).
>> +You would pay for the safety with the cost to find such untracked
>> files (i.e. performance).
>> +
> The second sentence looks out of flow, and the last sentence, while
> technically not incorrect, is unclear what it is trying to convey in
> the larger picture.
>
> Perhaps it is just me.
>
> In any case, I think it is a good idea to explain the reason why the
> user might want to use a non-default setting, and the criteria the
> user may want to base the choice on (which is the gist of your
> addition), and it is a good idea to do so _before_ saying "The
> default can be changed using ...".
>
> How about this?
>
>   Documentation/git-status.txt | 14 ++++++++++----
>   1 file changed, 10 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
> index 0412c40..9046df9 100644
> --- a/Documentation/git-status.txt
> +++ b/Documentation/git-status.txt
> @@ -46,15 +46,21 @@ OPTIONS
>   	Show untracked files.
>   +
>   The mode parameter is optional (defaults to 'all'), and is used to
> -specify the handling of untracked files; when -u is not used, the
> -default is 'normal', i.e. show untracked files and directories.
> +specify the handling of untracked files.
>   +
>   The possible options are:
>   +
> -	- 'no'     - Show no untracked files
> -	- 'normal' - Shows untracked files and directories
> +	- 'no'     - Show no untracked files.
> +	- 'normal' - Shows untracked files and directories.
>   	- 'all'    - Also shows individual files in untracked directories.
>   +
> +When `-u` option is not used, untracked files and directories are
> +shown (i.e. the same as specifying `normal`), to help you avoid
> +forgetting to add newly created files.  Because it takes extra work
> +to find untracked files in the filesystem, this mode may take some
> +time in a large working tree.  You can use `no` to have `git status`