See the vesta-intro man page's Terminology section for definitions of terms, and its hoName Interpretation section for an explanation of how names are looked up.
The vbranch command creates a branch of a package in the Vesta repository. A branch is a new package that is (usually) placed as a subdirectory of the parent package, with a name based on one of the versions of the parent package (the branch base), and with a version 0 that is identical to the branch base.
For example, if common/cxx/2 is an existing package version, "vbranch common/cxx/2.bugfix" will create a new package named common/cxx/2.bugfix, with version common/cxx/2.bugfix/0 being identical to the branch base common/cxx/2.
In more detail, vbranch:
- Creates a new appendable directory named package/branch, containing an appendable subdirectory named checkout.
- Creates a master stub named latest in each of those directories.
- Binds the name package/branch/0 to the same immutable directory named by old-version.
- Sets attributes as follows:
- On branch
- created-by, creation-time, old-version, and type (= {"package", "branch"}).
- On branch/checkout
- type.
- On branch/latest
- symlink-to (= $LAST).
- On branch/checkout/latest
- symlink-to (= $LAST).
- On branch/0
- old-version.
If the name package is unqualified (does not have "/", ".", or ".." as its first arc), it is interpreted relative to the site's default directory of packages, DefaultPackageParent. If package is omitted (that is, if the argument to vbranch does not contain a "/"), it defaults to ".". If the name old-version is unqualified, it is interpreted relative to package.
You must have write access to package. The newly created branch is owned by you, but has access permissions inherited from package.
In the presence of replication, branch creation cannot always be carried out entirely in the local repository. In particular, the local repository may contain no replica of one of the needed objects, or it may contain a non-master replica where the master replica is needed. Also, the -m/-M flags control which repository vbranch will give mastership of the created branch. (See vrepl(1) and vmaster(1) for more information about replication and mastership.) The exact steps are slightly different depending on which repository has the master copy of package and whether the local repository is to have the master copy of the created branch (controlled by the -m/-M flags).
If package is mastered locally, vbranch creates the branch in the local repository (and the -m/-M flags have no effect). However, if old-version does not exist locally, vbranch searches for a copy and replicates it to the local repository before creating the branch.
If package is not mastered locally, vbranch may give mastership of branch to the local repository, if either the -m flag is specified or [UserInterface]vbranch_acquires is set to true. If old-version does not exist locally, vbranch searches for a copy and replicates it to the local repository. vbranch then creates the branch remotely in the master copy of package (except for inserting old-version), replicates it to the local repository, transfers mastership, and finally inserts old-version.
If the -M flag is specified or [UserInterface]vbranch_acquires is set to false and package is mastered remotely, vbranch will leave mastership of branch with the master repository of package. In this case, if old-version does not exist in the remote master repository, vbranch searches for a copy and replicates it to that repository. vbranch then creates the branch remotely in the master copy of package (including inserting old-version), and replicates it to the local repository.
vbranch returns status 0 for success, 1 for parameter syntax errors, or 2 for more serious errors.