Link an existing version into a working directory
Suppose you want a copy of an existing checked-in version as a subdirectory in a checkout you're working on. You could simply copy it using the filesystem:
% cd /vesta-work/jsmith/pkg1 % cp -r /vesta/example.com/pkg2/1 subdir
This is wasteful, as it moves a lot of data over the network and forces the repository to store two copies of the files (at least until you run vadvance). It would be nicer to simply ask the repository to place a copy of the existing directory into the working directory for us.
vcheckout is the only tool that knows how to make a mutable working copy of an existing immutable directory, so that's the tool we'll use. However, we don't want vcheckout to do some of the things it normally does:
We don't want to reserve a new version, so we need to give the -N flag on the command line
We don't want to create a session directory, so we need to give the -S flag on the command line
Also, we'll tell vcheckout where we want the copy with the -w flag.
So here's how we can do the same thing as the example above:
% vcheckout -S -N -o 1 -w /vesta-work/jsmith/pkg1/subdir /vesta/example.com/pkg2
After this, /vesta-work/jsmith/pkg1/subdir will be a copy of /vesta/example.com/pkg2/1. This requires no copying of files, and happens very quickly.
Note that you can combine this with using a sub-directory as the old-version of a checkout to get a copy of a subdirectory of an existing version, rathern than an entire existing version.
Q&A
Q: (JohnVk) what happens when you vcheckin /vesta-work/jsmith/pkg1? Does it simply scan recursively pkg1 on down using the [?] interface? Or does it actually modify pkg1's vesta internal data structure of names it knows about.
A: (KenSchalk) Nothing special happens at checkin time. A particular snapshot of the working directory becomes the new version and the working directory (/vesta-work/jsmith/pkg1) gets deleted. Deleting it simply unlinks the entire directory tree rooted there (including /vesta-work/jsmith/pkg1/subdir).
Maybe though you're more interested in what happens at vadvance time. That does recursively walk the entire directory structure below the working directory to create the snapshot.
This trick really is exactly like creating a hard link to the existing immutable directory. Nothing has to be copied, and internally the storage for /vesta-work/jsmith/pkg1/subdir) refers to the same data structures as /vesta/example.com/pkg2/1 (unless you modify it).