bug#55632: [PATCH] Add new user option project-vc-find-tracked-only

bug#55632: [PATCH] Add new user option project-vc-find-tracked-only

[Jan Synáček]

[-- Attachment #1: Type: text/plain, Size: 744 bytes --]

Tags: patch

Tags: patch


Currently, `project-find-file' always includes untracked files, which is
not always the desired behavior. This patch adds a new user option to
make only find the actual project files. By default, the variable is set
to nil, which means the behavior is not changed.

In GNU Emacs 28.1.50 (build 1, x86_64-pc-linux-gnu, GTK+ Version 3.24.33, cairo version 1.17.6)
 of 2022-05-21 built on jsynacek-home
Repository revision: 9e7c0cf57d522b50423880f3a846c52c5509fef9
Repository branch: emacs-28
Windowing system distributor 'The X.Org Foundation', version 11.0.12101003
System Description: Arch Linux

Configured using:
 'configure --with-imagemagick --with-json --with-native-compilation
 --prefix=/home/jsynacek/emacs'


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-new-user-option-project-vc-find-tracked-only.patch --]
[-- Type: text/patch, Size: 3569 bytes --]

From e1562448ca0d95188c4dc9712c8aa4575a5a3bdd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jan=20Syn=C3=A1=C4=8Dek?= <jan.synacek@gmail.com>
Date: Wed, 25 May 2022 10:53:55 +0200
Subject: [PATCH] Add new user option project-vc-find-tracked-only

* doc/emacs/maintaining.texi (Projects): Document it.
* lisp/progmodes/project.el (project--vc-list-files): Use it.
---
 doc/emacs/maintaining.texi |  6 ++++--
 etc/NEWS                   |  5 +++++
 lisp/progmodes/project.el  | 16 +++++++++++-----
 3 files changed, 20 insertions(+), 7 deletions(-)

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 3ddea0ae58..c33b649490 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -1664,8 +1664,10 @@ Projects
 support additional types of projects.
 
   Which files do or don't belong to a project is also determined by
-the project back-end.  For example, the VC back-end doesn't consider
-``ignored'' files (@pxref{VC Ignore}) to be part of the project.
+the project back-end.  For example, the VC back-end only considers
+``ignored'' files (@pxref{VC Ignore}) to be part of the project if
+the value of the variable @code{project-vc-find-tracked-only} is
+non-nil.
 
 @menu
 * Project File Commands::   Commands for handling project files.
diff --git a/etc/NEWS b/etc/NEWS
index 857f300384..abae05749c 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1678,6 +1678,11 @@ Enabling this minor mode turns on hiding header material, like
 'elide-head' does; disabling it shows the header.  The commands
 'elide-head' and 'elide-head-show' are now obsolete.
 
++++
+*** New user option 'project-vc-find-tracked-only'.
+If set to non-nil, 'project-find-file' only considers tracked, that is
+not ignored, files.
+
 ---
 ** The autoarg.el library is now marked obsolete.
 This library provides the 'autoarg-mode' and 'autoarg-kp-mode' minor
diff --git a/lisp/progmodes/project.el b/lisp/progmodes/project.el
index 6c50135358..836d6a1574 100644
--- a/lisp/progmodes/project.el
+++ b/lisp/progmodes/project.el
@@ -382,6 +382,11 @@ project-vc-merge-submodules
   :package-version '(project . "0.2.0")
   :safe #'booleanp)
 
+(defcustom project-vc-find-tracked-only nil
+  "Non-nil makes `project-find-file' consider only tracked files."
+  :type 'boolean
+  :safe #'booleanp)
+
 ;; FIXME: Using the current approach, major modes are supposed to set
 ;; this variable to a buffer-local value.  So we don't have access to
 ;; the "external roots" of language A from buffers of language B, which
@@ -512,8 +517,9 @@ project--vc-list-files
            (args '("-z"))
            (vc-git-use-literal-pathspecs nil)
            files)
-       ;; Include unregistered.
-       (setq args (append args '("-c" "-o" "--exclude-standard")))
+       (setq args (append args
+                          '("-c" "--exclude-standard")
+                          (unless project-vc-find-tracked-only '("-o"))))
        (when extra-ignores
          (setq args (append args
                             (cons "--"
@@ -565,9 +571,9 @@ project--vc-list-files
        (delete-consecutive-dups files)))
     (`Hg
      (let ((default-directory (expand-file-name (file-name-as-directory dir)))
-           args)
-       ;; Include unregistered.
-       (setq args (nconc args '("-mcardu" "--no-status" "-0")))
+           (args (list (concat "-mcard" (unless project-vc-find-tracked-only "u"))
+                       "--no-status"
+                       "-0")))
        (when extra-ignores
          (setq args (nconc args
                            (mapcan
-- 
2.36.1

bug#55632: [PATCH] Add new user option project-vc-find-tracked-only

[Lars Ingebrigtsen]

Jan Synáček <jan.synacek@posteo.org> writes:

> Currently, `project-find-file' always includes untracked files, which is
> not always the desired behavior. This patch adds a new user option to
> make only find the actual project files. By default, the variable is set
> to nil, which means the behavior is not changed.

Makes sense to me, but perhaps Dmitry has some comments here -- added to
the CCs.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#55632: [PATCH] Add new user option project-vc-find-tracked-only

[Dmitry Gutov]

On 25.05.2022 12:08, Jan Synáček wrote:
> Currently, `project-find-file' always includes untracked files, which is
> not always the desired behavior. This patch adds a new user option to
> make only find the actual project files. By default, the variable is set
> to nil, which means the behavior is not changed.

Sure, thanks. I'll review this soon-ish.

As long as you are aware of the user option project-vc-ignores (which 
can be set directory-locally), and are certain that it doesn't satisfy 
your needs.

bug#55632: [PATCH] Add new user option project-vc-find-tracked-only

[Dmitry Gutov]

On 27.05.2022 16:55, Dmitry Gutov wrote:
> On 25.05.2022 12:08, Jan Synáček wrote:
>> Currently, `project-find-file' always includes untracked files, which is
>> not always the desired behavior. This patch adds a new user option to
>> make only find the actual project files. By default, the variable is set
>> to nil, which means the behavior is not changed.
> 
> Sure, thanks. I'll review this soon-ish.

The patch seems functional, thanks. Should also get you better 
performance, if this is the behavior you prefer.

Regarding the naming and the docstring, though: unlike what the 
defcustom says, it will affect also 'project-find-regexp' (i.e. which 
files get searched by this command), and all other features that 
delegate to 'project-files' internally.

So the docstring could use some generalizing. And consider these two 
options for rename:

   - project-vc-tracked-only (defaulting to nil, like in the patch)
   - project-vc-include-untracked (defaulting to t)

The docstring could say something like:

   When non-nil, the VC project backend includes the untracked files.

bug#55632: [PATCH] Add new user option project-vc-find-tracked-only

[jan.synacek]

On 27.05.2022 15:55, Dmitry Gutov wrote:
> On 25.05.2022 12:08, Jan Synáček wrote:
>> Currently, `project-find-file' always includes untracked files, which 
>> is
>> not always the desired behavior. This patch adds a new user option to
>> make only find the actual project files. By default, the variable is 
>> set
>> to nil, which means the behavior is not changed.
> 
> Sure, thanks. I'll review this soon-ish.
> 
> As long as you are aware of the user option project-vc-ignores (which
> can be set directory-locally), and are certain that it doesn't satisfy
> your needs.

Short answer:
Yes, I'm aware, but that option is something different. I don't want to 
add anything to ignore.

Long answer:
This mostly applies to the git and mercurial Emacs backends where the 
untracked files are
used by default now. I think that presenting a "project" as pretty much 
everything in a
folder (unless selectively ignored by using project-vc-ignores, for 
example) only makes
sense if there is no underlying VCS, otherwise it's pretty much 
backwards. Because if
there's already a repo that tracks files, the project should be, in my 
opinion, just the
files in that repo that the underlying VCS sees as tracked. That is the 
default behavior
in git and mercurial as far as I know (I don't use mercurial much, but 
use git a lot). The
VCS also has a mechanism for including untracked files in case the user 
wants to see them
in some operations, and ignoring additional files so that they don't 
count towards those
untracked files. These two options should map 1 to 1 to Emacs custom 
variables, in my
opinion.
So, in summary, I would suggest to change the VC backends that support 
this to behave by
default as the underlying VCS would behave and use custom variables to 
add additional
tweaks for non-default stuff. Of course, that is out of scope for this 
patch.

bug#55632: [PATCH] Add new user option project-vc-find-tracked-only

[jan.synacek]

[-- Attachment #1: Type: text/plain, Size: 1296 bytes --]

On 29.05.2022 23:41, Dmitry Gutov wrote:
> On 27.05.2022 16:55, Dmitry Gutov wrote:
>> On 25.05.2022 12:08, Jan Synáček wrote:
>>> Currently, `project-find-file' always includes untracked files, which 
>>> is
>>> not always the desired behavior. This patch adds a new user option to
>>> make only find the actual project files. By default, the variable is 
>>> set
>>> to nil, which means the behavior is not changed.
>> 
>> Sure, thanks. I'll review this soon-ish.
> 
> The patch seems functional, thanks. Should also get you better
> performance, if this is the behavior you prefer.
> 
> Regarding the naming and the docstring, though: unlike what the
> defcustom says, it will affect also 'project-find-regexp' (i.e. which
> files get searched by this command), and all other features that
> delegate to 'project-files' internally.
> 
> So the docstring could use some generalizing. And consider these two
> options for rename:
> 
>   - project-vc-tracked-only (defaulting to nil, like in the patch)
>   - project-vc-include-untracked (defaulting to t)
> 
> The docstring could say something like:
> 
>   When non-nil, the VC project backend includes the untracked files.

Thank you for the review. I addressed your comments in the new version 
of the patch.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-new-user-option-project-vc-include-untracked.patch --]
[-- Type: text/x-patch; name=0001-Add-new-user-option-project-vc-include-untracked.patch, Size: 3437 bytes --]

From be368647783da8c12e2ea175401dd7f84d0cd4c4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jan=20Syn=C3=A1=C4=8Dek?= <jan.synacek@gmail.com>
Date: Wed, 25 May 2022 10:53:55 +0200
Subject: [PATCH] Add new user option project-vc-include-untracked

* doc/emacs/maintaining.texi (Projects): Document it.
* lisp/progmodes/project.el (project--vc-list-files): Use it.
---
 doc/emacs/maintaining.texi |  3 +++
 etc/NEWS                   |  4 ++++
 lisp/progmodes/project.el  | 16 +++++++++++-----
 3 files changed, 18 insertions(+), 5 deletions(-)

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 3ddea0ae58..6f0da63837 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -1666,6 +1666,9 @@ Projects
   Which files do or don't belong to a project is also determined by
 the project back-end.  For example, the VC back-end doesn't consider
 ``ignored'' files (@pxref{VC Ignore}) to be part of the project.
+Also, some VC back-ends consider ``untracked'' files by default.
+That behavior is controllable with the variable
+@code{project-vc-include-untracked}.
 
 @menu
 * Project File Commands::   Commands for handling project files.
diff --git a/etc/NEWS b/etc/NEWS
index 5987acdac9..b695d63020 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1693,6 +1693,10 @@ Enabling this minor mode turns on hiding header material, like
 'elide-head' does; disabling it shows the header.  The commands
 'elide-head' and 'elide-head-show' are now obsolete.
 
++++
+*** New user option 'project-vc-include-untracked'.
+When non-nil, the VC project backend includes the untracked files.
+
 ---
 ** The autoarg.el library is now marked obsolete.
 This library provides the 'autoarg-mode' and 'autoarg-kp-mode' minor
diff --git a/lisp/progmodes/project.el b/lisp/progmodes/project.el
index 6c50135358..e488fa145e 100644
--- a/lisp/progmodes/project.el
+++ b/lisp/progmodes/project.el
@@ -382,6 +382,11 @@ project-vc-merge-submodules
   :package-version '(project . "0.2.0")
   :safe #'booleanp)
 
+(defcustom project-vc-include-untracked t
+  "When non-nil, the VC project backend includes the untracked files."
+  :type 'boolean
+  :safe #'booleanp)
+
 ;; FIXME: Using the current approach, major modes are supposed to set
 ;; this variable to a buffer-local value.  So we don't have access to
 ;; the "external roots" of language A from buffers of language B, which
@@ -512,8 +517,9 @@ project--vc-list-files
            (args '("-z"))
            (vc-git-use-literal-pathspecs nil)
            files)
-       ;; Include unregistered.
-       (setq args (append args '("-c" "-o" "--exclude-standard")))
+       (setq args (append args
+                          '("-c" "--exclude-standard")
+                          (when project-vc-include-untracked '("-o"))))
        (when extra-ignores
          (setq args (append args
                             (cons "--"
@@ -565,9 +571,9 @@ project--vc-list-files
        (delete-consecutive-dups files)))
     (`Hg
      (let ((default-directory (expand-file-name (file-name-as-directory dir)))
-           args)
-       ;; Include unregistered.
-       (setq args (nconc args '("-mcardu" "--no-status" "-0")))
+           (args (list (concat "-mcard" (when project-vc-include-untracked "u"))
+                       "--no-status"
+                       "-0")))
        (when extra-ignores
          (setq args (nconc args
                            (mapcan
-- 
2.36.1

bug#55632: [PATCH] Add new user option project-vc-find-tracked-only

[Dmitry Gutov]

On 30.05.2022 14:00, jan.synacek@posteo.org wrote:
> Thank you for the review. I addressed your comments in the new version 
> of the patch.

Thanks.

One last thing here. The manual addition says:

+Also, some VC back-ends consider ``untracked'' files by default.
+That behavior is controllable with the variable
+@code{project-vc-include-untracked}.

Should that say "some Project back-ends ..."? Or better yet, "the VC 
Project back-end". Because that's the only one in the core that has any 
notion of "untracked files".

And that behavior is so for all VC backends, with Git and Hg simply 
having custom file listing code (for better performance). The rest 
delegate to 'find', only picking up the list of ignores (like bzrignore, 
svnignore, etc).

Consequently, the new variable will only affect the VC Project backend's 
behavior only with Hg and Git.

bug#55632: [PATCH] Add new user option project-vc-find-tracked-only

[Dmitry Gutov]

On 30.05.2022 13:08, jan.synacek@posteo.org wrote:
> On 27.05.2022 15:55, Dmitry Gutov wrote:
>> On 25.05.2022 12:08, Jan Synáček wrote:
>>> Currently, `project-find-file' always includes untracked files, which is
>>> not always the desired behavior. This patch adds a new user option to
>>> make only find the actual project files. By default, the variable is set
>>> to nil, which means the behavior is not changed.
>>
>> Sure, thanks. I'll review this soon-ish.
>>
>> As long as you are aware of the user option project-vc-ignores (which
>> can be set directory-locally), and are certain that it doesn't satisfy
>> your needs.
> 
> Short answer:
> Yes, I'm aware, but that option is something different. I don't want to 
> add anything to ignore.

That's cool.

> Long answer:
> This mostly applies to the git and mercurial Emacs backends where the 
> untracked files are
> used by default now. I think that presenting a "project" as pretty much 
> everything in a
> folder (unless selectively ignored by using project-vc-ignores, for 
> example)

^^^or included in .gitignore or .hgignore

> only makes
> sense if there is no underlying VCS, otherwise it's pretty much 
> backwards. Because if
> there's already a repo that tracks files, the project should be, in my 
> opinion, just the
> files in that repo that the underlying VCS sees as tracked. That is the 
> default behavior
> in git and mercurial as far as I know (I don't use mercurial much, but 
> use git a lot). The
> VCS also has a mechanism for including untracked files in case the user 
> wants to see them
> in some operations, and ignoring additional files so that they don't 
> count towards those
> untracked files. These two options should map 1 to 1 to Emacs custom 
> variables, in my
> opinion.
> So, in summary, I would suggest to change the VC backends that support 
> this to behave by
> default as the underlying VCS would behave and use custom variables to 
> add additional
> tweaks for non-default stuff. Of course, that is out of scope for this 
> patch.

Here's the reasoning I used:

- Almost everyone works with a VCS. Let's use Git in this example.
- You start working on a new feature to your project. You add a couple 
of new source files, write tests for them. Haven't checked them in yet.
- To switch between the project files you probably use 
'project-find-file'. You are likely to use that function (or 
'project-find-regexp'), etc, during the initial phase of developing a 
new feature as well, and to jump between the newly created files, and 
their tests, etc.
- That creates expectation that new files should be considered part of 
the project. And overall, false positive is usually better for this kind 
of thing than false negative (not finding something that you expect to 
be there).

Using .xyzignore files to list files that are junk/unimportant/etc is 
par for the course when using a VCS. Until a file is added there (or 
checked in), it's very visible in 'git status'. Having them omitted from 
the list of project files would make them much less "visible", 
contradicting Git's (or Mercurial or etc) behavior.

bug#55632: [PATCH] Add new user option project-vc-find-tracked-only

[jan.synacek]

On 01.06.2022 00:57, Dmitry Gutov wrote:
> Here's the reasoning I used:
> 
> - Almost everyone works with a VCS. Let's use Git in this example.
> - You start working on a new feature to your project. You add a couple
> of new source files, write tests for them. Haven't checked them in
> yet.
> - To switch between the project files you probably use
> 'project-find-file'. You are likely to use that function (or
> 'project-find-regexp'), etc, during the initial phase of developing a
> new feature as well, and to jump between the newly created files, and
> their tests, etc.
> - That creates expectation that new files should be considered part of
> the project. And overall, false positive is usually better for this
> kind of thing than false negative (not finding something that you
> expect to be there).
> 
> Using .xyzignore files to list files that are junk/unimportant/etc is
> par for the course when using a VCS. Until a file is added there (or
> checked in), it's very visible in 'git status'. Having them omitted
> from the list of project files would make them much less "visible",
> contradicting Git's (or Mercurial or etc) behavior.

Ok, fair enough. I guess this makes sense as well.

bug#55632: [PATCH] Add new user option project-vc-find-tracked-only

[jan.synacek]

[-- Attachment #1: Type: text/plain, Size: 852 bytes --]

>> Thank you for the review. I addressed your comments in the new version 
>> of the patch.
> 
> Thanks.
> 
> One last thing here. The manual addition says:
> 
> +Also, some VC back-ends consider ``untracked'' files by default.
> +That behavior is controllable with the variable
> +@code{project-vc-include-untracked}.
> 
> Should that say "some Project back-ends ..."? Or better yet, "the VC
> Project back-end". Because that's the only one in the core that has
> any notion of "untracked files".
> 
> And that behavior is so for all VC backends, with Git and Hg simply
> having custom file listing code (for better performance). The rest
> delegate to 'find', only picking up the list of ignores (like
> bzrignore, svnignore, etc).
> 
> Consequently, the new variable will only affect the VC Project
> backend's behavior only with Hg and Git.

Fixed.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-new-user-option-project-vc-include-untracked.patch --]
[-- Type: text/x-patch; name=0001-Add-new-user-option-project-vc-include-untracked.patch, Size: 3443 bytes --]

From ff7eb6529019e98eae320c907c1e9683a21d627e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jan=20Syn=C3=A1=C4=8Dek?= <jan.synacek@gmail.com>
Date: Thu, 2 Jun 2022 20:59:53 +0200
Subject: [PATCH] Add new user option project-vc-include-untracked

* doc/emacs/maintaining.texi (Projects): Document it.
* lisp/progmodes/project.el (project--vc-list-files): Use it.
---
 doc/emacs/maintaining.texi |  3 +++
 etc/NEWS                   |  4 ++++
 lisp/progmodes/project.el  | 16 +++++++++++-----
 3 files changed, 18 insertions(+), 5 deletions(-)

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 3ddea0ae58..edc5acbd65 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -1666,6 +1666,9 @@ Projects
   Which files do or don't belong to a project is also determined by
 the project back-end.  For example, the VC back-end doesn't consider
 ``ignored'' files (@pxref{VC Ignore}) to be part of the project.
+Also, the VC Project back-end considers ``untracked'' files by default.
+That behavior is controllable with the variable
+@code{project-vc-include-untracked}.
 
 @menu
 * Project File Commands::   Commands for handling project files.
diff --git a/etc/NEWS b/etc/NEWS
index 71c19c06b4..3867fc8829 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1707,6 +1707,10 @@ Enabling this minor mode turns on hiding header material, like
 'elide-head' does; disabling it shows the header.  The commands
 'elide-head' and 'elide-head-show' are now obsolete.
 
++++
+*** New user option 'project-vc-include-untracked'.
+When non-nil, the VC project backend includes the untracked files.
+
 ---
 ** The autoarg.el library is now marked obsolete.
 This library provides the 'autoarg-mode' and 'autoarg-kp-mode' minor
diff --git a/lisp/progmodes/project.el b/lisp/progmodes/project.el
index 4dc4762176..49e07fe840 100644
--- a/lisp/progmodes/project.el
+++ b/lisp/progmodes/project.el
@@ -382,6 +382,11 @@ project-vc-merge-submodules
   :package-version '(project . "0.2.0")
   :safe #'booleanp)
 
+(defcustom project-vc-include-untracked t
+  "When non-nil, the VC project backend includes the untracked files."
+  :type 'boolean
+  :safe #'booleanp)
+
 ;; FIXME: Using the current approach, major modes are supposed to set
 ;; this variable to a buffer-local value.  So we don't have access to
 ;; the "external roots" of language A from buffers of language B, which
@@ -512,8 +517,9 @@ project--vc-list-files
            (args '("-z"))
            (vc-git-use-literal-pathspecs nil)
            files)
-       ;; Include unregistered.
-       (setq args (append args '("-c" "-o" "--exclude-standard")))
+       (setq args (append args
+                          '("-c" "--exclude-standard")
+                          (when project-vc-include-untracked '("-o"))))
        (when extra-ignores
          (setq args (append args
                             (cons "--"
@@ -565,9 +571,9 @@ project--vc-list-files
        (delete-consecutive-dups files)))
     (`Hg
      (let ((default-directory (expand-file-name (file-name-as-directory dir)))
-           args)
-       ;; Include unregistered.
-       (setq args (nconc args '("-mcardu" "--no-status" "-0")))
+           (args (list (concat "-mcard" (when project-vc-include-untracked "u"))
+                       "--no-status"
+                       "-0")))
        (when extra-ignores
          (setq args (nconc args
                            (mapcan
-- 
2.36.1

bug#55632: [PATCH] Add new user option project-vc-find-tracked-only

[Eli Zaretskii]

> Cc: 55632@debbugs.gnu.org, DG <raaahh@gmail.com>
> Date: Thu, 02 Jun 2022 19:01:53 +0000
> From: jan.synacek@posteo.org
> 
> ++++
> +*** New user option 'project-vc-include-untracked'.
> +When non-nil, the VC project backend includes the untracked files.

Can we please tell more about what does "include untracked files"
mean?  Include where and in what sense?  Bonus points for explaining
this without ever alluding to "backend", as that is not necessarily a
user-level concept in this case.

Also, is it "VC project backend" or "Project's VC backend"?

> +(defcustom project-vc-include-untracked t
> +  "When non-nil, the VC project backend includes the untracked files."
> +  :type 'boolean
> +  :safe #'booleanp)

Same here.  And new defcustom's should have a :version tag.

> -       ;; Include unregistered.
> -       (setq args (append args '("-c" "-o" "--exclude-standard")))
> +       (setq args (append args
> +                          '("-c" "--exclude-standard")
> +                          (when project-vc-include-untracked '("-o"))))
                              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
I think 'when' is overkill here, because 'if' will do the job.

> -       ;; Include unregistered.
> -       (setq args (nconc args '("-mcardu" "--no-status" "-0")))
> +           (args (list (concat "-mcard" (when project-vc-include-untracked "u"))
> +                       "--no-status"
> +                       "-0")))

Likewise here.

Thank you for working on this.

bug#55632: [PATCH] Add new user option project-vc-find-tracked-only

[Dmitry Gutov]

On 02.06.2022 22:19, Eli Zaretskii wrote:
> Can we please tell more about what does "include untracked files"
> mean?  Include where and in what sense?

Has them considered to be part of the project. Which in practice means 
including them in a project's list of files. For the purposes for 
project-find-file, project-find-regexp, and all other commands that 
build on top of 'project-files'.

How would you phrase that better?

> Bonus points for explaining
> this without ever alluding to "backend", as that is not necessarily a
> user-level concept in this case.

The variable only affects a particular backend. It's only meaningful 
when there is a VCS anyway.

> Also, is it "VC project backend" or "Project's VC backend"?

I would say both mean the same thing, but the latter seems to be more 
unambiguous.

bug#55632: [PATCH] Add new user option project-vc-find-tracked-only

[Eli Zaretskii]

> Date: Fri, 3 Jun 2022 02:45:19 +0300
> Cc: 55632@debbugs.gnu.org, raaahh@gmail.com
> From: Dmitry Gutov <dgutov@yandex.ru>
> 
> On 02.06.2022 22:19, Eli Zaretskii wrote:
> > Can we please tell more about what does "include untracked files"
> > mean?  Include where and in what sense?
> 
> Has them considered to be part of the project. Which in practice means 
> including them in a project's list of files. For the purposes for 
> project-find-file, project-find-regexp, and all other commands that 
> build on top of 'project-files'.
> 
> How would you phrase that better?

Something like this:

  If non-nil, files untracked by a VCS are considered to be part of
  the project by a VC project based on that VCS.

> > Bonus points for explaining
> > this without ever alluding to "backend", as that is not necessarily a
> > user-level concept in this case.
> 
> The variable only affects a particular backend. It's only meaningful 
> when there is a VCS anyway.

I understand.  My point was to avoid using the word "backend" in
user-level documentation, as much as possible.

> > Also, is it "VC project backend" or "Project's VC backend"?
> 
> I would say both mean the same thing, but the latter seems to be more 
> unambiguous.

Well, if you are okay with my alternative wording above, it solves
this problem as well.

bug#55632: [PATCH] Add new user option project-vc-find-tracked-only

[Dmitry Gutov]

Version: 29.1

On 03.06.2022 08:44, Eli Zaretskii wrote:
>> Date: Fri, 3 Jun 2022 02:45:19 +0300
>> Cc: 55632@debbugs.gnu.org, raaahh@gmail.com
>> From: Dmitry Gutov <dgutov@yandex.ru>
>>
>> On 02.06.2022 22:19, Eli Zaretskii wrote:
>>> Can we please tell more about what does "include untracked files"
>>> mean?  Include where and in what sense?
>>
>> Has them considered to be part of the project. Which in practice means
>> including them in a project's list of files. For the purposes for
>> project-find-file, project-find-regexp, and all other commands that
>> build on top of 'project-files'.
>>
>> How would you phrase that better?
> 
> Something like this:
> 
>    If non-nil, files untracked by a VCS are considered to be part of
>    the project by a VC project based on that VCS.

A bit unwieldy IMHO, but I don't mind. As long as you only objected to 
the NEWS entry.

The addition to the manual, which is also usually considered user-level 
text, only continues the style of the preceding sentence. And the 
docstring has to be precise either way.

>>> Bonus points for explaining
>>> this without ever alluding to "backend", as that is not necessarily a
>>> user-level concept in this case.
>>
>> The variable only affects a particular backend. It's only meaningful
>> when there is a VCS anyway.
> 
> I understand.  My point was to avoid using the word "backend" in
> user-level documentation, as much as possible.
> 
>>> Also, is it "VC project backend" or "Project's VC backend"?
>>
>> I would say both mean the same thing, but the latter seems to be more
>> unambiguous.
> 
> Well, if you are okay with my alternative wording above, it solves
> this problem as well.

Amended and pushed, thank you both.

bug#55632: [PATCH] Add new user option project-vc-find-tracked-only

[Eli Zaretskii]

> Date: Sat, 4 Jun 2022 03:37:21 +0300
> Cc: jan.synacek@posteo.org, 55632-done@debbugs.gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> 
> >    If non-nil, files untracked by a VCS are considered to be part of
> >    the project by a VC project based on that VCS.
> 
> A bit unwieldy IMHO, but I don't mind.

What is unwieldy there?

> As long as you only objected to the NEWS entry.
> 
> The addition to the manual, which is also usually considered user-level 
> text, only continues the style of the preceding sentence.

The manual explains what a back-end is, including what is the VC
back-end, so I didn't mind to using it there.

bug#55632: [PATCH] Add new user option project-vc-find-tracked-only

[Dmitry Gutov]

On 04.06.2022 09:29, Eli Zaretskii wrote:
>> Date: Sat, 4 Jun 2022 03:37:21 +0300
>> Cc: jan.synacek@posteo.org, 55632-done@debbugs.gnu.org
>> From: Dmitry Gutov <dgutov@yandex.ru>
>>
>>>     If non-nil, files untracked by a VCS are considered to be part of
>>>     the project by a VC project based on that VCS.
>>
>> A bit unwieldy IMHO, but I don't mind.
> 
> What is unwieldy there?

I had to re-read it a couple of times to understand and verify its 
meaning. While the original was shorter and just as informative.

Not something I want to argue about. If the present entry looks easy to 
understand to you, then it's fine by me.

>> As long as you only objected to the NEWS entry.
>>
>> The addition to the manual, which is also usually considered user-level
>> text, only continues the style of the preceding sentence.
> 
> The manual explains what a back-end is, including what is the VC
> back-end, so I didn't mind to using it there.

Cool.