VC: New support for other working trees

* lisp/vc/vc-git.el (vc-git--read-start-point): New function,
factored out of vc-git-create-tag.
(vc-git-create-tag): Use it.
(vc-git--worktrees, vc-git-known-other-working-trees)
(vc-git-add-working-tree, vc-git-delete-working-tree)
(vc-git-move-working-tree):
* lisp/vc/vc-hg.el (vc-hg-known-other-working-trees)
(vc-hg-add-working-tree, vc-hg--shared-p)
(vc-hg-delete-working-tree, vc-hg-move-working-tree): New
functions.
* lisp/vc/vc.el: Define API for known-other-working-tree,
add-working-tree, delete-working-tree and move-working-tree
backend functions.
(vc-dir-status-files): New function.
(project-current-directory-override): Declare.
(dired-rename-subdir): Autoload.
(vc-add-working-tree, vc-switch-working-tree)
(vc-delete-working-tree, vc-move-working-tree): New commands.
* lisp/vc/vc-hooks.el (vc-prefix-map): Bind them under C-x v.

* doc/emacs/vc1-xtra.texi (Other Working Trees): New node.
* etc/NEWS: Announce the new commands.

* test/lisp/vc/vc-tests/vc-tests.el
(vc-test--other-working-trees): New function.
(vc-test-git07-other-working-trees)
(vc-test-hg07-other-working-trees): New tests.

* lisp/ldefs-boot.el: Regenerate.

10 files changed, 637 insertions, 147 deletions

diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index ba47190944a..b373dc092f8 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -868,6 +868,7 @@ Miscellaneous Commands and Features of VC
 * Change Logs and VC::    Generating a change log file from log entries.
 * VC Delete/Rename::      Deleting and renaming version-controlled files.
 * Revision Tags::         Symbolic names for revisions.
+* Other Working Trees::   Multiple sets of workfiles.
 * Version Headers::       Inserting version control headers into working files.
 * Editing VC Commands::   Editing the VC shell commands that Emacs will run.
 * Preparing Patches::     Preparing and composing patches from within VC.
diff --git a/doc/emacs/vc1-xtra.texi b/doc/emacs/vc1-xtra.texi
index e35883c4819..29ae63c7e41 100644
--- a/doc/emacs/vc1-xtra.texi
+++ b/doc/emacs/vc1-xtra.texi
@@ -14,6 +14,7 @@
 * Change Logs and VC::  Generating a change log file from log entries.
 * VC Delete/Rename::    Deleting and renaming version-controlled files.
 * Revision Tags::       Symbolic names for revisions.
+* Other Working Trees:: Multiple sets of workfiles.
 * Version Headers::     Inserting version control headers into working files.
 * Editing VC Commands:: Editing the VC shell commands that Emacs will run.
 * Preparing Patches::   Preparing and composing patches from within VC.
@@ -226,6 +227,70 @@ an old tag, the renamed file is retrieved under its new name, which is
 not the name that the makefile expects.  So the program won't really
 work as retrieved.
 
+@node Other Working Trees
+@subsubsection Multiple Working Trees for One Repository
+
+@cindex other working trees
+@cindex multiple working trees
+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.
+
+@table @kbd
+@item C-x v w c
+Add a new working tree.
+
+@item C-x v w w
+Visit this file in another working tree.
+
+@item C-x v w x
+Delete a working tree you no longer need.
+
+@item C-x v w R
+Relocate a working tree to another file name.
+@end table
+
+@kindex C-x v w c
+@findex vc-add-working-tree
+You can start using multiple working trees by using the command
+@w{@kbd{C-x v w c}} (@code{vc-add-working-tree}) to create a new working
+tree.  This prompts you to specify a destination directory, which
+identifies the working tree, and which will hold the new set of
+workfiles.
+
+Different VCS have different rules about what may and must be checked
+out in other working trees, so there may be additional prompts depending
+on the VCS in use.  For example, Git requires that each branch be
+checked out in only one working tree at a time, so when using Git, Emacs
+will also prompt you for the name of the branch to be checked out in the
+new working tree.
+
+@kindex C-x v w w
+@findex vc-switch-working-tree
+Once your repository has other working trees, you can use the command
+@kbd{C-x v w w} (@code{vc-switch-working-tree}) to switch between them.
+It tries to find the analogue of the current buffer's file
+under another working tree.  Typically the sets of workfiles
+under different working trees differ more in file contents than in which
+files do and do not exist.  In other words, the file the
+current buffer visits probably exists in other working trees too, and
+this command lets you switch to those versions of the file.
+
+@kindex C-x v w x
+@kindex C-x v w R
+@findex vc-delete-working-tree
+@findex vc-move-working-tree
+The commands @kbd{C-x v w x} (@code{vc-delete-working-tree}) and
+@kbd{C-x v w R} (@code{vc-move-working-tree}) are for performing
+maintenance tasks on other working trees, letting you delete, move and
+rename them.  Deleting other working trees is particular useful because
+a common use for multiple working trees is to create throwaway copies of
+the repository to quickly test changes, without interfering with any
+work-in-progress you may have in your primary working trees.
+
 @node Version Headers
 @subsubsection Inserting Version Control Headers
 
diff --git a/etc/NEWS b/etc/NEWS
index 9ccfd75fecf..1164f63028e 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1843,6 +1843,22 @@ appearance of the list can be customized with the new faces
 
 ** VC
 
++++
+*** New commands to handle repositories with multiple working trees.
+Some VCS support more than one working tree with the same backing
+revisions store, such as with Git's 'worktree' subcommand and
+Mercurial's 'share' extension.  Emacs now has some commands to manage
+other working trees:
+
+- 'C-x v w c': Add a new working tree.
+- 'C-x v w w': Visit this file in another working tree.
+- 'C-x v w x': Delete a working tree you no longer need.
+- 'C-x v w R': Relocate a working tree to another file name.
+
+In addition, Lisp programs that extend VC can invoke the new backend
+functions to obtain a list of other working trees, and to add, remove
+and relocate them.
+
 ---
 *** Using 'e' from Log View mode to modify change comments now works for Git.
 
diff --git a/lisp/ldefs-boot.el b/lisp/ldefs-boot.el
index 8d275b37172..10328165450 100644
--- a/lisp/ldefs-boot.el
+++ b/lisp/ldefs-boot.el
@@ -5234,8 +5234,6 @@ evaluate the variable `compilation-shell-minor-mode'.
 The mode's hook is called both when the mode is enabled and when it is
 disabled.
 
-\\{compilation-shell-minor-mode-map}
-
 (fn &optional ARG)" t)
 (autoload 'compilation-minor-mode "compile" "\
 Toggle Compilation minor mode.
@@ -5258,8 +5256,6 @@ evaluate the variable `compilation-minor-mode'.
 The mode's hook is called both when the mode is enabled and when it is
 disabled.
 
