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
(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")
(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))
(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)
(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.
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)))
(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 "\
;; 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.
(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)
;;;###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)
;;;###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
;;;###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
(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
projects / emacs.git / commitdiff