Re: [PATCH 2/6] Update documentation for new directory and status logic
flat view
From: Stefan Beller <hidden>
Date: 2017-10-05 21:51:46
On Thu, Oct 5, 2017 at 1:54 PM, [off-list ref] wrote:
quoted hunk ↗ jump to hunk
From: Jameson Miller <redacted> Signed-off-by: Jameson Miller <redacted> --- Documentation/git-status.txt | 22 +++++++++++++++++- Documentation/technical/api-directory-listing.txt | 28 +++++++++++++++++++---- 2 files changed, 45 insertions(+), 5 deletions(-)diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 9f3a78a36c..7d1410ff3f 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt@@ -97,8 +97,28 @@ 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 'default', and if specified, it must be +stuck to the option (e.g. '--ignored=default`, but not `--ignored default`).
Is there a rationale for not accepting `--ignored default`? (It's just the way OPTION_STRING inputs seem to work, but in other cases [c.f. man git gc, search "--prune=" ] this is just implied). Or rather: no need to spell this out explicitly IMHO, as that draws the users attention to it, which might be confusing.
quoted hunk ↗ jump to hunk
++ +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. -z:: Terminate entries with NUL, instead of LF. This impliesdiff --git a/Documentation/technical/api-directory-listing.txt b/Documentation/technical/api-directory-listing.txt index 6c77b4920c..86c981c29c 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 is flag is mutually exclusive with
"is flag is" ?
quoted hunk ↗ jump to hunk
+ `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,22 @@ 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. +
I think to make the asciidoc happy, you'd put a '+ LF' as paragraph delimiter and the subsequent paragraphs are not indented. C.f. Documentation/git-gc.txt "--auto". Oh, screw that. It turns out, this place is the only place in our docs where we use triple colons. So I don't know what I am talking about.
+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.
+
`DIR_COLLECT_IGNORED`:::
Special mode for git-add. Return ignored files in `ignored[]` and
--
2.13.6