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.
This commit is contained in:
Eli Zaretskii
parent
eaad6eac00
commit
3b44829823
4 changed files with 141 additions and 44 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
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.
|
||||
|
||||
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.
|
||||
@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
|
||||
|
|
|
|||
16
etc/NEWS
16
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
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue