procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve documentation of VC commands, including in Dired

Browse source 
* doc/emacs/dired.texi (Operating on Files):
* doc/emacs/maintaining.texi (VC Change Log, VC Directory Mode)
(Version Control, Basic VC Editing): Document VC command
invocation from Dired buffers.  Improve documentation of vc-log
commands.

* lisp/dired-aux.el (dired-vc-next-action):
* lisp/vc/vc.el (vc-print-log, vc-log-search, vc-log-mergebase)
(vc-log-view-type, vc-print-root-log, vc-next-action): Doc fixes.
This commit is contained in:
Eli Zaretskii 2023-02-23 14:26:06 +02:00
parent 990f402713
commit 5286111ea1
4 changed files with 101 additions and 35 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
doc/emacs/dired.texi
View file

@ -715,6 +715,10 @@ Otherwise, the command operates on the current file only.
Certain other Dired commands, such as @kbd{!} and the @samp{%}
commands, use the same conventions to decide which files to work on.
In addition to Dired commands described here, you can also invoke
Version Control (VC) commands on one or more files shown in a Dired
buffer. @xref{Version Control}.
@vindex dired-dwim-target
@cindex two directories (in Dired)
Commands which ask for a destination directory, such as those which

57
doc/emacs/maintaining.texi
View file

@ -94,6 +94,20 @@ is useful when you perform version control commands outside Emacs
different version control system, or remove it from version control
entirely.
@cindex VC commands, in Dired buffers
@cindex filesets, VC, in Dired buffers
VC is also enabled automatically in Dired buffers (@pxref{Dired})
showing directories whose files are controlled by a VCS@. All VC
commands described in this section can be invoked from any Dired
buffer showing a directory with VC-controlled files; any files that
are marked in a Dired buffer (@pxref{Marks vs Flags}) are considered
to belong to the current fileset, and VC commands operate on the files
in this fileset. This allows you to construct VC filesets including
any files you want, regardless of their VC state. (If no files are
marked when a VC command is invoked from a Dired buffer, the file
shown on the current line in the buffer is considered the only file in
the fileset.)
@menu
* Introduction to VC:: How version control works in general.
* VC Mode Line:: How the mode line shows version control status.
@ -471,9 +485,10 @@ collection of one or more files that a VC operation acts on. When you
type VC commands in a buffer visiting a version-controlled file, the
VC fileset is simply that one file. When you type them in a VC
Directory buffer, and some files in it are marked, the VC fileset
consists of the marked files (@pxref{VC Directory Mode}). The VC
fileset also consists of the marked files in a Dired buffer
(@pxref{Dired}).
consists of the marked files (@pxref{VC Directory Mode}). Likewise,
when you invoke a VC command from a Dired buffer, the VC fileset
consists of the marked files (@pxref{Marks vs Flags}), defaulting to
the file shown on the current line if no files are marked.
On modern changeset-based version control systems (@pxref{VCS
Changesets}), VC commands handle multi-file VC filesets as a group.
@ -497,7 +512,9 @@ action on the current VC fileset: either registering it with a version
control system, or committing it, or unlocking it, or merging changes
into it. The precise actions are described in detail in the following
subsections. You can use @kbd{C-x v v} either in a file-visiting
buffer, in a Dired buffer, or in a VC Directory buffer.
buffer, in a Dired buffer, or in a VC Directory buffer; in the latter
two cases the command operates on the fileset consisting of the marked
files.
Note that VC filesets are distinct from the named filesets used
for viewing and visiting files in functional groups
@ -1002,16 +1019,25 @@ Search the change history for a specified pattern.
@findex vc-print-log
@kbd{C-x v l} (@code{vc-print-log}) displays a buffer named
@file{*vc-change-log*}, showing the history of changes made to the
current file, including who made the changes, the dates, and the log
entry for each change (these are the same log entries you would enter
via the @file{*vc-log*} buffer; @pxref{Log Buffer}). Point is
centered at the revision of the file currently being visited. With a
prefix argument, the command prompts for the revision to center on,
and the maximum number of revisions to display.
current fileset in the long form, including who made the changes, the
dates, and the log entry for each change (these are the same log
entries you would enter via the @file{*vc-log*} buffer; @pxref{Log
Buffer}). When invoked from a buffer visiting a file, the current
fileset consists of that single file, and point in the displayed
@file{*vc-change-log*} buffer is centered at the revision of that
file. When invoked from a VC Directory buffer (@pxref{VC Directory
Mode}) or from a Dired buffer (@pxref{Dired}), the fileset consists of
all the marked files, defaulting to the file shown on the current line
in the directory buffer if no file is marked.
If you call @kbd{C-x v l} from a VC Directory buffer (@pxref{VC
Directory Mode}) or a Dired buffer (@pxref{Dired}), it applies to the
file listed on the current line or to all the marked files.
If the fileset includes one or more directories, the resulting
@file{*vc-change-log*} buffer shows a short log of changes (one line
for each change), if the VC backend supports that; otherwise it shows
the log in the long form.
With a prefix argument, the command prompts for the revision to
center on in the @file{*vc-change-log*} buffer and for the maximum
number of revisions to display.
@kindex C-x v L
@findex vc-print-root-log
@ -1217,6 +1243,11 @@ called PCL-CVS which is specialized for CVS@. @xref{Top, , About
PCL-CVS, pcl-cvs, PCL-CVS---The Emacs Front-End to CVS}.
@end ifnottex
You can also invoke VC commands from Dired buffers (@pxref{Dired}).
In that case, any VC command you invoke considers the marked files as
the current fileset (@pxref{Basic VC Editing}), defaulting to the file
on the current line if no files are marked.
@menu
* Buffer: VC Directory Buffer. What the buffer looks like and means.
* Commands: VC Directory Commands. Commands to use in a VC directory buffer.

