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

From: Sean Whitton <[email-masked]>
Date: Sun, 27 Apr 2025 13:12:49 +0800

Hello,

Thanks for this.

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.

> +@node VC-Aware Project Backend
> +
> +This backend is used by default.  It determines the contents of the
> +project based on the VCS repository's configuration (if any), excluding
> +the ``ignored'' files from the output.

I'd prefer to avoid the scare quotes around both 'ignored' and
'untracked' (I dislike scare quotes almost as much as Eli dislikes the
passive voice ;)).

I think you can just say

    ... excluding files the VCS has been configured to ignore from its
    output.

> +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.

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

(And maybe we should rename the variable?)

-- 
Sean Whitton