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

Previous Next

Package: emacs;

Reported by: Jan Synáček <jan.synacek <at> posteo.org>

Date: Wed, 25 May 2022 14:04:02 UTC

Severity: normal

Tags: patch

Fixed in version 29.1

Done: Dmitry Gutov <dgutov <at> yandex.ru>

Bug is archived. No further changes may be made.

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 55632 in the body.
You can then email your comments to 55632 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

View this report as an mbox folder, status mbox, maintainer mbox


Report forwarded to bug-gnu-emacs <at> gnu.org:
bug#55632; Package emacs. (Wed, 25 May 2022 14:04:03 GMT) Full text and rfc822 format available.

Acknowledgement sent to Jan Synáček <jan.synacek <at> posteo.org>:
New bug report received and forwarded. Copy sent to bug-gnu-emacs <at> gnu.org. (Wed, 25 May 2022 14:04:03 GMT) Full text and rfc822 format available.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Jan Synáček <jan.synacek <at> posteo.org>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] Add new user option project-vc-find-tracked-only
Date: Wed, 25 May 2022 09:08:54 +0000
[Message part 1 (text/plain, inline)]
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'

[0001-Add-new-user-option-project-vc-find-tracked-only.patch (text/patch, attachment)]

Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#55632; Package emacs. (Fri, 27 May 2022 11:02:02 GMT) Full text and rfc822 format available.

Message #8 received at 55632 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Jan Synáček <jan.synacek <at> posteo.org>
Cc: 55632 <at> debbugs.gnu.org, Dmitry Gutov <dgutov <at> yandex.ru>
Subject: Re: bug#55632: [PATCH] Add new user option
 project-vc-find-tracked-only
Date: Fri, 27 May 2022 13:01:26 +0200
Jan Synáček <jan.synacek <at> 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




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#55632; Package emacs. (Fri, 27 May 2022 13:56:02 GMT) Full text and rfc822 format available.

Message #11 received at 55632 <at> debbugs.gnu.org (full text, mbox):

From: Dmitry Gutov <dgutov <at> yandex.ru>
To: Jan Synáček <jan.synacek <at> posteo.org>,
 55632 <at> debbugs.gnu.org
Subject: Re: bug#55632: [PATCH] Add new user option
 project-vc-find-tracked-only
Date: Fri, 27 May 2022 16:55:24 +0300
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.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#55632; Package emacs. (Sun, 29 May 2022 21:42:01 GMT) Full text and rfc822 format available.

Message #14 received at 55632 <at> debbugs.gnu.org (full text, mbox):

From: Dmitry Gutov <dgutov <at> yandex.ru>
To: Jan Synáček <jan.synacek <at> posteo.org>,
 55632 <at> debbugs.gnu.org
Subject: Re: bug#55632: [PATCH] Add new user option
 project-vc-find-tracked-only
Date: Mon, 30 May 2022 00:41:21 +0300
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.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#55632; Package emacs. (Mon, 30 May 2022 10:09:02 GMT) Full text and rfc822 format available.

Message #17 received at 55632 <at> debbugs.gnu.org (full text, mbox):

From: jan.synacek <at> posteo.org
To: Dmitry Gutov <dgutov <at> yandex.ru>
Cc: 55632 <at> debbugs.gnu.org, DG <raaahh <at> gmail.com>
Subject: Re: bug#55632: [PATCH] Add new user option
 project-vc-find-tracked-only
Date: Mon, 30 May 2022 10:08:52 +0000
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.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#55632; Package emacs. (Mon, 30 May 2022 11:01:02 GMT) Full text and rfc822 format available.

Message #20 received at 55632 <at> debbugs.gnu.org (full text, mbox):

From: jan.synacek <at> posteo.org
To: Dmitry Gutov <dgutov <at> yandex.ru>
Cc: 55632 <at> debbugs.gnu.org, DG <raaahh <at> gmail.com>
Subject: Re: bug#55632: [PATCH] Add new user option
 project-vc-find-tracked-only
