Re: [PATCH v2 2/5] Update documentation for new directory and status logic

[Jameson Miller <jameson.miller81@gmail.com>]

On 10/11/2017 10:55 PM, Junio C Hamano wrote:
> Jameson Miller <jameson.miller81@gmail.com> writes:
>
>> Signed-off-by: Jameson Miller <jamill@microsoft.com>
>> ---
>>   Documentation/git-status.txt                      | 21 +++++++++++++++++-
>>   Documentation/technical/api-directory-listing.txt | 27 +++++++++++++++++++----
>>   2 files changed, 43 insertions(+), 5 deletions(-)
>>
>> diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
>> index 9f3a78a36c..fc282e0a92 100644
>> --- a/Documentation/git-status.txt
>> +++ b/Documentation/git-status.txt
>> @@ -97,8 +97,27 @@ configuration variable documented in linkgit:git-config[1].
>>   	(and suppresses the output of submodule summaries when the config option
>>   	`status.submoduleSummary` is set).
>>   
>> ---ignored::
>> +--ignored[=<mode>]::
>>   	Show ignored files as well.
>> ++
>> +The mode parameter is used to specify the handling of ignored files.
>> +It is optional: it defaults to 'traditional'.
>> ++
>> +The possible options are:
>> ++
>> +	- 'traditional' - Shows ignored files and directories, unless
>> +			  --untracked-files=all is specifed, in which case
>> +			  individual files in ignored directories are
>> +			  displayed.
>> +	- 'no'	        - Show no ignored files.
>> +	- 'matching'    - Shows ignored files and directories matching an
>> +			  ignore pattern.
>> ++
>> +When 'matching' mode is specified, paths that explicity match an
>> +ignored pattern are shown. If a directory matches an ignore pattern,
>> +then it is shown, but not paths contained in the ignored directory. If
>> +a directory does not match an ignore pattern, but all contents are
>> +ignored, then the directory is not shown, but all contents are shown.
> Well explained.
>
>> diff --git a/Documentation/technical/api-directory-listing.txt b/Documentation/technical/api-directory-listing.txt
>> index 6c77b4920c..7fae00f44f 100644
>> --- a/Documentation/technical/api-directory-listing.txt
>> +++ b/Documentation/technical/api-directory-listing.txt
>> @@ -22,16 +22,20 @@ The notable options are:
>>   
>>   `flags`::
>>   
>> -	A bit-field of options (the `*IGNORED*` flags are mutually exclusive):
>> +	A bit-field of options:
>>   
>>   `DIR_SHOW_IGNORED`:::
>>   
>> -	Return just ignored files in `entries[]`, not untracked files.
>> +	Return just ignored files in `entries[]`, not untracked
>> +	files. This flag is mutually exclusive with
>> +	`DIR_SHOW_IGNORED_TOO`.
>>   
>>   `DIR_SHOW_IGNORED_TOO`:::
>>   
>> -	Similar to `DIR_SHOW_IGNORED`, but return ignored files in `ignored[]`
>> -	in addition to untracked files in `entries[]`.
>> +	Similar to `DIR_SHOW_IGNORED`, but return ignored files in
>> +	`ignored[]` in addition to untracked files in
>> +	`entries[]`. This flag is mutually exclusive with
>> +	`DIR_SHOW_IGNORED`.
>>   
>>   `DIR_KEEP_UNTRACKED_CONTENTS`:::
>>   
>> @@ -39,6 +43,21 @@ The notable options are:
>>   	untracked contents of untracked directories are also returned in
>>   	`entries[]`.
>>   
>> +`DIR_SHOW_IGNORED_TOO_MODE_MATCHING`:::
>> +
>> +	Only has meaning if `DIR_SHOW_IGNORED_TOO` is also set; if
>> +	this is set, returns ignored files and directories that match
>> +	an exclude pattern. If a directory matches an exclude pattern,
>> +	then the directory is returned and the contained paths are
>> +	not. A directory that does not match an exclude pattern will
>> +	not be returned even if all of its contents are ignored. In
>> +	this case, the contents are returned as individual entries.
>> ++
>> +If this is set, files and directories that explicity match an ignore
>> +pattern are reported. Implicity ignored directories (directories that
>> +do not match an ignore pattern, but whose contents are all ignored)
>> +are not reported, instead all of the contents are reported.
> Makes me wonder if DIR_SHOW_IGNORED* should be splt out into a short
> enum.  We have:
>
>   - Do not show ignored ones (0)
>
>   - Collect ignored ones (DIR_SHOW_IGNORED)
>
>   - Collect ignored and untracked ones separately (DIR_SHOW_IGNORED_TOO)
>
>   - Collect ignored and duntracked ones separately, but limit them to
>     those mach exclude patterns explicitly (DIR_SHOW_IGNORED_TOO|...MODE_MATCHING)
>
> so we need two bits to fit a 4-possiblity enum.
>
> Then we do not have to worry about saying quirky things like A and B
> are incompatible, and C makes sense only when B is set, etc.
I could see a potential for other values for the "show ignored
mode" flags - for example: "NORMAL", "MATCHING", "ALL"... Instead
of making more change at this point in time, how would you feel
about waiting until the next change in this area.

If you would prefer for me to change these enums now, I can do
that.

>
>>   `DIR_COLLECT_IGNORED`:::
>>   
>>   	Special mode for git-add. Return ignored files in `ignored[]` and