-\\{compilation-minor-mode-map}
-
 (fn &optional ARG)" t)
 (autoload 'compilation-next-error-function "compile" "\
 Advance to the next error message and visit the file where the error was.
@@ -5372,7 +5368,10 @@ either customize it (see the info node `Easy Customization')
 or call the function `global-completion-preview-mode'.")
 (custom-autoload 'global-completion-preview-mode "completion-preview" nil)
 (autoload 'global-completion-preview-mode "completion-preview" "\
-Toggle Completion-Preview mode in all buffers.
+Toggle Completion-Preview mode in many buffers.
+Specifically, Completion-Preview mode is enabled in all buffers where
+`completion-preview-mode' would do it.
+
 With prefix ARG, enable Global Completion-Preview mode if ARG is
 positive; otherwise, disable it.
 
@@ -5380,9 +5379,6 @@ If called from Lisp, toggle the mode if ARG is `toggle'.
 Enable the mode if ARG is nil, omitted, or is a positive number.
 Disable the mode if ARG is a negative number.
 
-Completion-Preview mode is enabled in all buffers where
-`completion-preview-mode' would do it.
-
 See `completion-preview-mode' for more information on
 Completion-Preview mode.
 
@@ -6539,7 +6535,10 @@ either customize it (see the info node `Easy Customization')
 or call the function `global-cwarn-mode'.")
 (custom-autoload 'global-cwarn-mode "cwarn" nil)
 (autoload 'global-cwarn-mode "cwarn" "\
-Toggle Cwarn mode in all buffers.
+Toggle Cwarn mode in many buffers.
+Specifically, Cwarn mode is enabled in all buffers where
+`turn-on-cwarn-mode-if-enabled' would do it.
+
 With prefix ARG, enable Global Cwarn mode if ARG is positive;
 otherwise, disable it.
 
@@ -6547,9 +6546,6 @@ If called from Lisp, toggle the mode if ARG is `toggle'.
 Enable the mode if ARG is nil, omitted, or is a positive number.
 Disable the mode if ARG is a negative number.
 
-Cwarn mode is enabled in all buffers where
-`turn-on-cwarn-mode-if-enabled' would do it.
-
 See `cwarn-mode' for more information on Cwarn mode.
 
 (fn &optional ARG)" t)
@@ -7653,18 +7649,18 @@ Also see the `diff-entire-buffers' variable.
 
 (autoload 'diff-mode "diff-mode" "\
 Major mode for viewing/editing context diffs.
-Supports unified and context diffs as well as (to a lesser extent)
-normal diffs.
-
-When the buffer is read-only, the ESC prefix is not necessary.
-If you edit the buffer manually, `diff-mode' will try to update the hunk
-headers for you on-the-fly.
+Supports unified and context diffs as well as, to a lesser extent, diffs
+in the old \"normal\" format.  (Unified diffs have become the standard,
+most commonly encountered format.)  If you edit the buffer manually,
+`diff-mode' will try to update the hunk headers for you on-the-fly.
 
 You can also switch between context diff and unified diff with \\[diff-context->unified],
 or vice versa with \\[diff-unified->context] and you can also reverse the direction of
 a diff with \\[diff-reverse-direction].
 
 \\{diff-mode-map}
+In read-only buffers the following bindings are also available:
+\\{diff-read-only-map}
 
 (fn)" t)
 (autoload 'diff-minor-mode "diff-mode" "\
@@ -8114,7 +8110,10 @@ either customize it (see the info node `Easy Customization')
 or call the function `global-display-fill-column-indicator-mode'.")
 (custom-autoload 'global-display-fill-column-indicator-mode "display-fill-column-indicator" nil)
 (autoload 'global-display-fill-column-indicator-mode "display-fill-column-indicator" "\
-Toggle Display-Fill-Column-Indicator mode in all buffers.
+Toggle Display-Fill-Column-Indicator mode in many buffers.
+Specifically, Display-Fill-Column-Indicator mode is enabled in all
+buffers where `display-fill-column-indicator--turn-on' would do it.
+
 With prefix ARG, enable Global Display-Fill-Column-Indicator mode if
 ARG is positive; otherwise, disable it.
 
@@ -8122,9 +8121,6 @@ If called from Lisp, toggle the mode if ARG is `toggle'.
 Enable the mode if ARG is nil, omitted, or is a positive number.
 Disable the mode if ARG is a negative number.
 
-Display-Fill-Column-Indicator mode is enabled in all buffers where
-`display-fill-column-indicator--turn-on' would do it.
-
 See `display-fill-column-indicator-mode' for more information on
 Display-Fill-Column-Indicator mode.
 
@@ -8185,7 +8181,10 @@ either customize it (see the info node `Easy Customization')
 or call the function `global-display-line-numbers-mode'.")
 (custom-autoload 'global-display-line-numbers-mode "display-line-numbers" nil)
 (autoload 'global-display-line-numbers-mode "display-line-numbers" "\
-Toggle Display-Line-Numbers mode in all buffers.
+Toggle Display-Line-Numbers mode in many buffers.
+Specifically, Display-Line-Numbers mode is enabled in all buffers
+where `display-line-numbers--turn-on' would do it.
+
 With prefix ARG, enable Global Display-Line-Numbers mode if ARG is
 positive; otherwise, disable it.
 
@@ -8193,9 +8192,6 @@ If called from Lisp, toggle the mode if ARG is `toggle'.
 Enable the mode if ARG is nil, omitted, or is a positive number.
 Disable the mode if ARG is a negative number.
 
-Display-Line-Numbers mode is enabled in all buffers where
-`display-line-numbers--turn-on' would do it.
-
 See `display-line-numbers-mode' for more information on
 Display-Line-Numbers mode.
 
@@ -8550,8 +8546,8 @@ switch on the minor mode in all major modes), nil (meaning don't
 switch on in any major mode), a list of modes (meaning switch on only
 in those modes and their descendants), or a list (not MODES...),
 meaning switch on in any major mode except MODES.  The value can also
-mix all of these forms, see the info node `Defining Minor Modes' for
-details.  The :predicate key causes the macro to create a user option
+mix all of these forms, see the Info node `(elisp)Defining Minor Modes'
+for details.  The :predicate key causes the macro to create a user option
 named the same as MODE, but ending with \"-modes\" instead of \"-mode\".
 That user option can then be used to customize in which modes this
 globalized minor mode will be switched on.
@@ -8929,7 +8925,7 @@ A second call of this function without changing point inserts the next match.
 A call with prefix PREFIX reads the symbol to insert from the minibuffer with
 completion.
 
-(fn PREFIX)" t)
+(fn PREFIX)" '("P"))
 (autoload 'ebrowse-tags-loop-continue "ebrowse" "\
 Repeat last operation on files in tree.
 FIRST-TIME non-nil means this is not a repetition, but the first time.
@@ -9851,7 +9847,7 @@ Describe CTR if it is a class constructor.
 
 ;;; Generated autoloads from emacs-lisp/eldoc.el
 
-(push '(eldoc 1 15 0) package--builtin-versions)
+(push '(eldoc 1 16 0) package--builtin-versions)
 
 
 ;;; Generated autoloads from elec-pair.el
@@ -9951,32 +9947,6 @@ mode hooks.
 (register-definition-prefixes "elide-head" '("elide-head-"))
 
 
-;;; Generated autoloads from emacs-lisp/elint.el
-
-(autoload 'elint-file "elint" "\
-Lint the file FILE.
-
-(fn FILE)" t)
-(autoload 'elint-directory "elint" "\
-Lint all the .el files in DIRECTORY.
-A complicated directory may require a lot of memory.
-
-(fn DIRECTORY)" t)
-(autoload 'elint-current-buffer "elint" "\
-Lint the current buffer.
-If necessary, this first calls `elint-initialize'." t)
-(autoload 'elint-defun "elint" "\
-Lint the function at point.
-If necessary, this first calls `elint-initialize'." t)
-(autoload 'elint-initialize "elint" "\
-Initialize elint.
-If elint is already initialized, this does nothing, unless
-optional prefix argument REINIT is non-nil.
-
-(fn &optional REINIT)" t)
-(register-definition-prefixes "elint" '("elint-"))
-
-
 ;;; Generated autoloads from progmodes/elixir-ts-mode.el
 
 (autoload 'elixir-ts-mode "elixir-ts-mode" "\
@@ -10721,7 +10691,7 @@ ERC assigns SERVER and FULL-NAME the associated keyword values
 and defers to `erc-compute-port', `erc-compute-user', and
 `erc-compute-nick' for those respective parameters.
 
-(fn &key SERVER PORT NICK USER PASSWORD FULL-NAME ID)" t)
+(fn &key SERVER PORT NICK USER PASSWORD FULL-NAME ID)" '((let ((erc--display-context `((erc-interactive-display . erc) ,@erc--display-context))) (erc-select-read-args))))
 (defalias 'erc-select #'erc)
 (autoload 'erc-tls "erc" "\
 Connect to an IRC server over a TLS-encrypted connection.
@@ -10744,7 +10714,7 @@ See the alternative entry-point command `erc' as well as Info
 node `(erc) Connecting' for a fuller description of the various
 parameters, like ID.
 
-(fn &key SERVER PORT NICK USER PASSWORD FULL-NAME CLIENT-CERTIFICATE ID)" t)
+(fn &key SERVER PORT NICK USER PASSWORD FULL-NAME CLIENT-CERTIFICATE ID)" '((let ((erc-default-port erc-default-port-tls) (erc--display-context `((erc-interactive-display . erc-tls) ,@erc--display-context))) (erc-select-read-args))))
 (autoload 'erc-handle-irc-url "erc" "\
 Use ERC to IRC on HOST:PORT in CHANNEL.
 If ERC is already connected to HOST:PORT, simply /join CHANNEL.
@@ -10976,9 +10946,7 @@ it has to be wrapped in `(eval (quote ...))'.
 If NAME is already defined as a test and Emacs is running
 in batch mode, an error is signaled.
 
-(fn NAME () [DOCSTRING] [:expected-result RESULT-TYPE] [:tags \\='(TAG...)] BODY...)" nil t)
-(function-put 'ert-deftest 'doc-string-elt 3)
-(function-put 'ert-deftest 'lisp-indent-function 2)
+(fn NAME () [DOCSTRING] [:expected-result RESULT-TYPE] [:tags \\='(TAG...)] BODY...)" nil 'macro)
 (autoload 'ert-run-tests-batch "ert" "\
 Run the tests specified by SELECTOR, printing results to the terminal.
 
@@ -12830,6 +12798,8 @@ value is the default binding of the variable.
 The connection-local value of `path-separator'.")
 (autoload 'null-device "files-x" "\
 The connection-local value of `null-device'.")
+(autoload 'exec-suffixes "files-x" "\
+The connection-local value of `exec-suffixes'.")
 (register-definition-prefixes "files-x" '("connection-local-" "dir-locals-to-string" "modify-" "read-"))
 
 
@@ -13399,8 +13369,6 @@ evaluate the variable `flymake-mode'.
 The mode's hook is called both when the mode is enabled and when it is
 disabled.
 
-\\{flymake-mode-map}
-
 (fn &optional ARG)" t)
 (autoload 'flymake-mode-on "flymake" "\
 Turn Flymake mode on.")
@@ -15232,7 +15200,10 @@ either customize it (see the info node `Easy Customization')
 or call the function `global-goto-address-mode'.")
 (custom-autoload 'global-goto-address-mode "goto-addr" nil)
 (autoload 'global-goto-address-mode "goto-addr" "\
-Toggle Goto-Address mode in all buffers.
+Toggle Goto-Address mode in many buffers.
+Specifically, Goto-Address mode is enabled in all buffers where
+`goto-addr-mode--turn-on' would do it.
+
 With prefix ARG, enable Global Goto-Address mode if ARG is positive;
 otherwise, disable it.
 
@@ -15240,9 +15211,6 @@ If called from Lisp, toggle the mode if ARG is `toggle'.
 Enable the mode if ARG is nil, omitted, or is a positive number.
 Disable the mode if ARG is a negative number.
 
-Goto-Address mode is enabled in all buffers where
-`goto-addr-mode--turn-on' would do it.
-
 See `goto-address-mode' for more information on Goto-Address mode.
 
 (fn &optional ARG)" t)
@@ -16433,7 +16401,10 @@ either customize it (see the info node `Easy Customization')
 or call the function `global-hi-lock-mode'.")
 (custom-autoload 'global-hi-lock-mode "hi-lock" nil)
 (autoload 'global-hi-lock-mode "hi-lock" "\
-Toggle Hi-Lock mode in all buffers.
+Toggle Hi-Lock mode in many buffers.
+Specifically, Hi-Lock mode is enabled in all buffers where
+`turn-on-hi-lock-if-enabled' would do it.
+
 With prefix ARG, enable Global Hi-Lock mode if ARG is positive;
 otherwise, disable it.
 
@@ -16441,9 +16412,6 @@ If called from Lisp, toggle the mode if ARG is `toggle'.
 Enable the mode if ARG is nil, omitted, or is a positive number.
 Disable the mode if ARG is a negative number.
 
-Hi-Lock mode is enabled in all buffers where
-`turn-on-hi-lock-if-enabled' would do it.
-
 See `hi-lock-mode' for more information on Hi-Lock mode.
 
 (fn &optional ARG)" t)
@@ -16812,7 +16780,10 @@ either customize it (see the info node `Easy Customization')
 or call the function `global-highlight-changes-mode'.")
 (custom-autoload 'global-highlight-changes-mode "hilit-chg" nil)
 (autoload 'global-highlight-changes-mode "hilit-chg" "\
-Toggle Highlight-Changes mode in all buffers.
+Toggle Highlight-Changes mode in many buffers.
+Specifically, Highlight-Changes mode is enabled in all buffers where
+`highlight-changes-mode-turn-on' would do it.
+
 With prefix ARG, enable Global Highlight-Changes mode if ARG is
 positive; otherwise, disable it.
 
@@ -16820,9 +16791,6 @@ If called from Lisp, toggle the mode if ARG is `toggle'.
 Enable the mode if ARG is nil, omitted, or is a positive number.
 Disable the mode if ARG is a negative number.
 
-Highlight-Changes mode is enabled in all buffers where
-`highlight-changes-mode-turn-on' would do it.
-
 See `highlight-changes-mode' for more information on Highlight-Changes
 mode.
 
@@ -17102,8 +17070,7 @@ inlined into the compiled format versions.  This means that if you
 change its definition, you should explicitly call
 `ibuffer-recompile-formats'.
 
-(fn SYMBOL (&key NAME INLINE PROPS SUMMARIZER) &rest BODY)" nil t)
-(function-put 'define-ibuffer-column 'lisp-indent-function 'defun)
+(fn SYMBOL (&key NAME INLINE PROPS SUMMARIZER) &rest BODY)" nil 'macro)
 (autoload 'define-ibuffer-sorter "ibuf-macs" "\
 Define a method of sorting named NAME.
 DOCUMENTATION is the documentation of the function, which will be called
@@ -17114,9 +17081,7 @@ For sorting, the forms in BODY will be evaluated with `a' bound to one
 buffer object, and `b' bound to another.  BODY should return a non-nil
 value if and only if `a' is \"less than\" `b'.
 
-(fn NAME DOCUMENTATION (&key DESCRIPTION) &rest BODY)" nil t)
-(function-put 'define-ibuffer-sorter 'lisp-indent-function 1)
-(function-put 'define-ibuffer-sorter 'doc-string-elt 2)
+(fn NAME DOCUMENTATION (&key DESCRIPTION) &rest BODY)" nil 'macro)
 (autoload 'define-ibuffer-op "ibuf-macs" "\
 Generate a function which operates on a buffer.
 OP becomes the name of the function; if it doesn't begin with
@@ -17159,9 +17124,7 @@ BODY define the operation; they are forms to evaluate per each
 marked buffer.  BODY is evaluated with `buf' bound to the
 buffer object.
 
-(fn OP ARGS DOCUMENTATION (&key INTERACTIVE MARK MODIFIER-P DANGEROUS OPSTRING ACTIVE-OPSTRING BEFORE AFTER COMPLEX) &rest BODY)" nil t)
-(function-put 'define-ibuffer-op 'lisp-indent-function 2)
-(function-put 'define-ibuffer-op 'doc-string-elt 3)
+(fn OP ARGS DOCUMENTATION (&key INTERACTIVE MARK MODIFIER-P DANGEROUS OPSTRING ACTIVE-OPSTRING BEFORE AFTER COMPLEX) &rest BODY)" nil 'macro)
 (autoload 'define-ibuffer-filter "ibuf-macs" "\
 Define a filter named NAME.
 DOCUMENTATION is the documentation of the function.
@@ -17176,9 +17139,7 @@ not a particular buffer should be displayed or not.  The forms in BODY
 will be evaluated with BUF bound to the buffer object, and QUALIFIER
 bound to the current value of the filter.
 
-(fn NAME DOCUMENTATION (&key READER DESCRIPTION) &rest BODY)" nil t)
-(function-put 'define-ibuffer-filter 'lisp-indent-function 2)
-(function-put 'define-ibuffer-filter 'doc-string-elt 2)
+(fn NAME DOCUMENTATION (&key READER DESCRIPTION) &rest BODY)" nil 'macro)
 (register-definition-prefixes "ibuf-macs" '("ibuffer-"))
 
 
@@ -18088,8 +18049,9 @@ Toggle thumbnails in front of marked file names in the Dired buffer.
 If no file is marked, toggle display of thumbnail on the current file's line.
 ARG, if non-nil (interactively, the prefix argument), specifies the files
 whose thumbnail display to toggle instead of the marked files: if ARG is an
-integer, use the next ARG (or previous -ARG, if ARG<0) files; any other
-value of ARG means toggle thumbnail display of the current line's file.
+integer, use the next ARG (or previous -ARG, if ARG<0) files; if ARG is
+the symbol `marked', use only the marked files, if any; any other value of
+ARG means toggle thumbnail display of the current line's file.
 
 (fn &optional ARG)" '(dired-mode))
 (autoload 'image-dired-jump-thumbnail-buffer "image-dired-dired" "\
@@ -20017,7 +19979,9 @@ keys and associated values are:
     files that are concerned by the current operation (using relative names);
  `log-edit-diff-function' -- function taking no arguments that
     displays a diff of the files concerned by the current operation.
- `vc-log-fileset' -- the VC fileset to be committed (if any).
+ `vc-log-fileset' -- list of files to be committed, if any
+                     (not a true VC fileset structure as returned by
+                     `vc-deduce-fileset', but only the second element).
 
 If BUFFER is non-nil, `log-edit' will switch to that buffer, use it
 to edit the log message and go back to the current buffer when
@@ -27204,8 +27168,6 @@ evaluate the variable `rectangle-mark-mode'.
 The mode's hook is called both when the mode is enabled and when it is
 disabled.
 
-\\{rectangle-mark-mode-map}
-
 (fn &optional ARG)" t)
 (register-definition-prefixes "rect" '("apply-on-rectangle" "clear-rectangle-line" "delete-" "extract-rectangle-" "killed-rectangle" "ope" "rectangle-" "spaces-string" "string-rectangle-"))
 
@@ -29004,6 +28966,22 @@ disabled.
 (register-definition-prefixes "semantic/senator" '("semantic-up-reference" "senator-"))
 
 
+;;; Generated autoloads from send-to.el
+
+(autoload 'send-to-supported-p "send-to" "\
+Return non-nil for platforms where `send-to' is supported.")
+(autoload 'send-to "send-to" "\
+Send file(s) or region text to (non-Emacs) applications or services.
+
+Sending is handled by the first supported handler from `send-to-handlers'.
+
+ITEMS list is also populated by the resolved handler, but can be
+explicitly overridden.
+
+(fn &optional ITEMS)" t)
+(register-definition-prefixes "send-to" '("send-to-"))
+
+
 ;;; Generated autoloads from mail/sendmail.el
 
 (defvar mail-from-style 'angles "\
@@ -31509,7 +31487,10 @@ either customize it (see the info node `Easy Customization')
 or call the function `global-subword-mode'.")
 (custom-autoload 'global-subword-mode "subword" nil)
 (autoload 'global-subword-mode "subword" "\
-Toggle Subword mode in all buffers.
+Toggle Subword mode in many buffers.
+Specifically, Subword mode is enabled in all buffers where `(lambda
+nil (subword-mode 1))' would do it.
+
 With prefix ARG, enable Global Subword mode if ARG is positive;
 otherwise, disable it.
 
@@ -31517,9 +31498,6 @@ If called from Lisp, toggle the mode if ARG is `toggle'.
 Enable the mode if ARG is nil, omitted, or is a positive number.
 Disable the mode if ARG is a negative number.
 
-Subword mode is enabled in all buffers where `(lambda nil
-(subword-mode 1))' would do it.
-
 See `subword-mode' for more information on Subword mode.
 
 (fn &optional ARG)" t)
@@ -31558,7 +31536,10 @@ either customize it (see the info node `Easy Customization')
 or call the function `global-superword-mode'.")
 (custom-autoload 'global-superword-mode "subword" nil)
 (autoload 'global-superword-mode "subword" "\
-Toggle Superword mode in all buffers.
+Toggle Superword mode in many buffers.
+Specifically, Superword mode is enabled in all buffers where `(lambda
+nil (superword-mode 1))' would do it.
+
 With prefix ARG, enable Global Superword mode if ARG is positive;
 otherwise, disable it.
 
@@ -31566,9 +31547,6 @@ If called from Lisp, toggle the mode if ARG is `toggle'.
 Enable the mode if ARG is nil, omitted, or is a positive number.
 Disable the mode if ARG is a negative number.
 
-Superword mode is enabled in all buffers where `(lambda nil
-(superword-mode 1))' would do it.
-
 See `superword-mode' for more information on Superword mode.
 
 (fn &optional ARG)" t)
@@ -31693,7 +31671,10 @@ either customize it (see the info node `Easy Customization')
 or call the function `global-tab-line-mode'.")
 (custom-autoload 'global-tab-line-mode "tab-line" nil)
 (autoload 'global-tab-line-mode "tab-line" "\
-Toggle Tab-Line mode in all buffers.
+Toggle Tab-Line mode in many buffers.
+Specifically, Tab-Line mode is enabled in all buffers where
+`tab-line-mode--turn-on' would do it.
+
 With prefix ARG, enable Global Tab-Line mode if ARG is positive;
 otherwise, disable it.
 
@@ -31701,9 +31682,6 @@ If called from Lisp, toggle the mode if ARG is `toggle'.
 Enable the mode if ARG is nil, omitted, or is a positive number.
 Disable the mode if ARG is a negative number.
 
-Tab-Line mode is enabled in all buffers where `tab-line-mode--turn-on'
-would do it.
-
 See `tab-line-mode' for more information on Tab-Line mode.
 
 (fn &optional ARG)" t)
@@ -33980,7 +33958,7 @@ If the buffer runs `dired', the buffer is reverted." t)
 Visit the file or directory named on this line as the superuser.
 
 By default this is done using the \"sudo\" Tramp method.
-YOu can customize `tramp-file-name-with-method' to change this.
+You can customize `tramp-file-name-with-method' to change this.
 
 Interactively, with a prefix argument, prompt for a different method." t)
 (register-definition-prefixes "tramp-cmds" '("tramp-" "with-tramp-file-name-with-method"))
@@ -34058,7 +34036,7 @@ Interactively, with a prefix argument, prompt for a different method." t)
 
 ;;; Generated autoloads from net/trampver.el
 
-(push '(tramp 2 8 0) package--builtin-versions)
+(push '(tramp 2 8 1 -1) package--builtin-versions)
 (register-definition-prefixes "trampver" '("tramp-"))
 
 
@@ -35627,6 +35605,7 @@ The merge base is a common ancestor between REV1 and REV2 revisions.
 (fn FILES REV1 REV2)" t)
 (autoload 'vc-root-diff-incoming "vc" "\
 Report diff of all changes that would be pulled from REMOTE-LOCATION.
+When unspecified REMOTE-LOCATION is the place \\[vc-update] would pull from.
 When called interactively with a prefix argument, prompt for REMOTE-LOCATION.
 In some version control systems REMOTE-LOCATION can be a remote branch name.
 
@@ -35636,6 +35615,7 @@ global binding.
 (fn &optional REMOTE-LOCATION)" t)
 (autoload 'vc-root-diff-outgoing "vc" "\
 Report diff of all changes that would be pushed to REMOTE-LOCATION.
+When unspecified REMOTE-LOCATION is the place \\[vc-push] would push to.
 When called interactively with a prefix argument, prompt for REMOTE-LOCATION.
 In some version control systems REMOTE-LOCATION can be a remote branch name.
 
@@ -35752,12 +35732,12 @@ locked files at or below DIR (but if NAME is empty, locked files are
 allowed and simply skipped).
 If BRANCHP is non-nil (interactively, the prefix argument), switch to the
 branch and check out and update the files to their version on that branch.
+In this case NAME may not be empty.
 This function runs the hook `vc-retrieve-tag-hook' when finished.
 
 (fn DIR NAME &optional BRANCHP)" t)
 (autoload 'vc-switch-branch "vc" "\
 Switch to the branch NAME in the directory DIR.
-If NAME is empty, it refers to the latest revision of the current branch.
 Interactively, prompt for DIR only for VCS that works at file level;
 otherwise use the root directory of the current buffer's VC tree.
 Interactively, prompt for the NAME of the branch.
@@ -35801,12 +35781,14 @@ The command prompts for the branch whose change log to show.
 (fn BRANCH)" t)
 (autoload 'vc-log-incoming "vc" "\
 Show log of changes that will be received with pull from REMOTE-LOCATION.
+When unspecified REMOTE-LOCATION is the place \\[vc-update] would pull from.
 When called interactively with a prefix argument, prompt for REMOTE-LOCATION.
 In some version control systems REMOTE-LOCATION can be a remote branch name.
 
 (fn &optional REMOTE-LOCATION)" t)
 (autoload 'vc-log-outgoing "vc" "\
 Show log of changes that will be sent with a push operation to REMOTE-LOCATION.
+When unspecified REMOTE-LOCATION is the place \\[vc-push] would push to.
 When called interactively with a prefix argument, prompt for REMOTE-LOCATION.
 In some version control systems REMOTE-LOCATION can be a remote branch name.
 
@@ -35953,6 +35935,34 @@ When invoked interactively in a Log View buffer with
 marked revisions, use those.
 
 (fn ADDRESSEE SUBJECT REVISIONS)" t)
+(autoload 'vc-add-working-tree "vc" "\
+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.
+
+(fn BACKEND DIRECTORY)" t)
+(autoload 'vc-switch-working-tree "vc" "\
+Switch to this file or directory's analogue in working tree DIRECTORY.
+This command switches to the file or directory which has the same path
+relative to DIRECTORY that this buffer's file or directory 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.
+
+(fn DIRECTORY)" t)
+(autoload 'vc-delete-working-tree "vc" "\
+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.
+
+(fn BACKEND DIRECTORY)" t)
+(autoload 'vc-move-working-tree "vc" "\
+Relocate a working tree from FROM to TO.
+See Info node `(emacs)Other Working Trees' regarding VCS repositories
+with multiple working trees.
+
+(fn BACKEND FROM TO)" t)
 (register-definition-prefixes "vc" '("log-view-vc-prev-" "vc-" "with-vc-properties"))
 
 
@@ -37300,7 +37310,10 @@ either customize it (see the info node `Easy Customization')
 or call the function `global-visual-wrap-prefix-mode'.")
 (custom-autoload 'global-visual-wrap-prefix-mode "visual-wrap" nil)
 (autoload 'global-visual-wrap-prefix-mode "visual-wrap" "\
-Toggle Visual-Wrap-Prefix mode in all buffers.
+Toggle Visual-Wrap-Prefix mode in many buffers.
+Specifically, Visual-Wrap-Prefix mode is enabled in all buffers where
+`visual-wrap-prefix-mode' would do it.
+
 With prefix ARG, enable Global Visual-Wrap-Prefix mode if ARG is
 positive; otherwise, disable it.
 
@@ -37308,9 +37321,6 @@ If called from Lisp, toggle the mode if ARG is `toggle'.
 Enable the mode if ARG is nil, omitted, or is a positive number.
 Disable the mode if ARG is a negative number.
 
-Visual-Wrap-Prefix mode is enabled in all buffers where
-`visual-wrap-prefix-mode' would do it.
-
 See `visual-wrap-prefix-mode' for more information on
 Visual-Wrap-Prefix mode.
 
@@ -37757,7 +37767,10 @@ either customize it (see the info node `Easy Customization')
 or call the function `global-whitespace-mode'.")
 (custom-autoload 'global-whitespace-mode "whitespace" nil)
 (autoload 'global-whitespace-mode "whitespace" "\
-Toggle Whitespace mode in all buffers.
+Toggle Whitespace mode in many buffers.
+Specifically, Whitespace mode is enabled in all buffers where
+`whitespace-turn-on-if-enabled' would do it.
+
 With prefix ARG, enable Global Whitespace mode if ARG is positive;
 otherwise, disable it.
 
@@ -37765,9 +37778,6 @@ If called from Lisp, toggle the mode if ARG is `toggle'.
 Enable the mode if ARG is nil, omitted, or is a positive number.
 Disable the mode if ARG is a negative number.
 
-Whitespace mode is enabled in all buffers where
-`whitespace-turn-on-if-enabled' would do it.
-
 See `whitespace-mode' for more information on Whitespace mode.
 
 (fn &optional ARG)" t)
@@ -38414,7 +38424,10 @@ either customize it (see the info node `Easy Customization')
 or call the function `global-window-tool-bar-mode'.")
 (custom-autoload 'global-window-tool-bar-mode "window-tool-bar" nil)
 (autoload 'global-window-tool-bar-mode "window-tool-bar" "\
-Toggle Window-Tool-Bar mode in all buffers.
+Toggle Window-Tool-Bar mode in many buffers.
+Specifically, Window-Tool-Bar mode is enabled in all buffers where
+`window-tool-bar--turn-on' would do it.
+
 With prefix ARG, enable Global Window-Tool-Bar mode if ARG is
 positive; otherwise, disable it.
 
@@ -38422,9 +38435,6 @@ If called from Lisp, toggle the mode if ARG is `toggle'.
 Enable the mode if ARG is nil, omitted, or is a positive number.
 Disable the mode if ARG is a negative number.
 
-Window-Tool-Bar mode is enabled in all buffers where
-`window-tool-bar--turn-on' would do it.
-
 See `window-tool-bar-mode' for more information on Window-Tool-Bar
 mode.
 
@@ -38643,7 +38653,10 @@ either customize it (see the info node `Easy Customization')
 or call the function `global-word-wrap-whitespace-mode'.")
 (custom-autoload 'global-word-wrap-whitespace-mode "word-wrap-mode" nil)
 (autoload 'global-word-wrap-whitespace-mode "word-wrap-mode" "\
-Toggle Word-Wrap-Whitespace mode in all buffers.
+Toggle Word-Wrap-Whitespace mode in many buffers.
+Specifically, Word-Wrap-Whitespace mode is enabled in all buffers
+where `word-wrap-whitespace-mode' would do it.
+
 With prefix ARG, enable Global Word-Wrap-Whitespace mode if ARG is
 positive; otherwise, disable it.
 
@@ -38651,9 +38664,6 @@ If called from Lisp, toggle the mode if ARG is `toggle'.
 Enable the mode if ARG is nil, omitted, or is a positive number.
 Disable the mode if ARG is a negative number.
 
-Word-Wrap-Whitespace mode is enabled in all buffers where
-`word-wrap-whitespace-mode' would do it.
-
 See `word-wrap-whitespace-mode' for more information on
 Word-Wrap-Whitespace mode.
 
@@ -38990,9 +39000,9 @@ run a specific program.  The program must be a member of
 (provide 'loaddefs)
 
 ;; Local Variables:
+;; no-byte-compile: t
 ;; version-control: never
 ;; no-update-autoloads: t
-;; no-byte-compile: t
 ;; no-native-compile: t
 ;; coding: utf-8-emacs-unix
 ;; End:
diff --git a/lisp/vc/vc-dir.el b/lisp/vc/vc-dir.el
index 340a3f28756..93a05412a04 100644
--- a/lisp/vc/vc-dir.el
+++ b/lisp/vc/vc-dir.el
@@ -1415,7 +1415,7 @@ Throw an error if another update process is in progress."
           (vc-call-backend
            backend 'dir-status-files def-dir nil
            (lambda (entries &optional more-to-come)
-             ;; ENTRIES is a list of (FILE VC_STATE EXTRA) items.
+             ;; ENTRIES is a list of (FILE VC-STATE EXTRA) items.
              ;; If MORE-TO-COME is true, then more updates will come from
              ;; the asynchronous process.
              (with-current-buffer buffer
@@ -1520,7 +1520,7 @@ not under version control, prompt for a directory."
   (interactive)
   (let ((root-dir (vc-root-dir)))
     (if root-dir (vc-dir root-dir)
-      (call-interactively 'vc-dir))))
+      (call-interactively #'vc-dir))))
 
 ;;;###autoload
 (defun vc-dir (dir &optional backend)
diff --git a/lisp/vc/vc-git.el b/lisp/vc/vc-git.el
index 44af30b2eb0..680e74d8a6e 100644
--- a/lisp/vc/vc-git.el
+++ b/lisp/vc/vc-git.el
@@ -1913,12 +1913,15 @@ This requires git 1.8.4 or later, for the \"-L\" option of \"git log\"."
 (declare-function vc-read-revision "vc"
                   (prompt &optional files backend default initial-input))
 
+(defun vc-git--read-start-point (&optional dir)
+  (let ((branch (car (vc-git-branches))))
+    (vc-read-revision (format-prompt "Start point" branch)
+                      (list (or dir (vc-git-root default-directory)))
+                      'Git branch)))
+
 (defun vc-git-create-tag (dir name branchp)
   (let ((default-directory dir)
-        (start-point (when branchp (vc-read-revision
-                                    (format-prompt "Start point"
-                                                   (car (vc-git-branches)))
-                                    (list dir) 'Git (car (vc-git-branches))))))
+        (start-point (and branchp (vc-git--read-start-point dir))))
     (and (or (zerop (vc-git-command nil t nil "update-index" "--refresh"))
              (y-or-n-p "Modified files exist.  Proceed? ")
              (user-error (format "Can't create %s with modified files"
@@ -2340,7 +2343,7 @@ In other modes, call `vc-deduce-fileset' to determine files to stash."
   (vc-resynch-buffer (vc-git-root default-directory) t t))
 
 (defun vc-git-stash-list ()
-  (when-let* ((out (vc-git--run-command-string nil "stash" "list")))
+  (and-let* ((out (vc-git--run-command-string nil "stash" "list")))
     (split-string
      (replace-regexp-in-string
       "^stash@" "             " out)
@@ -2389,6 +2392,63 @@ In other modes, call `vc-deduce-fileset' to determine files to stash."
   (interactive "e")
   (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."
+  (with-temp-buffer
+    (vc-git-command nil 0 nil "worktree" "prune")
+    (vc-git-command t 0 nil "worktree" "list" "--porcelain" "-z")
+    (let (worktrees current-root current-rest)
+      (goto-char (point-min))
+      (while
+          (re-search-forward "\\=\\(\\([a-zA-Z]+\\)\\(?: \\([^\0]+\\)\\)?\\)?\0"
+                             nil t)
+        (if (match-string 1)
+            (let ((k (intern (match-string 2)))
+                  (v (or (match-string 3) t)))
+              (cond ((and (not current-root) (eq k 'worktree))
+                     (setq current-root (file-name-as-directory v)))
+                    ((not (eq k 'worktree))
+                     (push (cons k v) current-rest))
+                    (t
+                     (error "'git worktree' output parse error"))))
+          (push (cons current-root current-rest) worktrees)
+          (setq current-root nil current-rest nil)))
+      (or worktrees
+          (error "'git worktree' output parse error")))))
+
+(defun vc-git-known-other-working-trees ()
+  (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)
+  (letrec ((dir (expand-file-name directory))
+           (vc-filter-command-function #'list) ; see `vc-read-revision'
+           (revs (vc-git-revision-table nil))
+           (table (lazy-completion-table table (lambda () revs)))
+           (branch (completing-read (format-prompt "New or existing branch"
+                                                   "latest revision, detached")
+                                    table nil nil nil 'vc-revision-history))
+           (args (cond ((string-empty-p branch)
+                        (list "--detach" dir))
+                       ((member branch revs)
+                        (list dir branch))
+                       (t
+                        (list "-b" branch dir (vc-git--read-start-point))))))
+    (apply #'vc-git-command nil 0 nil "worktree" "add" args)))
+
+(defun vc-git-delete-working-tree (directory)
+  (vc-git-command nil 0 nil "worktree" "remove" "-f"
+                  (expand-file-name directory)))
+
+(defun vc-git-move-working-tree (from to)
+  ;; '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)
+  (let ((default-directory to))
+    (vc-git-command nil 0 nil "worktree" "repair")))
+
 
 ;;; Internal commands
 
diff --git a/lisp/vc/vc-hg.el b/lisp/vc/vc-hg.el
index 4e9057db4f9..976c8183efe 100644
--- a/lisp/vc/vc-hg.el
+++ b/lisp/vc/vc-hg.el
@@ -1217,7 +1217,7 @@ It is based on `log-edit-mode', and has Hg-specific extensions.")
 (defalias 'vc-hg-async-checkins #'always)
 
 (defun vc-hg-checkin (files comment &optional _rev)
-  "Hg-specific version of `vc-backend-checkin'.
+  "Hg-specific version of `vc-BACKEND-checkin'.
 REV is ignored."
   (let ((args (nconc (list "commit" "-m")
                      (vc-hg--extract-headers comment))))
@@ -1681,6 +1681,57 @@ Intended for use via the `vc-hg--async-command' wrapper."
                      (concat "paths." (or remote-name "default")))
       (buffer-substring-no-properties (point-min) (1- (point-max))))))
 
+(defun vc-hg-known-other-working-trees ()
+  ;; 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.
+  ;;
+  ;; Therefore, to support the VC API for other working trees, Emacs
+  ;; needs to maintain records of its own about other working trees.
+  ;; Rather than create something new our strategy is to rely on
+  ;; project.el's knowledge of existing projects.
+  ;; Note that this relies on code calling `vc-hg-add-working-tree'
+  ;; registering the resultant working tree with project.el.
+  (let* ((our-root (vc-hg-root default-directory))
+         (our-sp (expand-file-name ".hg/sharedpath" our-root))
+         our-store shares)
+    (if (file-exists-p our-sp)
+        (with-temp-buffer
+          (insert-file-contents-literally our-sp)
+          (setq our-store (string-trim (buffer-string)))
+          (push (abbreviate-file-name (file-name-directory our-store))
+                shares))
+      (setq our-store (expand-file-name ".hg" our-root)))
+    (dolist (root (project-known-project-roots))
+      (when-let* (((not (equal root our-root)))
+                  (sp (expand-file-name ".hg/sharedpath" root))
+                  ((file-exists-p sp)))
+        (with-temp-buffer
+          (insert-file-contents-literally sp)
+          (when (equal our-store (buffer-string))
+            (push root shares)))))
+    shares))
+
+(defun vc-hg-add-working-tree (directory)
+  (vc-hg-command nil 0 nil "share"
+                 (vc-hg-root default-directory)
+                 (expand-file-name directory)))
+
+(defun vc-hg--shared-p (directory)
+  (file-exists-p (expand-file-name ".hg/sharedpath" directory)))
+
+(defun vc-hg-delete-working-tree (directory)
+  (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)
+  (if (vc-hg--shared-p from)
+      (rename-file from (directory-file-name to) 1)
+    (user-error "\
+Cannot relocate first working tree because this would break other working trees")))
+
 (provide 'vc-hg)
 
 ;;; vc-hg.el ends here
diff --git a/lisp/vc/vc-hooks.el b/lisp/vc/vc-hooks.el
index f06736689aa..9fdc7fcf5a9 100644
--- a/lisp/vc/vc-hooks.el
+++ b/lisp/vc/vc-hooks.el
@@ -965,7 +965,11 @@ In the latter case, VC mode is deactivated for this buffer."
   "~"   #'vc-revision-other-window
   "R"   #'vc-rename-file
   "x"   #'vc-delete-file
-  "!"   #'vc-edit-next-command)
+  "!"   #'vc-edit-next-command
+  "w c" #'vc-add-working-tree
+  "w w" #'vc-switch-working-tree
+  "w x" #'vc-delete-working-tree
+  "w R" #'vc-move-working-tree)
 (fset 'vc-prefix-map vc-prefix-map)
 (define-key ctl-x-map "v" 'vc-prefix-map)
 
diff --git a/lisp/vc/vc.el b/lisp/vc/vc.el
index c4471a55440..6cb03c60919 100644
--- a/lisp/vc/vc.el
+++ b/lisp/vc/vc.el
@@ -207,6 +207,17 @@
 ;;   The default implementation deals well with all states that
 ;;   `vc-state' can return.
 ;;
+;; - known-other-working-trees ()
+;;
+;;   Return a list of all other working trees known to use the same
+;;   backing repository as this working tree.  The members of the list
+;;   are the abbreviated (with `abbreviate-file-name') absolute file
+;;   names of the root directories of the other working trees.
+;;   For some VCS, the known working trees will not be all the other
+;;   working trees, because other working trees can share the same
+;;   backing repository in a way that's transparent to the original
+;;   working tree (Mercurial is like this).
+;;
 ;; STATE-CHANGING FUNCTIONS
 ;;
 ;; * create-repo ()
@@ -342,6 +353,31 @@
 ;; - find-admin-dir (file)
 ;;
 ;;   Return the administrative directory of FILE.
+;;
+;; - add-working-tree (directory)
+;;
+;;   Create a new working tree at DIRECTORY that uses the same backing
+;;   repository as this working tree.
+;;   What gets checked out in DIRECTORY is left to the backend because
+;;   while some VCS can check out the same branch in multiple working
+;;   trees (e.g. Mercurial), others allow each branch to be checked out
+;;   in only one working tree (e.g. Git).
+;;   If a new branch should be created then the backend should handle
+;;   prompting for this, including prompting for a branch or tag from
+;;   which to start/fork the new branch, like `vc-create-branch'.
+;;
+;; - delete-working-tree (directory)
+;;
+;;   Remove the working tree, assumed to be one that uses the same
+;;   backing repository as this working tree, at DIRECTORY.
+;;   This removal should be unconditional with respect to the state of
+;;   the working tree: the caller is responsible for checking for
+;;   uncommitted work in DIRECTORY.
+;;
+;; - move-working-tree (from to)
+;;
+;;   Relocate the working tree, assumed to be one that uses the same
+;;   backing repository as this working tree, at FROM to TO.
 
 ;; HISTORY FUNCTIONS
 ;;
@@ -4178,24 +4214,24 @@ to provide the `find-revision' operation instead."
   t)
 
 (defun vc-default-retrieve-tag (backend dir name update)
-  (if (string= name "")
-      (progn
-        (vc-file-tree-walk
-         dir
-         (lambda (f) (and
-                 (vc-up-to-date-p f)
-                 (vc-error-occurred
-                  (vc-call-backend backend 'checkout f nil "")
-                  (when update (vc-resynch-buffer f t t)))))))
+  (if (string-empty-p name)
+      (vc-file-tree-walk dir
+                         (lambda (f)
+                           (and (vc-up-to-date-p f)
+                                (vc-error-occurred
+                                 (vc-call-backend backend 'checkout f nil "")
+                                 (when update
+                                   (vc-resynch-buffer f t t))))))
     (let ((result (vc-tag-precondition dir)))
       (if (stringp result)
           (error "File %s is locked" result)
         (setq update (and (eq result 'visited) update))
-        (vc-file-tree-walk
-         dir
-         (lambda (f) (vc-error-occurred
-                 (vc-call-backend backend 'checkout f nil name)
-                 (when update (vc-resynch-buffer f t t)))))))))
+        (vc-file-tree-walk dir
+                           (lambda (f)
+                             (vc-error-occurred
+                              (vc-call-backend backend 'checkout f nil name)
+                              (when update
+                                (vc-resynch-buffer f t t)))))))))
 
 (defun vc-default-revert (backend file contents-done)
   (unless contents-done
@@ -4301,6 +4337,136 @@ It returns the last revision that changed LINE number in FILE."
     (let ((rev (vc-call annotate-extract-revision-at-line 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."
+  ;; 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
+  ;; 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)
+    (with-temp-buffer
+      (setq default-directory directory)
+      (vc-call-backend (or backend (vc-responsible-backend directory))
+                       'dir-status-files directory files
+                       (lambda (entries &optional more-to-come)
+                         (let (entry)
+                           (while (setq entry (pop entries))
+                             ;; We shouldn't actually get any
+                             ;; `up-to-date' or `ignored' entries back,
+                             ;; but just in case, pass through a filter.
+                             (unless (memq (cadr entry)
+                                           '(up-to-date ignored))
+                               (push entry results))))
+                         (setq morep more-to-come)))
+      (while morep (accept-process-output)))
+    (nreverse 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."
+  (interactive
+   (list
+    (vc-responsible-backend default-directory)
+    (read-directory-name "Location for new working tree: "
+                         (file-name-parent-directory
+                          (or (vc-root-dir)
+                              (error "File is not under version control"))))))
+  (vc-call-backend backend 'add-working-tree directory)
+
+  ;; `vc-switch-working-tree' relies on project.el registration so try
+  ;; to ensure that both the old and new working trees are registered.
+  ;; `project-current' should not return nil in either case, but don't
+  ;; signal an error if it does.
+  (when-let* ((p (project-current)))
+    (project-remember-project p))
+  (when-let* ((p (project-current nil directory)))
+    (project-remember-project p))
+
+  (vc-dir directory backend))
+
+(defvar project-current-directory-override)
+
+;;;###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."
+  ;; FIXME: Switch between directory analogues, too, in Dired buffers.
+  (interactive
+   (list
+    ;; FIXME: This should respect `project-prompter'.  See bug#79024.
+    (completing-read "Other working tree to visit: "
+                     (vc-call-backend (vc-responsible-backend default-directory)
+                                      'known-other-working-trees)
+                     nil t)))
+  (let ((project-current-directory-override directory))
+    (project-find-matching-file)))
+
+;;;###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."
+  (interactive
+   (let ((backend (vc-responsible-backend default-directory)))
+     (list backend
+           ;; FIXME: This should respect `project-prompter'.  See bug#79024.
+           (completing-read "Delete working tree: "
+                            (vc-call-backend backend 'known-other-working-trees)
+                            nil t))))
+  ;; We could consider not prompting here, thus always failing when
+  ;; there is uncommitted work, and requiring the user to review and
+  ;; revert the uncommitted changes before invoking this command again.
+  ;; But other working trees are often created as throwaways to quickly
+  ;; test some changes, so it is more useful to offer to recursively
+  ;; delete them on the user's behalf.
+  (when (and (vc-dir-status-files directory nil backend)
+             (not (yes-or-no-p (format "\
+%s contains uncommitted work.  Continue to recursively delete it?" directory))))
+    (user-error "Aborted due to uncommitted work in %s" directory))
+
+  (project-forget-project directory)
+  (vc-call-backend backend 'delete-working-tree directory))
+
+(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."
+  (interactive
+   (let ((backend (vc-responsible-backend default-directory)))
+     (list backend
+           ;; FIXME: This should respect `project-prompter'.  See bug#79024.
+           (completing-read "Relocate working tree: "
+                            (vc-call-backend backend 'known-other-working-trees)
+                            nil t)
+           (read-directory-name "New location for working tree: "
+                                (file-name-parent-directory (vc-root-dir))))))
+  (let ((inhibit-message t))
+    (project-forget-project from))
+  (vc-call-backend backend 'move-working-tree from to)
+
+  ;; Update visited file names for buffers visiting files under FROM.
+  ;; FIXME: Also update VC-Dir buffers.
+  (dired-rename-subdir (expand-file-name from) (expand-file-name to))
+
+  (when-let* ((p (project-current nil to)))
+    (project-remember-project p)))
+
 
 
 ;; These things should probably be generally available
diff --git a/test/lisp/vc/vc-tests/vc-tests.el b/test/lisp/vc/vc-tests/vc-tests.el
index 82f28cdad3a..9f570ca0dd1 100644
--- a/test/lisp/vc/vc-tests/vc-tests.el
+++ b/test/lisp/vc/vc-tests/vc-tests.el
@@ -44,6 +44,7 @@
 ;; - latest-on-branch-p (file)
 ;; * checkout-model (files)                                     DONE
 ;; - mode-line-string (file)
+;; - other-working-trees ()                                     DONE
 
 ;; STATE-CHANGING FUNCTIONS
 ;;
@@ -65,6 +66,9 @@
 ;; - modify-change-comment (files rev comment)
 ;; - mark-resolved (files)
 ;; - find-admin-dir (file)
+;; - add-working-tree (directory)                               DONE
+;; - delete-working-tree (directory)                            DONE
+;; - move-working-tree (from to)                                DONE
 
 ;; HISTORY FUNCTIONS
 ;;
@@ -656,6 +660,103 @@ This checks also `vc-backend' and `vc-responsible-backend'."
         (ignore-errors
           (run-hooks 'vc-test--cleanup-hook))))))
 
+(defun vc-test--other-working-trees (backend)
+  "Test other working trees actions."
+  (ert-with-temp-directory tempdir
+    (let ((vc-handled-backends `(,backend))
+          (default-directory
+           (file-name-as-directory
+            (expand-file-name
+             (make-temp-name "vc-test") temporary-file-directory)))
+          (process-environment process-environment)
+          vc-test--cleanup-hook)
+      (unwind-protect
+          (progn
+            ;; Cleanup.
+            (add-hook
+             'vc-test--cleanup-hook
+             (let ((dir default-directory))
+               (lambda ()
+                 (delete-directory dir 'recursive)
+                 (dolist (name '("first" "second" "first"))
+                   (project-forget-project
+                    (expand-file-name name default-directory))))))
+
+            (let* ((first (file-name-as-directory
+                           (expand-file-name "first" default-directory)))
+                   (second (file-name-as-directory
+                            (expand-file-name "second" default-directory)))
+                   (third (file-name-as-directory
+                           (expand-file-name "third" default-directory)))
+                   (tmp-name (expand-file-name "foo" first)))
+
+              ;; Set up the first working tree.
+              (make-directory first t)
+              (let ((default-directory first))
+                (vc-test--create-repo-function backend)
+                (write-region "foo" nil tmp-name nil 'nomessage)
+                (vc-register `(,backend (,(file-name-nondirectory tmp-name)))))
+              (with-current-buffer (find-file-noselect tmp-name)
+                (vc-checkin (list (file-name-nondirectory tmp-name)) backend)
+                (insert "Testing other working trees")
+                (let (vc-async-checkin)
+                  (log-edit-done))
+
+                ;; Set up the second working tree.
+                ;; For the backends which do additional prompting (as
+                ;; specified in the API for this backend function) we
+                ;; need to stub that out.
+                (cl-ecase backend
+                  (Git (cl-letf (((symbol-function 'completing-read)
+                                  (lambda (&rest _ignore) "")))
+                         (vc-add-working-tree backend second)))
+                  (Hg (vc-add-working-tree backend second))))
+
+              ;; Test `known-other-working-trees'.
+              (with-current-buffer (find-file-noselect tmp-name)
+                (should
+                 (equal (list second)
+                        (vc-call-backend backend 'known-other-working-trees)))
+                (let ((default-directory second))
+                  (should
+                   (equal (list first)
+                          (vc-call-backend backend 'known-other-working-trees))))
+
+                ;; Test `move-working-tree'.
+                (vc-move-working-tree backend second third)
+                (should
+                 (equal (list third)
+                        (vc-call-backend backend 'known-other-working-trees)))
+                (should-not (file-directory-p second))
+                (should (file-directory-p third))
+                ;; Moving the first working tree is only supported
+                ;; for some backends.
+                (cl-ecase backend
+                  (Git
+                   (let ((default-directory third))
+                     (vc-move-working-tree backend first second))
+                   (let ((default-directory third))
+                     (should
+                      (equal (list second)
+                             (vc-call-backend backend
+                                              'known-other-working-trees))))
+                   (should-not (file-directory-p first))
+                   (should (file-directory-p second))
+                   (vc-move-working-tree backend second first))
+                  (Hg
+                   (let ((default-directory third))
+                     (should-error (vc-move-working-tree backend
+                                                         first second)))))
+
+                ;; Test `delete-working-tree'.
+                (let ((default-directory first))
+                  (vc-delete-working-tree backend third)
+                  (should-not (file-directory-p third))))))
+
+        ;; Save exit.
+        (ignore-errors
+          (run-hooks 'vc-test--cleanup-hook))))))
+
 ;; Create the test cases.
 
 (defun vc-test--rcs-enabled ()
@@ -794,7 +895,23 @@ This checks also `vc-backend' and `vc-responsible-backend'."
                           (eq system-type 'windows-nt)
                           noninteractive))
           (vc-test--version-diff ',backend))
-        ))))
+
+        (ert-deftest
+            ,(intern (format "vc-test-%s07-other-working-trees" backend-string)) ()
+          ,(format "Check other working trees functions for the %s backend."
+                   backend-string)
+          (skip-unless
+           (ert-test-passed-p
+            (ert-test-most-recent-result
+             (ert-get-test
+              ',(intern
+                 (format "vc-test-%s01-register" backend-string))))))
+          (skip-unless (memq ',backend '(Git Hg)))
+          (skip-when
+           (and (eq ',backend 'Hg)
+                (equal (car (process-lines-ignore-status "hg" "share"))
+                       "hg: unknown command 'share'")))
+          (vc-test--other-working-trees ',backend))))))
 
 (provide 'vc-tests)
 ;;; vc-tests.el ends here