• RepositoryRules

Repository Filesystem Rules

The repository is a virtual filesystem. You mount it using an NFS client. You can browse it and perform operations within it from the command line or using any other filesystem tools. However, it has certain rules that it enforces.

Roots

The repository root (also called "the appendable root") is normally mounted as "/vesta". In fact, "/vesta" is used in all canonical names for objects in the repository. (Mostly those are the names printed by tools like vcheckout and stored in attributes like old-version.)

The mutable root is normally mounted as "/vesta-work" (which is also its canonical name).

There is a third root called the volatile root, which is normally mounted as "/vesta-work/.volatile". This is where the temporary directories used during builds exist. Users almost never interact directly with anything in the volatile root.

Object Types

Objects in the repository have types, which can't be represented through the filesystem interface. For example, there are several different types of directories, but there's no way to tell the difference between them using the filesystem interface.

To get information on an object's type, use vattrib.

Appendable Directories

The repository root is an appendable directory. Many directories you find below it are also appendable directories. Packages are appendable directories. (The repository tools treat packages differently from other appendable directories, but only because of their attributes.)

Appendable directories have several rules:

• Once you create something with a particular name in an appendable directory, you can't get rid of that name.

• If you delete something in a master appendable directory, it will leave behind a ghost

Appendable directories can contain:

• Appendable directories
• Immutable directories
• Stubs
• Ghosts

Theoretically, an immutable file could be placed directly in an appendable directory (i.e. versioning a file rather than a directory). No tools exist to do this, but one could be written.

To support Vesta's partial replication feature, there are two kinds of appendable directory, master and nonmaster. Each appendable directory can have its master replica in only one repository, but there can be nonmaster replicas in many other repositories. All the replicas have the same canonical name. A directory's master replica must contain every name that exists in any of the directory's replicas, but a nonmaster replica often doesn't contain all the names that exist in the master replica. In any replica (including the master), some of the names may be bound to ghosts or stubs even if they are bound to something else in other replicas.

Inside a master appendable directory you can:

• Use mkdir or vmkdir to create a new master appendable directory.

• Remove an existing object with rm, rmdir, or vrm and leave behind a ghost. (This operation is usually restricted to administrators.)

• Change permissions with chmod, chown, and chgrp.

• Create a stub or immutable directory using one of the repository tools.

• Use vrepl to replicate in content from another repository. Note that doing this replaces a stub or ghost, because of the rule that the master always contains all names.

Inside a nonmaster appendable directory you can:

• Use vrepl to replicate in content from another repository.

• Remove an existing object with rm, rmdir, or vrm and leave behind a ghost.

Inside an appendable directory you cannot:

• Create a file through the NFS interface. (Theoretically you could add an immutable file to a master appendable directory using the repository's API.)
• Rename an existing object.
• Reuse a name that has existed before. (Ghosts prevent this)
• Directly create a symlink (but see under Stubs below)
• Create a hard link

Immutable Directories

An immutable directory is a directory whose contents cannot be changed. The versions in a package or session are immutable directories. They are normally created with vcheckin or vadvance.

Immutable directories can contain:

• Immutable files
• Immutable directories

Stubs

A stub is a placeholder for an object that doesn't exist yet or doesn't exist here.

Master stubs are version reservations created by vcheckout. A master stub can be replaced with any other object later. Master stubs are often replaced with immutable directories by vcheckin.

Nonmaster stubs are placeholders for objects that don't exist in this repository, but may exist in some other repository. A nonmaster stub may be replaced later by replicating the object it is standing in for from a repository that has a copy.

Stubs can also be used to create symbolic links. A stub with a symlink-to attribute will be appear as a symbolic link in the filesystem interface. The latest symlink in a package is a stub. Because a symlink's value is mutable, symlinks aren't visible to the Vesta evaluator; they are only a convenience feature for users browsing the repository.

A stub can exist only in an appendable directory.

Ghosts

A ghost is a placeholder for a name that used to exist, to prevent it from being reused in the future with a different meaning. Ghosts are created by deleting an existing object from an appendable directory, typically with rm, rmdir, or vrm.

You can revive a ghost by replicating in a copy of the object that its name used to belong to from another repository, using vrepl -r. Without the -r flag, vrepl assumes you want the ghost to stay dead.

A ghost can exist only in an appendable directory.

Mutable Directories

Mutable directories can be changed arbitrarily. They don't have the kind of restrictions that appendable and immutable directories have. Mutable directories are found only under the mutable root (/vesta-work).

The working copies created by vcheckout for editing are mutable directories. Each user's directory containing their working copies (/vesta-work/jsmith) is a mutable directory.

Inside a mutable directory you can:

• Create, delete, and rename files and directories
• Modify files

• Change permissions with chmod, chown, and chgrp

Inside a mutable directory you cannot:

• Create symbolic links (at least not currently)
• Create hard links
• Create appendable directories, immutable directories, ghosts, or stubs