Date: Mon, 30 May 2022 11:00:07 +0000
[Message part 1 (text/plain, inline)]
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.
[0001-Add-new-user-option-project-vc-include-untracked.patch (text/x-patch, attachment)]

Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#55632; Package emacs. (Tue, 31 May 2022 22:50:02 GMT) Full text and rfc822 format available.

Message #23 received at 55632 <at> debbugs.gnu.org (full text, mbox):

From: Dmitry Gutov <dgutov <at> yandex.ru>
To: jan.synacek <at> posteo.org
Cc: 55632 <at> debbugs.gnu.org, DG <raaahh <at> gmail.com>
Subject: Re: bug#55632: [PATCH] Add new user option
 project-vc-find-tracked-only
Date: Wed, 1 Jun 2022 01:49:08 +0300
On 30.05.2022 14:00, jan.synacek <at> 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.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#55632; Package emacs. (Tue, 31 May 2022 22:58:02 GMT) Full text and rfc822 format available.

Message #26 received at 55632 <at> debbugs.gnu.org (full text, mbox):

From: Dmitry Gutov <dgutov <at> yandex.ru>
To: jan.synacek <at> posteo.org
Cc: 55632 <at> debbugs.gnu.org, DG <raaahh <at> gmail.com>
Subject: Re: bug#55632: [PATCH] Add new user option
 project-vc-find-tracked-only
Date: Wed, 1 Jun 2022 01:57:42 +0300
On 30.05.2022 13:08, jan.synacek <at> 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.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#55632; Package emacs. (Wed, 01 Jun 2022 15:22:02 GMT) Full text and rfc822 format available.

Message #29 received at 55632 <at> debbugs.gnu.org (full text, mbox):

From: jan.synacek <at> posteo.org
To: Dmitry Gutov <dgutov <at> yandex.ru>
Cc: 55632 <at> debbugs.gnu.org, DG <raaahh <at> gmail.com>
Subject: Re: bug#55632: [PATCH] Add new user option
 project-vc-find-tracked-only
Date: Wed, 01 Jun 2022 15:21:12 +0000
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.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#55632; Package emacs. (Thu, 02 Jun 2022 19:03:01 GMT) Full text and rfc822 format available.

Message #32 received at 55632 <at> debbugs.gnu.org (full text, mbox):

From: jan.synacek <at> posteo.org
To: Dmitry Gutov <dgutov <at> yandex.ru>
Cc: 55632 <at> debbugs.gnu.org, DG <raaahh <at> gmail.com>
Subject: Re: bug#55632: [PATCH] Add new user option
 project-vc-find-tracked-only
Date: Thu, 02 Jun 2022 19:01:53 +0000
[Message part 1 (text/plain, inline)]
>> 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.
[0001-Add-new-user-option-project-vc-include-untracked.patch (text/x-patch, attachment)]

Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#55632; Package emacs. (Thu, 02 Jun 2022 19:20:02 GMT) Full text and rfc822 format available.

Message #35 received at 55632 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: jan.synacek <at> posteo.org
Cc: 55632 <at> debbugs.gnu.org, raaahh <at> gmail.com, dgutov <at> yandex.ru
Subject: Re: bug#55632: [PATCH] Add new user option
 project-vc-find-tracked-only
Date: Thu, 02 Jun 2022 22:19:24 +0300
> Cc: 55632 <at> debbugs.gnu.org, DG <raaahh <at> gmail.com>
> Date: Thu, 02 Jun 2022 19:01:53 +0000
> From: jan.synacek <at> 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.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#55632; Package emacs. (Thu, 02 Jun 2022 23:46:02 GMT) Full text and rfc822 format available.

Message #38 received at 55632 <at> debbugs.gnu.org (full text, mbox):

From: Dmitry Gutov <dgutov <at> yandex.ru>
To: Eli Zaretskii <eliz <at> gnu.org>, jan.synacek <at> posteo.org
Cc: 55632 <at> debbugs.gnu.org, raaahh <at> gmail.com
Subject: Re: bug#55632: [PATCH] Add new user option
 project-vc-find-tracked-only
