Jameson Miller <jameson.mille...@gmail.com> writes: > Signed-off-by: Jameson Miller <jam...@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. > `DIR_COLLECT_IGNORED`::: > > Special mode for git-add. Return ignored files in `ignored[]` and
