Subject: Manual updates for the VC-aware project backend

From: Dmitry Gutov <[email-masked]>
Date: Tue, 22 Apr 2025 00:51:30 +0300

Tags: patch

Here are some proposed updates, which create a new node for this backend 
and list some of the options that were until now not mentioned in the 
manual.

Feedback welcome on the general structure (do we want the new node in 
that place?) and the phrasing of the new text as well.

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index c761dc33c86..f6c0cd71dc4 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -1782,20 +1782,18 @@ Projects
 a hierarchy of directories; the top-level directory of the hierarchy
 is known as the @dfn{project root}.
 
-@cindex project back-end
+@cindex project backend
   Whether a given directory is a root of some project is determined by
-the project-specific infrastructure, known as @dfn{project back-end}.
-Emacs currently supports two such back-ends: VC-aware (@pxref{Version
+the project-specific infrastructure, known as @dfn{project backend}.
+Emacs currently supports two such backends: VC-aware (@pxref{Version
 Control}), whereby a VCS repository is considered a project; and EDE
 (@pxref{EDE}).  This is expected to be extended in the future to
 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-aware back-end doesn't
+the project backend.  For example, the VC-aware backend doesn't
 consider ``ignored'' files (@pxref{VC Ignore}) to be part of the
-project.  Also, the VC-aware Project back-end considers ``untracked''
-files by default.  That behavior is controllable with the variable
-@code{project-vc-include-untracked}.
+project.  See its entry below for description and related options.
 
 @cindex current project name on mode line
 @defopt project-mode-line
@@ -1806,12 +1804,58 @@ Projects
 @end defopt
 
 @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
 
+@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.
+
+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
+
+@defopt project-vc-ignores
+Using this variable you can add more ignore patterns to the project, to
+exclude more files from the project's file listing.  The value is a list
+of glob strings.  They can match both regular files and directories.  To
+anchor an entry to the project root, start it with @code{./}.  To match
+directories only, end it with @code{/}.
+@end defopt
+
+@defopt project-vc-merge-submodules
+By default all submodules inside a Git project are considered to be part
+of the parent repository's project.  Customize this to nil to make them
+separate projects.
+@end defopt
+
+@defopt project-vc-name
+This variable allows you to change the automatically detected name of
+the project to a string of your choice.  By default the name is the base
+name of its root directory.
+@end defopt
+
+@defopt project-vc-extra-root-markers
+This variable allows you to set up detection of non-VC projects in this
+backend, and also to have some subdirectories detected as separate
+projects.  The value is a list.
+
+Each element is either a base file name or a glob pattern for such.
+
+Example values: @samp{".dir-locals.el"}, @samp{"package.json"},
+@samp{"requirements.txt}, @samp{"*.gemspec"}.
+@end defopt
+
 @node Project File Commands
 @subsection Project Commands That Operate on Files