Date: Fri, 3 Jun 2022 02:45:19 +0300
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.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#55632; Package emacs. (Fri, 03 Jun 2022 05:45:01 GMT) Full text and rfc822 format available.

Message #41 received at 55632 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Dmitry Gutov <dgutov <at> yandex.ru>
Cc: jan.synacek <at> posteo.org, 55632 <at> debbugs.gnu.org, raaahh <at> gmail.com
Subject: Re: bug#55632: [PATCH] Add new user option
 project-vc-find-tracked-only
Date: Fri, 03 Jun 2022 08:44:05 +0300
> Date: Fri, 3 Jun 2022 02:45:19 +0300
> Cc: 55632 <at> debbugs.gnu.org, raaahh <at> gmail.com
> From: Dmitry Gutov <dgutov <at> 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.




Reply sent to Dmitry Gutov <dgutov <at> yandex.ru>:
You have taken responsibility. (Sat, 04 Jun 2022 00:38:02 GMT) Full text and rfc822 format available.

Notification sent to Jan Synáček <jan.synacek <at> posteo.org>:
bug acknowledged by developer. (Sat, 04 Jun 2022 00:38:02 GMT) Full text and rfc822 format available.

Message #46 received at 55632-done <at> debbugs.gnu.org (full text, mbox):

From: Dmitry Gutov <dgutov <at> yandex.ru>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: jan.synacek <at> posteo.org, 55632-done <at> debbugs.gnu.org
Subject: Re: bug#55632: [PATCH] Add new user option
 project-vc-find-tracked-only
Date: Sat, 4 Jun 2022 03:37:21 +0300
Version: 29.1

On 03.06.2022 08:44, Eli Zaretskii wrote:
>> Date: Fri, 3 Jun 2022 02:45:19 +0300
>> Cc: 55632 <at> debbugs.gnu.org, raaahh <at> gmail.com
>> From: Dmitry Gutov <dgutov <at> 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.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#55632; Package emacs. (Sat, 04 Jun 2022 06:30:02 GMT) Full text and rfc822 format available.

Message #49 received at 55632 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Dmitry Gutov <dgutov <at> yandex.ru>
Cc: jan.synacek <at> posteo.org, 55632 <at> debbugs.gnu.org
Subject: Re: bug#55632: [PATCH] Add new user option
 project-vc-find-tracked-only
Date: Sat, 04 Jun 2022 09:29:34 +0300
> Date: Sat, 4 Jun 2022 03:37:21 +0300
> Cc: jan.synacek <at> posteo.org, 55632-done <at> debbugs.gnu.org
> From: Dmitry Gutov <dgutov <at> 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.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#55632; Package emacs. (Sat, 04 Jun 2022 09:41:01 GMT) Full text and rfc822 format available.

Message #52 received at 55632 <at> debbugs.gnu.org (full text, mbox):

From: Dmitry Gutov <dgutov <at> yandex.ru>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: jan.synacek <at> posteo.org, 55632 <at> debbugs.gnu.org
Subject: Re: bug#55632: [PATCH] Add new user option
 project-vc-find-tracked-only
Date: Sat, 4 Jun 2022 12:40:31 +0300
On 04.06.2022 09:29, Eli Zaretskii wrote:
>> Date: Sat, 4 Jun 2022 03:37:21 +0300
>> Cc: jan.synacek <at> posteo.org, 55632-done <at> debbugs.gnu.org
>> From: Dmitry Gutov <dgutov <at> 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.




bug archived. Request was from Debbugs Internal Request <help-debbugs <at> gnu.org> to internal_control <at> debbugs.gnu.org. (Sat, 02 Jul 2022 11:24:04 GMT) Full text and rfc822 format available.

This bug report was last modified 1 year and 299 days ago.

Previous Next


GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.