diff options
author | Eli Zaretskii <eliz@gnu.org> | 2023-02-23 14:26:06 +0200 |
---|---|---|
committer | Eli Zaretskii <eliz@gnu.org> | 2023-02-23 14:26:06 +0200 |
commit | 5286111ea1fe442d861cd4a940d86db3fd832139 (patch) | |
tree | 2bcc8972824681ae4cd7f99bafc8d8bf81bd3328 /lisp/vc/vc.el | |
parent | 990f4027131e4ff7d83db23d82de0d47f64d288e (diff) | |
download | emacs-5286111ea1fe442d861cd4a940d86db3fd832139.tar.gz |
Improve documentation of VC commands, including in Dired
* 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.
Diffstat (limited to 'lisp/vc/vc.el')
-rw-r--r-- | lisp/vc/vc.el | 54 |
1 files changed, 38 insertions, 16 deletions
diff --git a/lisp/vc/vc.el b/lisp/vc/vc.el index 4ba62c0b3c7..0e3519e2e5c 100644 --- a/lisp/vc/vc.el +++ b/lisp/vc/vc.el @@ -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)) |