21
lisp/dired-aux.el
View file

@ -3741,12 +3741,21 @@ of the target of the link instead."
;;;###autoload
(defun dired-vc-next-action (verbose)
"Do the next version control operation on marked files/directories.
When only files are marked then call `vc-next-action' with the
same value of the VERBOSE argument.
When also directories are marked then call `vc-dir' and mark
the same files/directories in the VC-Dir buffer that were marked
in the Dired buffer."
"Do the next logical version control operation on marked files/directories.
The VC control operation will operate on a fileset which includes
the marked files/directories. If no files/directories are marked, the
fileset will include the single file/directory shown on the current line.
If only regular files are in the fileset, call `vc-next-action' with
the same value of the VERBOSE argument (interactively, the prefix
argument).
If one or more directories are in the fileset, start `vc-dir' in the root
directory of the repository that includes the current directory, with
the same files/directories marked in the VC-Directory buffer that were
marked in the original Dired buffer. If the current directory doesn't
belong to a VCS repository, prompt for a repository directory. In this
case, the VERBOSE argument is ignored."
(interactive "P")
(let* ((marked-files
(dired-get-marked-files nil nil nil nil t))

54
lisp/vc/vc.el
View file

@ -1239,7 +1239,11 @@ For old-style locking-based version control systems, like RCS:
When using this command to register a new file (or files), it
will automatically deduce which VC repository to register it
with, using the most specific one."
with, using the most specific one.
If VERBOSE is non-nil (interactively, the prefix argument),
you can specify a VC backend or (for centralized VCS only)
the revision ID or branch ID."
(interactive "P")
(let* ((vc-fileset (vc-deduce-fileset nil t 'state-model-only-files))
(backend (car vc-fileset))
@ -2696,7 +2700,16 @@ earlier revisions. Show up to LIMIT entries (non-nil means unlimited)."
is-start-revision limit type)))))
(defvar vc-log-view-type nil
"Set this to differentiate the different types of logs.")
"Set this to record the type of VC log shown in the current buffer.
Supported values are:
`short' -- short log form, one line for each commit
`long' -- long log form, including full log message and author
`with-diff' -- log including diffs
`log-outgoing' -- log of changes to be pushed to upstream
`log-incoming' -- log of changes to be brought by pulling from upstream
`log-search' -- log entries matching a pattern; shown in long format
`mergebase' -- log created by `vc-log-mergebase'.")
(put 'vc-log-view-type 'permanent-local t)
(defvar vc-sentinel-movepoint)
@ -2753,13 +2766,20 @@ Each function runs in the log output buffer without args.")
;;;###autoload
(defun vc-print-log (&optional working-revision limit)
"List the change log of the current fileset in a window.
If WORKING-REVISION is non-nil, leave point at that revision.
"Show in another window the VC change history of the current fileset.
If WORKING-REVISION is non-nil, it should be a revision ID; position
point in the change history buffer at that revision.
If LIMIT is non-nil, it should be a number specifying the maximum
number of revisions to show; the default is `vc-log-show-limit'.
When called interactively with a prefix argument, prompt for
WORKING-REVISION and LIMIT."
WORKING-REVISION and LIMIT.
This shows a short log (one line for each commit) if the current
fileset includes directories and the VC backend supports that;
otherwise it shows the detailed log of each commit, which includes
the full log message and the author. Additional control of the
shown log style is available via `vc-log-short-style'."
(interactive
(cond
(current-prefix-arg
@ -2784,14 +2804,14 @@ WORKING-REVISION and LIMIT."
;;;###autoload
(defun vc-print-root-log (&optional limit revision)
"List the revision history for the current VC controlled tree in a window.
"Show in another window VC change history of the current VC controlled tree.
If LIMIT is non-nil, it should be a number specifying the maximum
number of revisions to show; the default is `vc-log-show-limit'.
When called interactively with a prefix argument, prompt for LIMIT.
When the prefix argument is a number, use it as LIMIT.
When called interactively with a prefix argument, prompt for LIMIT, but
if the prefix argument is a number, use it as LIMIT.
A special case is when the prefix argument is 1: in this case
the command asks for the ID of a revision, and shows that revision
with its diffs (if the underlying VCS supports that)."
the command prompts for the ID of a revision, and shows that revision
with its diffs (if the underlying VCS backend supports that)."
(interactive
(cond
((eq current-prefix-arg 1)
@ -2875,15 +2895,17 @@ In some version control systems REMOTE-LOCATION can be a remote branch name."
;;;###autoload
(defun vc-log-search (pattern)
"Search the log of changes for PATTERN.
"Search the VC log of changes for PATTERN and show log of matching changes.
PATTERN is usually interpreted as a regular expression. However, its
exact semantics is up to the backend's log search command; some can
only match fixed strings.
Display all entries that match log messages in long format.
With a prefix argument, ask for a command to run that will output
log entries."
This command displays in long format all the changes whose log messages
match PATTERN.
With a prefix argument, the command asks for a shell command to run that
will output log entries, and displays those log entries instead."
(interactive (list (unless current-prefix-arg
(read-regexp "Search log with pattern: "))))
(let ((backend (vc-deduce-backend)))
@ -2894,8 +2916,8 @@ log entries."
;;;###autoload
(defun vc-log-mergebase (_files rev1 rev2)
"Show a log of changes between the merge base of REV1 and REV2 revisions.
The merge base is a common ancestor between REV1 and REV2 revisions."
"Show a log of changes between the merge base of revisions REV1 and REV2.
The merge base is a common ancestor of revisions REV1 and REV2."
(interactive
(vc-diff-build-argument-list-internal
(or (ignore-errors (vc-deduce-fileset t))