vadvance(1)

Name

vadvance - Advance to the next version within a Vesta checkout session

Synopsis

vadvance [-t] [-q] [-Q] [-f] [-F fp-content] [-j junk | -J] [-z maxsize | -Z] [-s session-dir] [-a session-ver-arc] [-R repos] [[-w] work-dir]

In the most common usage, vadvance is invoked from the checkout session's working directory, and no arguments are needed.

Contents

Description

See the vesta-intro man page's Terminology section for definitions of terms, and its Name Interpretation section for an explanation of how names are looked up.

The vadvance command cleans up and snapshots the contents of a working directory to form the next version in a Vesta checkout session.

In more detail: vadvance's cleanup phase walks the directory tree rooted at work-dir. If the last arc of any file's name matches one of the patterns in junk, the file is deleted. Here junk is a space-separated list of glob(3) patterns. If a file added since the last advance is larger than maxsize, vadvance exits with an error message upon encountering it. Next, by default, vadvance checks whether anything under work-dir has changed since the last advance; if not, it exits with an informational message. Finally, vadvance's snapshot phase binds session-dir/session-ver-arc to a new immutable directory that is a copy of the mutable directory work-dir, and then sets the session-ver-arc attribute of work-dir to session-ver-arc.

vadvance figure

You must have read and write access to work-dir and write access to session-dir. The newly created snapshot is owned by you, but has access permissions inherited from session-dir.

Without the -t flag, vadvance returns status 0 if the advance was successful or if no advance was performed because nothing changed, 1 for parameter syntax errors, or 2 for more serious errors. See the description of -t below for how it affects the exit status.

Flags

-q
Quiet; suppress printing out what is being done.
-Q
Query; print out what the command would do, but don't do it.
-t
Test; exit with 0 status only if no advance would be performed because nothing changed. Exit with 255 if the working directory has been modified. Implies -Q.
-w work-dir
The mutable working directory to snapshot to produce the new version. If you place this option last on the command line, you can omit the -w. If the name work-dir is unqualified (does not have "/", ".", or ".." as its first arc), it is interpreted relative to DefaultWorkParent/user, where user is your local user name. Defaults to the current directory.
-s session-dir
The session directory that will hold the new version. If the name session-dir is unqualified, it is interpreted relative to the site's default directory of packages, DefaultPackageParent. Defaults to the session-dir attribute of work-dir, if any.
-a session-ver-arc
The new version in the session directory. Must be a single arc (i.e., must contain no "/" characters). Defaults to the highest version number bound in session-dir plus 1. That is, session-dir is searched for arcs consisting entirely of decimal digits, the one with the highest value is chosen, and it is incremented by 1 to obtain the default. If no such arcs are found, the default is set to 1.
-f
Force; omit sanity checking. If the -f flag is not given:
  • The directory session-dir must be of type "session". (That is, its type attribute must include this value.)
  • Some file or directory in the tree rooted at the working directory must have changed since the last vadvance.
-F fp-content
Any new or modified files in the directory that are strictly less than fp-content bytes long are fingerprinted deterministically according to their contents. Longer files are fingerprinted with arbitrary unique identifiers. The cost of fingerprinting a file's contents is non-trivial, but doing so allows for cache hits in cases where two evaluations depend on files that have identical contents but were inserted into the repository separately. The default value for this parameter is determined by the Vesta configuration file; see below. The special value -1 causes all files to be fingerprinted by contents, while 0 causes all files to be fingerprinted by unique identifier.
-j junk
A space-separated list of glob(3) patterns used to delete unwanted files from the working directory tree before advancing. If the last arc of a file's name matches one of the patterns in junk, and the file was created or modified since the last advance, the file is deleted. The default value is obtained from the Vesta configuration file; see below.
-J
Clears the junk pattern list; equivalent to -j "".
-z maxsize
Size of the largest new file that vadvance will advance into the repository, in bytes. If a file larger than maxsize was created or modified since the last advance, the new advance will fail with an error message. The default value is obtained from the Vesta configuration file; see below.
-Z
Disables the file size limit; equivalent to -z -1.
-R repos
Advance the package in repos instead of the default local repository. The repository is specified by host name and TCP port number in the format host:port. The :port portion may be omitted; it defaults to [Repository]VestaSourceSRPC_port.

Configuration

The following values are obtained from the [UserInterface] section of the Vesta configuration file (vesta.cfg).

AppendableRootName
The filename under which the global root directory of Vesta repositories is mounted. Ordinarily set to /vesta.
MutableRootName
The filename under which the local tree of mutable directories provided by Vesta is mounted. Ordinarily set to /vesta-work.
DefaultPackageParent
The default directory to put new packages in. Ordinarily a subdirectory of the appendable root, named with an Internet domain name belonging to the local site.
DefaultWorkParent
The default parent directory for mutable working directory trees belonging to individual users. Ordinarily the same as the mutable root.
realm
Global user names are formed by appending @realm to the local name.
TimeFormat
A format string for strftime(3) to produce time strings for Vesta attributes. A common setting is "%a %b %e %T %Z %Y".
FpContent
The default value for the -F flag.
vadvance_junk
The default value for the -j flag. If not set, the default is "*~ .*~ core".
vadvance_maxsize
The default value for the -z flag. If not set, the default is 1048576 (1 megabyte).

The following values are obtained from the [Repository] section of the Vesta configuration file.

VestaSourceSRPC_host
The host name of the default (local) repository.
VestaSourceSRPC_port
The default TCP port number for repositories.

Limitations

See Also

vesta-intro(1), repos-ui(1)

Author

Tim Mann 

Last modified on Wed Apr 30 00:00:17 PDT 2003 by mann
     modified on Tue Apr 22 21:51:37 EDT 2003 by scott@scooter.cx
     modified on Tue Nov 13 11:49:37 EST 2001 by ken@xorian.net  
     modified on Wed Feb 19 15:21:27 PST 1997 by heydon
This page was generated automatically by mtex software.