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 (see Version Control Branches) checked out simultaneously, in different working trees, but with all revision history, branches, tags and other metadata shared.
Suppose your project has a trunk where you’re developing the new version 3 of your software, and a stable release branch from which you make point releases of version 2. Someone sends you a patch fixing a bug that’s present in version 2. Your main working tree has version 3 checked out, and you’re in the middle of a big refactor that you don’t want to disturb. So you type C-x v w c (see below) and create a new working tree, following the prompts to check out the version 2 branch there.
You apply the patch to that working tree using C-x v w a (see below), build and test it. Satisfied, you use C-x v P (see Pulling/Pushing Changes into/from a Branch) in the other working tree. In the course of testing the patch, you’ve realized that the bug exists in version 3 of the software, too. So you switch back to your first working tree, and use C-x v m (see Merging Branches) to merge the branch you have checked out in the other working tree. Now your version of the trunk has all of version 2’s fixes merged into it, but you haven’t pushed it yet because you’re still refactoring. You’ll use C-x v P later.
Ordinary VC commands like C-x v v (see Basic Editing under Version Control) and C-x v d (see VC Directory Mode) 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. Another way to put this is that any action taken in any working tree which creates new artifacts in the VCS backing store will be visible from other working trees, but actions which only affect workfiles won’t be. So if you apply a patch to some workfiles in one working tree, that only affects that working tree. But if you commit the changes made by applying the patch, then that creates a new revision in the backing store, and so this action affects other working trees in the sense that their view of the repository’s history will now have an additional commit in it.
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
default-directory (see File Names) is within a VC working
tree.
Add a new working tree.
Visit this file or directory in another working tree.
Kill buffers visiting this file in other working trees.
Invoke C-x p p (project-switch-project) but limited to
other working trees.
Copy or move fileset changes to another working tree.
Copy or move all changes to another working tree.
Delete a working tree you no longer need.
Relocate a working tree to another file name.
You can start using multiple working trees by using the command
C-x v w c (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.
Once your repository has other working trees, you can use the command
C-x v w w (vc-switch-working-tree) to switch between them.
It tries to find the analogue of the current buffer’s file or directory
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 or directory the current
buffer visits probably exists in other working trees too, and this
command lets you switch to those versions of the file.
C-x v w w also works in Diff mode (see Diff Mode) and Log View
mode (see VC Change Log). Instead of switching to a different
buffer, the command changes the default directory of the buffer to the
corresponding directory under another working tree. This is
particularly useful from Log View mode buffers generated by commands
like C-x v L (see VC Change Log). After using C-x v w w
to change the default directory of the Log View buffer, you can move
point to a revision of interest and type = (log-view-diff)
to open a Diff mode buffer with that revision’s changes. Then you can
use standard Diff mode commands like C-c C-a
(diff-apply-hunk) to apply hunks to the other working tree.
After using C-x v w w in file-visiting buffers you will have
multiple buffers visiting identically named files (see Making Buffer Names Unique).
You can kill all but one of these buffers by typing C-x v w k
(vc-kill-other-working-tree-buffers). This command kills buffers
visiting versions of the current buffer’s file in other working trees,
preserving the current buffer. It does not work in non-file-visiting
buffers.
An alternative way to switch between working trees is C-x v w s
(vc-working-tree-switch-project). This prompts you to select a
working tree, and then displays a menu of commands to operate on it.
This is in fact just C-x p p (project-switch-project)
(see Switching Projects) but with the selection of projects limited
to other working trees. The main difference between C-x v w w and
C-x v w s is that the former looks for an analogue of the current
buffer in the other working tree while the latter considers the other
working tree as a whole, independent project.
The command C-x v w a (vc-apply-to-other-working-tree)
prompts you to select another working tree, then copies changes from the
current working tree to that other working tree. With a prefix
argument, it moves changes instead of just copying them. Usually the
command operates on local (uncommitted) changes to the current VC
fileset. When invoked in a buffer under Diff mode (see Diff Mode), it
operates on the changes specified by the contents of that buffer. The
command stops and does nothing if any of the changes don’t apply to the
target working tree.
C-x v w a is useful to copy changes to a temporary working tree in order to test them. It is also useful to copy fixes back to your main working tree for checking in. For example, you might hack away at a bug in a temporary working tree, and fix it. You’d then want to copy or move the fix back to your main working tree to check it in and push it.
The command C-x v w A works similarly, except that it always copies or moves all local changes to the whole working tree, not just changes to the current VC fileset or changes represented by the contents of a Diff mode buffer. With two prefix arguments, this command shows a preview of changes to be copied, leaving you to apply them using standard Diff mode commands like C-c C-a and C-c <RET> a (see Diff Mode). (C-u C-u C-x v w A is roughly equivalent to typing C-x v D followed by C-x v w w.)
The commands C-x v w x (vc-delete-working-tree) and
C-x v w R (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.