From 561e9fb91bba98616f6d7ea3818727c1cdd2d853 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 21 Mar 2020 13:26:19 +0200 Subject: [PATCH] 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 c3cb37e6a6d..6ef4ca63ae7 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 a6f66f6e7f3..ebcdddfcae3 100644 --- a/doc/emacs/maintaining.texi +++ b/doc/emacs/maintaining.texi @@ -13,6 +13,9 @@ large-size programs and packages. These features include: 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 b41541c715f..d3f27e328e7 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 ccd8cc049d4..f4678681858 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]'." (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))) -- 2.39.5