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

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