Subject: Re: bug#77974: Manual updates for the VC-aware project backend

From: Dmitry Gutov <[email-masked]>
Date: Mon, 28 Apr 2025 01:39:00 +0300

Hi!

On 27/04/2025 08:12, Sean Whitton wrote:

> On Tue 22 Apr 2025 at 12:51am +03, Dmitry Gutov wrote:
> 
>>   @menu
>> +* VC-Aware Project Backend:: Default project backend.
>>   * Project File Commands::   Commands for handling project files.
>>   * Project Buffer Commands:: Commands for handling project buffers.
>>   * Switching Projects::      Switching between projects.
>>   * Managing Projects::       Managing the project list file.
>>   @end menu
> 
> I agree with Eli that it should probably go last, not just because the
> other parts are backend-agnostic, but also because it is probably less
> useful information to a new user than what comes before.

This makes sense to me indeed, even though the backend itself will 
probably be relevant for >90% of the users who read that text.

>> +It has some performance optimizations for listing the files with some of
>> +the popular VCS systems (currently Git and Mercurial).
>> +
>> +@defopt project-vc-include-untracked
>> +``untracked'' files are considered to be part of the project.  To change
>> +that, you can customize this variable to nil.
>> +@end defopt
> 
> We already have the "unregistered" state in VC.  How about using that?
> 
>      By default, files which are neither registered nor ignored are
>      considered part of this proejct.  Customize this variable to nil to
>      change that.

"Neither registered nor ignored" sounds like the definition for 
"unregistered", actually.

Sounds good to me as a phrasing (might even be more accurate than the 
Git definition I quoted previously).

> ... possibly with a cross-reference to the definitions of the VC terms.

If there is a node to reference, happy to.

> (And maybe we should rename the variable?)

Doesn't seem worth the hassle for us and existing users, TBH.