From: Eli Zaretskii Date: Sat, 25 Jul 2020 09:28:05 +0000 (+0300) Subject: Update and improve documentation of project.el commands X-Git-Tag: emacs-28.0.90~6938 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=3b44829823f43d3736b8ec9db2258eeff7f6c16a;p=emacs.git Update and improve documentation of project.el commands * doc/emacs/custom.texi (Prefix Keymaps): Document 'project-prefix-map'. * doc/emacs/maintaining.texi (Project File Commands) (Switching Projects): Describe key bindings for the commands described in the sections. Document 'project-list-file'. (Project Buffer Commands): New section. * doc/emacs/emacs.texi (Top): Add Project sections to the detailed menu. * etc/NEWS: Add entries for project.el, and mark documented entries as appropriate. --- diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi index 00c8ee4f98b..acd7fb13ae1 100644 --- a/doc/emacs/custom.texi +++ b/doc/emacs/custom.texi @@ -1630,6 +1630,10 @@ characters are actually defined by this map. @item @vindex mode-specific-map @code{mode-specific-map} is for characters that follow @kbd{C-c}. +@item +@vindex project-prefix-map +@code{project-prefix-map} is for characters that follow @kbd{C-x p}, +used for project-related commands (@pxref{Projects}). @end itemize @node Local Keymaps diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index 6b82aeb8234..5b6b7b7e93e 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -857,6 +857,12 @@ Customizing VC * CVS Options:: Options for CVS. @end ifnottex +Projects + +* Project File Commands:: Commands for handling project files. +* Project Buffer Commands:: Commands for handling project buffers. +* Switching Projects:: Switching between projects. + Change Logs * Change Log Commands:: Commands for editing change log files. diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi index cc7415e7ad5..43ec2d4e9f2 100644 --- a/doc/emacs/maintaining.texi +++ b/doc/emacs/maintaining.texi @@ -1657,12 +1657,43 @@ the project back-end. For example, the VC back-end doesn't consider ``ignored'' files (@pxref{VC Ignore}) to be part of the project. @menu -* Project File Commands:: Commands for handling project files. -* Switching Projects:: Switching between projects. +* Project File Commands:: Commands for handling project files. +* Project Buffer Commands:: Commands for handling project buffers. +* Switching Projects:: Switching between projects. @end menu @node Project File Commands -@subsection Project File Commands +@subsection Project Commands That Operate on Files + +@table @kbd +@item C-x p f +Visit a file that belongs to the current project +(@code{project-find-file}). +@item C-x p g +Find matches for a regexp in all files that belong to the current +project (@code{project-find-regexp}). +@item M-x project-search +Interactively search for regexp matches in all files that belong to +the current project. +@item C-x p r +Perform query-replace for a regexp in all files that belong to the +current project (@code{project-query-replace-regexp}). +@item C-x p d +Run Dired in the current project's root directory +(@code{project-dired}). +@item C-x p v +Run @code{vc-dir} in the current project's root directory +(@code{project-vc-dir}). +@item C-x p s +Start an inferior shell in the current project's root directory +(@code{project-shell}). +@item C-x p e +Start Eshell in the current project's root directory +(@code{project-eshell}). +@item C-x p c +Run compilation in the current project's root directory +(@code{project-compile}). +@end table Emacs provides commands for handling project files conveniently. This subsection describes these commands. @@ -1676,25 +1707,26 @@ 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. + The command @kbd{C-x p f} (@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. + The command @kbd{C-x p g} (@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 @@ -1706,7 +1738,7 @@ 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 + @kbd{C-x p r} (@code{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 @@ -1714,40 +1746,85 @@ response causes Emacs to exit the query-replace loop, you can later continue with @w{@kbd{M-x fileloop-continue @key{RET}}}. @findex project-dired - The command @code{project-dired} opens a Dired buffer -(@pxref{Dired}) listing the files in the current project's root + The command @kbd{C-x p d} (@code{project-dired}) opens a Dired +buffer (@pxref{Dired}) listing the files in the current project's root directory. @findex project-vc-dir - The command @code{project-vc-dir} opens a VC Directory buffer -(@pxref{VC Directory Mode}) listing the version control statuses of -the files in a directory tree under the current project's -root directory. + The command @kbd{C-x p v} (@code{project-vc-dir}) opens a VC +Directory buffer (@pxref{VC Directory Mode}) listing the version +control statuses of the files in a directory tree under the current +project's root directory. @findex project-shell - The command @code{project-shell} starts a shell session -(@pxref{Shell}) in a new buffer with the current project's root as the -working directory. + The command @kbd{C-x p s} (@code{project-shell}) starts a shell +session (@pxref{Shell}) in a new buffer with the current project's +root as the working directory. @findex project-eshell - The command @code{project-eshell} starts an Eshell session in a new -buffer with the current project's root as the working directory. -@xref{Top,Eshell,Eshell, eshell, Eshell: The Emacs Shell}. + The command @kbd{C-x p e} (@code{project-eshell}) starts an Eshell +session in a new buffer with the current project's root as the working +directory. @xref{Top,Eshell,Eshell, eshell, Eshell: The Emacs Shell}. + +@findex project-compile + The command @kbd{C-x p c} (@code{project-compile}) runs compilation +(@pxref{Compilation}) in the current project's root directory. + +@node Project Buffer Commands +@subsection Project Commands That Operate on Buffers + +@table @kbd +@item C-x p b +Switch to another buffer belonging to the current project +(@code{project-switch-to-buffer}). +@item C-x p k +Kill all live buffers that belong to the current project +(@code{project-kill-buffers}). +@end table + +@findex project-switch-to-buffer + Working on a project could potentially involve having many buffers +visiting files that belong to the project, and also buffers that +belong to the project, but don't visit any files (like the +@file{*compilation*} buffer created by @code{project-compile}). The +command @kbd{C-x p b} (@code{project-switch-to-buffer}) helps you +switch between buffers that belong to the current project by prompting +for a buffer to switch and considering only the current project's +buffers as candidates for completion. + +@findex project-kill-buffers +@vindex project-kill-buffers-ignores + When you finish working on the project, you may wish to kill all the +buffers that belong to the project, to keep your Emacs session +smaller. The command @kbd{C-x p k} (@code{project-kill-buffers}) +accomplishes that: it kills all the buffers that belong to the current +project, except if @code{project-kill-buffers-ignores} tells +otherwise. @node Switching Projects @subsection Switching Projects +@table @kbd +@item C-x p p +Run an Emacs command for another project (@code{project-switch-project}). +@end table + +@findex project-switch-project +@vindex project-switch-commands Commands that operate on project files (@pxref{Project File Commands}) will conveniently prompt you for a project directory when -no project is current. When you are inside a project but you want to -operate on a different project, the command -@code{project-switch-project} can be used. - - This command prompts you to choose a directory among known project -roots, and then displays the menu of available commands to operate on -the chosen project. The variable @code{project-switch-commands} -controls which commands are available in the menu, and by which keys -they are invoked. +no project is current. When you are inside some project, but you want +to operate on a different project, use the @kbd{C-x p p} command +(@code{project-switch-project}). This command prompts you to choose a +directory among known project roots, and then displays the menu of +available commands to operate on the project you choose. The variable +@code{project-switch-commands} controls which commands are available +in the menu, and which key invokes each command. + +@vindex project-list-file + The variable @code{project-list-file} names the file in which Emacs +records the list of known projects. It defaults to the file +@file{projects} in @code{user-emacs-directory} (@pxref{Find Init}). @node Change Log @section Change Logs diff --git a/etc/NEWS b/etc/NEWS index c93057e24dd..650b95867fb 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -502,21 +502,31 @@ information, see the related entry about 'shr-browse-url' above. *** New user option 'project-vc-merge-submodules'. -*** Previously used project directories are now suggested by -all commands that prompt for a project directory. +*** Project commands now have their own history. +Previously used project directories are now suggested by all commands +that prompt for a project directory. + ++++ +*** New prefix keymap 'project-prefix-map'. +Key sequences that invoke project-related commands start with the +prefix 'C-x p'. Type "C-x p C-h" to show the full list. +++ *** New commands 'project-dired', 'project-vc-dir', 'project-shell', 'project-eshell'. These commands run Dired/VC-Dir and Shell/Eshell in a project's root directory, respectively. -*** New command 'project-compile', which runs compilation. ++++ +*** New command 'project-compile'. +This command runs compilation in the current project's root +directory. +++ *** New command 'project-switch-project'. This command lets you "switch" to another project and run a project command chosen from a dispatch menu. ++++ *** New user option 'project-list-file'. ** json.el