[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
emacs-27 561e9fb: Improve documentation of project.el commands
From: |
Eli Zaretskii |
Subject: |
emacs-27 561e9fb: Improve documentation of project.el commands |
Date: |
Sat, 21 Mar 2020 07:26:59 -0400 (EDT) |
branch: emacs-27
commit 561e9fb91bba98616f6d7ea3818727c1cdd2d853
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>
Improve documentation of project.el commands
* lisp/progmodes/project.el (project-find-regexp): Require 'grep'
to be able to call 'grep-read-files'.
(project-search, project-query-replace-regexp): Doc fixes.
* doc/emacs/maintaining.texi (Projects): New section.
* doc/emacs/emacs.texi (Top): Add "Projects" to the detailed menu.
---
doc/emacs/emacs.texi | 1 +
doc/emacs/maintaining.texi | 75 ++++++++++++++++++++++++++++++++++++++++++++++
etc/NEWS | 3 ++
lisp/progmodes/project.el | 11 ++++---
4 files changed, 86 insertions(+), 4 deletions(-)
diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index c3cb37e..6ef4ca6 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -785,6 +785,7 @@ GDB Graphical Interface
Maintaining Large Programs
* Version Control:: Using version control systems.
+* Projects:: Commands for handling source files in a project.
* Change Log:: Maintaining a change history for your program.
* Xref:: Find definitions and references of any function,
method, struct, macro, @dots{} in your program.
diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index a6f66f6..ebcdddf 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -14,6 +14,9 @@ Unified interface to Support for Version Control Systems
(@acronym{VCS}) that record the history of changes to source files.
@item
+Commands for handling programming projects.
+
+@item
A specialized mode for maintaining @file{ChangeLog} files that provide
a chronological log of program changes.
@@ -38,6 +41,7 @@ Lisp Regression Testing}).
@menu
* Version Control:: Using version control systems.
+* Projects:: Commands for handling source files in a project.
* Change Log:: Maintaining a change history for your program.
* Xref:: Find definitions and references of any function,
method, struct, macro, @dots{} in your program.
@@ -1630,6 +1634,77 @@ different revision with @kbd{C-u C-x v v}.
@include vc1-xtra.texi
@end ifnottex
+@node Projects
+@section Working with Projects
+@cindex projects
+
+@cindex project root
+ A @dfn{project} is a collection of files used for producing one or
+more programs. Files that belong to a project are typically stored in
+a hierarchy of directories; the top-level directory of the hierarchy
+is known as the @dfn{project root}.
+
+@cindex project back-end
+ 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 (@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 back-end doesn't consider
+``ignored'' files (@pxref{VC Ignore}) to be part of the project.
+
+ Emacs provides commands for handling project files conveniently.
+This section describes these commands.
+
+@cindex current project
+ All of the commands described here share the notion of the
+@dfn{current project}. The current project is determined by the
+@code{default-directory} (@pxref{File Names}) of the buffer that is
+the current buffer when the command is invoked. If that directory
+doesn't seem to belong to a recognizable project, these commands
+prompt you for the project directory.
+
+@findex project-find-file
+ The command @code{project-find-file} is a convenient way of visiting
+files (@pxref{Visiting}) that belong to the current project. Unlike
+@kbd{C-x C-f}, this command doesn't require to type the full file name
+of the file to visit, you can type only the file's base name (i.e.,
+omit the leading directories). In addition, the completion candidates
+considered by the command include only the files belonging to the
+current project, and nothing else. If there's a file name at point,
+this command offers that file as the default to visit.
+
+@findex project-find-regexp
+ The command @code{project-find-regexp} is similar to @code{rgrep}
+(@pxref{Grep Searching}), but it searches only the files that belong
+to the current project. The command prompts for the regular
+expression to search, and pops up an Xref mode buffer with the search
+results, where you can select a match using the Xref mode commands
+(@pxref{Xref Commands}). When invoked with a prefix argument, this
+command additionally prompts for the base directory from which to
+start the search; this allows, for example, to limit the search only
+to project files under a certain subdirectory of the project root.
+
+@findex project-search
+ @kbd{M-x project-search} is an interactive variant of
+@code{project-find-regexp}. It prompts for a regular expression to
+search in the current project's files, but instead of finding all the
+matches and displaying them, it stops when it finds a match and visits
+the matched file at the locus of the match, allowing you to edit the
+matched file. To find the rest of the matches, type @w{@kbd{M-x
+fileloop-continue @key{RET}}}.
+
+@findex project-query-replace-regexp
+ @kbd{M-x project-query-replace-regexp} is similar to
+@code{project-search}, but it prompts you for whether to replace each
+match it finds, like @code{query-replace} does (@pxref{Query
+Replace}), and continues to the next match after you respond. If your
+response causes Emacs to exit the query-replace loop, you can later
+continue with @w{@kbd{M-x fileloop-continue @key{RET}}}.
+
@node Change Log
@section Change Logs
diff --git a/etc/NEWS b/etc/NEWS
index b41541c..d3f27e3 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -978,7 +978,10 @@ The mode is automatically enabled in files that start with
the
** project.el
++++
*** New commands 'project-search' and 'project-query-replace-regexp'.
+
+---
*** New user option 'project-read-file-name-function'.
** Etags
diff --git a/lisp/progmodes/project.el b/lisp/progmodes/project.el
index ccd8cc0..f467868 100644
--- a/lisp/progmodes/project.el
+++ b/lisp/progmodes/project.el
@@ -437,6 +437,7 @@ triggers completion when entering a pattern, including it
requires quoting, e.g. `\\[quoted-insert]<space>'."
(interactive (list (project--read-regexp)))
(require 'xref)
+ (require 'grep)
(let* ((pr (project-current t))
(files
(if (not current-prefix-arg)
@@ -606,7 +607,8 @@ PREDICATE, HIST, and DEFAULT have the same meaning as in
(defun project-search (regexp)
"Search for REGEXP in all the files of the project.
Stops when a match is found.
-To continue searching for next match, use command \\[fileloop-continue]."
+To continue searching for the next match, use the
+command \\[fileloop-continue]."
(interactive "sSearch (regexp): ")
(fileloop-initialize-search
regexp (project-files (project-current t)) 'default)
@@ -614,9 +616,10 @@ To continue searching for next match, use command
\\[fileloop-continue]."
;;;###autoload
(defun project-query-replace-regexp (from to)
- "Search for REGEXP in all the files of the project.
-Stops when a match is found.
-To continue searching for next match, use command \\[fileloop-continue]."
+ "Query-replace REGEXP in all the files of the project.
+Stops when a match is found and prompts for whether to replace it.
+If you exit the query-replace, you can later continue the query-replace
+loop using the command \\[fileloop-continue]."
(interactive
(pcase-let ((`(,from ,to)
(query-replace-read-args "Query replace (regexp)" t t)))
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- emacs-27 561e9fb: Improve documentation of project.el commands,
Eli Zaretskii <=