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

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

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