git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: Junio C Hamano <gitster@pobox.com>
To: Jameson Miller <jameson.miller81@gmail.com>
Cc: bmwill@google.com, git@vger.kernel.org, jamill@microsoft.com,
	peff@peff.net, sbeller@google.com
Subject: Re: [PATCH v2 2/5] Update documentation for new directory and status logic
Date: Thu, 12 Oct 2017 11:55:33 +0900	[thread overview]
Message-ID: <xmqqtvz513dm.fsf@gitster.mtv.corp.google.com> (raw)
In-Reply-To: <20171011133504.15049-3-jamill@microsoft.com> (Jameson Miller's message of "Wed, 11 Oct 2017 09:35:01 -0400")

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.

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

  reply	other threads:[~2017-10-12  2:55 UTC|newest]

Thread overview: 49+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2017-10-05 20:54 [PATCH 0/6] Teach Status options around showing ignored files jameson.miller81
2017-10-05 20:54 ` [PATCH 1/6] Teach status " jameson.miller81
2017-10-05 20:54 ` [PATCH 2/6] Update documentation for new directory and status logic jameson.miller81
2017-10-05 21:51   ` Stefan Beller
2017-10-05 20:54 ` [PATCH 3/6] Add tests for git status `--ignored=matching` jameson.miller81
2017-10-05 21:59   ` Stefan Beller
2017-10-05 20:54 ` [PATCH 4/6] Expand support for ignored arguments on status jameson.miller81
2017-10-05 20:54 ` [PATCH 5/6] Add tests around status handling of ignored arguments jameson.miller81
2017-10-05 20:54 ` [PATCH 6/6] Handle unsupported combination status arguments jameson.miller81
2017-10-05 22:08   ` Stefan Beller
2017-10-05 21:16 ` [PATCH 0/6] Teach Status options around showing ignored files Jonathan Nieder
2017-10-05 21:22   ` Jameson Miller
2017-10-11 13:34 ` [PATCH v2 0/5] " Jameson Miller
2017-10-11 13:35   ` [PATCH v2 1/5] Teach status " Jameson Miller
2017-10-12  2:49     ` Junio C Hamano
2017-10-12 20:15       ` Jameson Miller
2017-10-11 13:35   ` [PATCH v2 2/5] Update documentation for new directory and status logic Jameson Miller
2017-10-12  2:55     ` Junio C Hamano [this message]
2017-10-12 20:54       ` Jameson Miller
2017-10-13  0:42         ` Junio C Hamano
2017-10-11 13:35   ` [PATCH v2 3/5] Add tests for git status `--ignored=matching` Jameson Miller
2017-10-11 13:35   ` [PATCH v2 4/5] Expand support for ignored arguments on status Jameson Miller
2017-10-12  3:58     ` Junio C Hamano
2017-10-11 13:35   ` [PATCH v2 5/5] Add tests around status handling of ignored arguments Jameson Miller
2017-10-12  4:06     ` Junio C Hamano
2017-10-12 20:16       ` Jameson Miller
2017-10-13  0:49         ` Junio C Hamano
2017-10-12  2:33   ` [PATCH v2 0/5] Teach Status options around showing ignored files Junio C Hamano
2017-10-12 20:20     ` Jameson Miller
2017-10-19 16:05 ` [PATCH v3 0/4] status: add option to show ignored files differently Jameson Miller
2017-10-19 16:05   ` [PATCH v3 1/4] " Jameson Miller
2017-10-23  3:34     ` Junio C Hamano
2017-10-19 16:05   ` [PATCH v3 2/4] status: report matching ignored and normal untracked Jameson Miller
2017-10-19 16:06   ` [PATCH v3 3/4] status: document options to show matching ignored files Jameson Miller
2017-10-19 16:06   ` [PATCH v3 4/4] status: test --ignored=matching Jameson Miller
2017-10-19 19:33     ` Stefan Beller
2017-10-22  2:10     ` Junio C Hamano
2017-10-23  4:46   ` [PATCH v3 0/4] status: add option to show ignored files differently Junio C Hamano
2017-10-23 17:05 ` [PATCH v4 " Jameson Miller
2017-10-23 17:05   ` [PATCH v4 1/4] " Jameson Miller
2017-10-23 17:05   ` [PATCH v4 2/4] status: report matching ignored and normal untracked Jameson Miller
2017-10-23 17:05   ` [PATCH v4 3/4] status: document options to show matching ignored files Jameson Miller
2017-10-23 17:05   ` [PATCH v4 4/4] status: test ignored modes Jameson Miller
2017-10-30 17:21 ` [PATCH v5 0/4] status: add option to show ignored files differently jameson.miller81
2017-10-30 17:21   ` [PATCH v5 1/4] " jameson.miller81
2017-10-30 17:21   ` [PATCH v5 2/4] status: report matching ignored and normal untracked jameson.miller81
2017-10-30 17:21   ` [PATCH v5 3/4] status: document options to show matching ignored files jameson.miller81
2017-10-30 17:21   ` [PATCH v5 4/4] status: test ignored modes jameson.miller81
2017-10-31  3:16   ` [PATCH v5 0/4] status: add option to show ignored files differently Junio C Hamano

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=xmqqtvz513dm.fsf@gitster.mtv.corp.google.com \
    --to=gitster@pobox.com \
    --cc=bmwill@google.com \
    --cc=git@vger.kernel.org \
    --cc=jameson.miller81@gmail.com \
    --cc=jamill@microsoft.com \
    --cc=peff@peff.net \
    --cc=sbeller@google.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).