From: Sean Whitton Date: Sat, 26 Jul 2025 12:06:51 +0000 (+0100) Subject: ; VC: Improve documentation of other working trees features. X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=744b9c572ecc2deb554db424224578f963b01743;p=emacs.git ; VC: Improve documentation of other working trees features. (cherry picked from commit fcdf2061eabd0892895b68e00297871273f922a0) --- diff --git a/doc/emacs/vc1-xtra.texi b/doc/emacs/vc1-xtra.texi index f2a561eccf8..f733b57afa4 100644 --- a/doc/emacs/vc1-xtra.texi +++ b/doc/emacs/vc1-xtra.texi @@ -236,8 +236,19 @@ Some VCS support more than one working tree with the same backing repository or revisions store. This means that you can have different revisions or branches (@pxref{Branches}) checked out simultaneously, in different working trees, but with all revision history, branches, tags -and other metadata shared. The following commands let you switch -between and modify different working trees. +and other metadata shared. + +Ordinary VC commands like @kbd{C-x v v} and @kbd{C-x v d} don't work any +differently when there exist other working trees, except that the +commits, branches and other VC artifacts they create will be visible +from all working trees. + +The following special commands let you switch between and modify +different working trees. It is an error to use them other than from +within a VC working tree; that is, from a buffer visiting a +VCS-controlled file, or otherwise from a buffer whose +@code{default-directory} (@pxref{File Names}) is within a VC working +tree. @table @kbd @item C-x v w c diff --git a/lisp/vc/vc-git.el b/lisp/vc/vc-git.el index 48d8e7cd76a..72c47f6532d 100644 --- a/lisp/vc/vc-git.el +++ b/lisp/vc/vc-git.el @@ -2393,7 +2393,12 @@ In other modes, call `vc-deduce-fileset' to determine files to stash." (vc-dir-at-event e (popup-menu vc-git-stash-menu-map e))) (defun vc-git--worktrees () - "Return an alist of alists regarding this repository's worktrees." + "Return an alist of alists regarding this repository's worktrees. +The keys into the outer alist are the worktree root directories; so, +there is one inner alist for each worktree. The keys and values of each +inner alist are the worktree attributes returned by `git worktree list'; +see the \"LIST OUTPUT FORMAT\" section of the git-worktree(1) manual +page for the meanings of these attributes." (with-temp-buffer (vc-git-command nil 0 nil "worktree" "prune") (vc-git-command t 0 nil "worktree" "list" "--porcelain" "-z") @@ -2417,12 +2422,14 @@ In other modes, call `vc-deduce-fileset' to determine files to stash." (error "'git worktree' output parse error"))))) (defun vc-git-known-other-working-trees () + "Implementation of `known-other-working-trees' backend function for Git." (cl-loop with root = (expand-file-name (vc-git-root default-directory)) for (worktree) in (vc-git--worktrees) unless (equal worktree root) collect (abbreviate-file-name worktree))) (defun vc-git-add-working-tree (directory) + "Implementation of `add-working-tree' backend function for Git." (letrec ((dir (expand-file-name directory)) (vc-filter-command-function #'list) ; see `vc-read-revision' (revs (vc-git-revision-table nil)) @@ -2439,10 +2446,12 @@ In other modes, call `vc-deduce-fileset' to determine files to stash." (apply #'vc-git-command nil 0 nil "worktree" "add" args))) (defun vc-git-delete-working-tree (directory) + "Implementation of `delete-working-tree' backend function for Git." (vc-git-command nil 0 nil "worktree" "remove" "-f" (expand-file-name directory))) (defun vc-git-move-working-tree (from to) + "Implementation of `move-working-tree' backend function for Git." ;; 'git worktree move' can't move the main worktree, but moving and ;; then repairing like this can. (rename-file from (directory-file-name to) 1) diff --git a/lisp/vc/vc-hg.el b/lisp/vc/vc-hg.el index 976c8183efe..1e064a24e39 100644 --- a/lisp/vc/vc-hg.el +++ b/lisp/vc/vc-hg.el @@ -1682,6 +1682,7 @@ Intended for use via the `vc-hg--async-command' wrapper." (buffer-substring-no-properties (point-min) (1- (point-max)))))) (defun vc-hg-known-other-working-trees () + "Implementation of `known-other-working-trees' backend function for Hg." ;; Mercurial doesn't maintain records of shared repositories. ;; The first repository knows nothing about shares created from it, ;; and each share only has a reference back to the first repository. @@ -1713,6 +1714,7 @@ Intended for use via the `vc-hg--async-command' wrapper." shares)) (defun vc-hg-add-working-tree (directory) + "Implementation of `add-working-tree' backend function for Mercurial." (vc-hg-command nil 0 nil "share" (vc-hg-root default-directory) (expand-file-name directory))) @@ -1721,12 +1723,14 @@ Intended for use via the `vc-hg--async-command' wrapper." (file-exists-p (expand-file-name ".hg/sharedpath" directory))) (defun vc-hg-delete-working-tree (directory) + "Implementation of `delete-working-tree' backend function for Mercurial." (if (vc-hg--shared-p directory) (delete-directory directory t t) (user-error "\ Cannot delete first working tree because this would break other working trees"))) (defun vc-hg-move-working-tree (from to) + "Implementation of `move-working-tree' backend function for Mercurial." (if (vc-hg--shared-p from) (rename-file from (directory-file-name to) 1) (user-error "\ diff --git a/lisp/vc/vc.el b/lisp/vc/vc.el index ae1b3cfafee..ebf4cda8c22 100644 --- a/lisp/vc/vc.el +++ b/lisp/vc/vc.el @@ -152,6 +152,7 @@ ;; files, including up-to-date or ignored files. ;; ;; EXTRA can be used for backend specific information about FILE. +;; ;; If a command needs to be run to compute this list, it should be ;; run asynchronously using (current-buffer) as the buffer for the ;; command. @@ -4333,16 +4334,26 @@ It returns the last revision that changed LINE number in FILE." (if (consp rev) (car rev) rev)))) (defun vc-dir-status-files (directory &optional files backend) - "Synchronously run `dir-status-files' VC backend function for DIRECTORY. -FILES is passed to the VC backend function. -BACKEND is defaulted by calling `vc-responsible-backend' on DIRECTORY." + "Return VC status information about files in DIRECTORY. +Return a list of the form (FILE VC-STATE EXTRA) for each file. +VC-STATE is the current VC state of the file, and EXTRA is optional, +backend-specific information. +Normally files in the `up-to-date' and `ignored' states are not +included. If the optional argument FILES is non-nil, report on only +those files, and don't exclude them for being in one of those states. +BACKEND is the VC backend; if nil or omitted, it defaults to the result +of calling `vc-responsible-backend' with DIRECTORY as its first and only +argument. + +This function provides Lisp programs with synchronous access to the same +information that Emacs requests from VC backends to populate VC-Dir +buffers. It is usually considerably faster than walking the tree +yourself with a function like `vc-file-tree-walk'." ;; The `dir-status-files' API was designed for asynchronous use to ;; populate *vc-dir* buffers; see `vc-dir-refresh'. - ;; This function provides Lisp programs with synchronous access to the - ;; same information without touching the user's *vc-dir* buffers and + ;; This function provides Lisp programs with access to the same + ;; information without touching the user's *vc-dir* buffers and ;; without having to add a new VC backend function. - ;; It is considerably faster than using `vc-file-tree-walk' - ;; (like `vc-tag-precondition' does). ;; This function is in this file despite its `vc-dir-' prefix to avoid ;; having to load `vc-dir' just to get access to this simple wrapper. (let ((morep t) results) @@ -4369,8 +4380,9 @@ BACKEND is defaulted by calling `vc-responsible-backend' on DIRECTORY." ;;;###autoload (defun vc-add-working-tree (backend directory) "Create working tree DIRECTORY with same backing repository as this tree. -See Info node `(emacs)Other Working Trees' regarding VCS repositories -with multiple working trees." +Must be called from within an existing VC working tree. +When called interactively, prompts for DIRECTORY. +When called from Lisp, BACKEND is the VC backend." (interactive (list (vc-responsible-backend default-directory) @@ -4396,12 +4408,11 @@ with multiple working trees." ;;;###autoload (defun vc-switch-working-tree (directory) "Switch to this file's analogue in working tree DIRECTORY. -This command switches to the file which has the same path -relative to DIRECTORY that this buffer's file has relative -to the root of this working tree. -DIRECTORY names another working tree with the same backing repository as -this tree; see Info node `(emacs)Other Working Trees' for general -information regarding VCS repositories with multiple working trees." +Must be called from within an existing VC working tree. +When called interactively, prompts for DIRECTORY. +This command switches to the file which has the same file +name relative to DIRECTORY that this buffer's file has relative +to the root of this working tree." ;; FIXME: Switch between directory analogues, too, in Dired buffers. (interactive (list @@ -4416,8 +4427,9 @@ information regarding VCS repositories with multiple working trees." ;;;###autoload (defun vc-delete-working-tree (backend directory) "Delete working tree DIRECTORY with same backing repository as this tree. -See Info node `(emacs)Other Working Trees' regarding VCS repositories -with multiple working trees." +Must be called from within an existing VC working tree. +When called interactively, prompts for DIRECTORY. +BACKEND is the VC backend." (interactive (let ((backend (vc-responsible-backend default-directory))) (list backend @@ -4442,9 +4454,11 @@ with multiple working trees." (autoload 'dired-rename-subdir "dired-aux") ;;;###autoload (defun vc-move-working-tree (backend from to) - "Relocate a working tree from FROM to TO. -See Info node `(emacs)Other Working Trees' regarding VCS repositories -with multiple working trees." + "Relocate a working tree from FROM to TO, two directory file names. +Must be called from within an existing VC working tree. +When called interactively, prompts the directory file names of each of +the other working trees FROM and TO. +BACKEND is the VC backend." (interactive (let ((backend (vc-responsible-backend default-directory))) (list backend