mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2025-12-15 10:30:25 -08:00
Code Issues Projects Releases Wiki Activity

; VC: Improve documentation of other working trees features.

Browse source
This commit is contained in:
Sean Whitton 2025-07-26 13:06:51 +01:00
parent 88337345f5
commit fcdf2061ea
4 changed files with 61 additions and 23 deletions
Download patch file Download diff file Expand all files Collapse all files

15
doc/emacs/vc1-xtra.texi
View file

@ -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

11
lisp/vc/vc-git.el
View file

@ -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)

4
lisp/vc/vc-hg.el
View file

@ -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 "\

54
lisp/vc/vc.el
View file

@ -155,6 +155,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.
@ -4338,16 +4339,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)
@ -4374,8 +4385,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)
@ -4401,12 +4413,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
@ -4421,8 +4432,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
@ -4447,9 +4459,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