.ig Copyright (C) 1993,1994 by the author(s). This software is published in the hope that it will be useful, but WITHOUT ANY WARRANTY for any part of this software to work correctly or as described in the manuals. See the ShapeTools Public License for details. Permission is granted to use, copy, modify, or distribute any part of this software but only under the conditions described in the ShapeTools Public License. A copy of this license is supposed to have been given to you along with ShapeTools in a file named LICENSE. Among other things, this copyright notice and the Public License must be preserved on all copies. Authors: Andreas Lampen (Andreas.Lampen@cs.tu-berlin.de) Axel Mahler (Axel.Mahler@cs.tu-berlin.de) $Header: vadm.1[10.0] Fri Jul 9 16:30:15 1993 andy@cs.tu-berlin.de frozen $ .. .TH vadm 1 "Fri Jul 9 16:30:15 1993" "vadm-4.10" "ShapeTools" .SH NAME vadm \- manipulate and administer version object base .SH SYNOPSIS .na \fBvadm\fP [ \fIversion binding options\fP ] [\ \fIoptions\fP\ ]\ [\ \fIaction\fP\ ] name\|.\|. .br .IP \fIOptions:\fP \w'\fIOptions:\0\fP'u [\ \fB\-?fq\fP\ ] [\ \fB\-cache\fP\ ] [\ \fB\-force\fP\ ] [\ \fB\-help\fP\ ] [\ \fB\-nomail\fP\ ] [\ \fB\-quiet\fP\ ] [\ \fB\-stdin\fP\ ] [\ \fB\-version\fP\ ] .IP \fIActions:\fP \w'\fIOptions:\0\fP'u [\ \fB\-alias\fP\ \fIversion alias name\fP\ ] [\ \fB\-attr\fP\ \fIattribute\fP\ ] [\ \fB\-chaut\fP\ \fIuser\fP\ ] [\ \fB\-chmod\fP\ \fIprotection\fP\ ] [\ \fB\-chown\fP\ \fIuser\fP\ ] [\ \fB\-delattr\fP\ \fIattribute name\fP\ ] [\ \fB\-d\fP\ (or\ \fB\-delete\fP)\ ] [\ \fB\-l\fP\ (or\ \fB\-lock\fP)\ [\fIversion binding\fP\] ] [\ \fB\-newgen\fP\ ] [\ \fB\-promote\fP\ ] [\ \fB\-set\fP\ \fIdescription\fP\ |\ \fInote\fP\ |\ \fIintent\fP\ ] [\ \fB\-setc\fP\ \fIcomment leader\fP\ ] [\ \fB\-unlock\fP\ [\fIversion\ binding\fP\]\ ] [\ \fB\-unpromote\fP\ ] .br .IP "\fBvattr\fP\ [ \fIversion binding options\fP ] attribute name\|.\|. .br .IP "\fBvrm\fP\ [ \fIversion binding options\fP ] name\|.\|. .br .IP "\fBsbmt\fP\ [ \fIversion binding options\fP ] name\|.\|." .br .IP "\fBpubl\fP\ [ \fIversion binding options\fP ] name\|.\|." .br .IP "\fBaccs\fP\ [ \fIversion binding options\fP ] name\|.\|." .br .IP "\fBfrze\fP\ [ \fIversion binding options\fP ] name\|.\|." .ad .SH DESCRIPTION .LP \fBvadm\fP is a general purpose command to perform all sorts of actions upon parts of an AtFS object repository. It can be used to lock or unlock an AtFS object for modification, to delete a particular object instance, to associate symbolic (alias) names with version objects, to promote or unpromote certain version objects from one status to another, to modify an objects access permissions, to set or modify a descriptive entry of particular version objects, to set or modify an eventual change intention, and to set or unset various object attributes such as the author or any user defined attributes. .LP \fBvattr\fP and \fBvrm\fP are short forms for \fIvadm -attr\fP and \fIvadm -delete\fP. See the descriptions of the \fI\-attr\fP and the \fI\-delete\fP options for details. .LP \fBsbmt\fP, \fBpubl\fP, \fBaccs\fP, and \fBfrze\fP are alternate program names for \fBvadm\fP that represent \fIstatus-change\fP operations for version objects. See the description of option \fB\-promote\fP for details. .LP The typical command invocation is supplemented by one or more \fIcommand options\fP, \fIversion binding options \fP defining the versions to be acted upon, an \fIaction specifier\fP indicating the sort of action to be performed, and a set of \fIobject names\fP defining the initial subset of the object base that's going to be manipulated. .LP Object names may be given in \fIbound version notation\fP, i.e. a notation that identifies a particular version of an object (e.g. \fCmkattr.c[2.4]\fP). It is also possible to use a previously assigned \fIsymbolic name\fP rather than a numerical version identification (e.g. \fCmkattr.c[tools-V4R3]\fP). Make sure to escape the bracket-symbols when using \fBcsh(1)\fP or \fBtcsh(1)\fP because they have meaning to these shells. .SH OPTIONS .LP For version selection, any \fIversion binding option\fP, as described on the vbind(1) manual page, may be given, or a \fIversion bind directive\fP may be given in brackets added to the file name. .IP "\fB\-?, \-help\fP" print brief instructions about using \fBvadm\fP .IP "\fB\-cache\fP" apply the requested operation to objects residing in the \fIderived object cache\fP. The set of actions that may be performed on binary pool objects is limited. .IP "\fB\-f, \-force\fP" don't ask for confirmation when deleting versions from a history. .IP "\fB\-nomail\fP" Suppress the notification mail to the user who holds the lock on a history when breaking this lock (\fI\-unlock\fP option). .IP "\fB\-q, -quiet\fP" suppress any prompts, informal messages and user dialogues. Default values are assumed for everything that might otherwise be inquired interactively. This option is useful for batch operation. .IP "\fB\-stdin\fP" forces \fBvadm\fP to read a descriptive text, note or intent from standard input if action \fB\-set\fP is selected. The note is used for \fIall\fP specified AtFS objects. Otherwise your favorite editor (taken from the EDITOR environment variable) is invoked. .IP "\fB\-version\fP" print version information about the \fBvadm\fP program itself. No action will be performed on the database. .LP \fBvadm\fP will perform all of its operations upon a specified set of AtFS version objects. In case no such set is specified, the operation will be applied to the most recently saved versions of the named object(s). .SH ACTIONS The kind of action to be performed upon a specified set of AtFS objects is indicated by a keyword. The following actions are defined: .IP "\fB\-alias\fP\ \fIversion\ alias\ name\fP" assigns the \fIversion alias name\fP to the specified version. The name works as an alias for the version number, so it must be different from any other symbolic name assigned to any version object in a particular object history. It is, however, possible to assign the same symbolic name to version objects in \fIdifferent object histories\fP. An object history is usually denoted by a name, similarly to a files name. .sp 0.05i The use of alias names is a simple but effective way to associate component members of a \fIsystem configuration\fP. Typical symbolic names will look something like \fIMysystem_Release_4.22\fP, indicating that version objects with this name are part of release 4.22 of the system in question. .IP "\fB\-attr\fP\ \fIattrname\fP Return rthe value of the named attribute. This may be a \fIstandard attribute\fP or a \fIuser defined attribute\fP. Check the list below for a complete list of standard attribute names. .IP "\fB\-attr\fP\ \fIattrname\fP[\fI+\fP|\fI-\fP]=[\fI@\fP|\fI^\fP|\fI!\fP|\fI*\fP]\fIvalue\fP" defines a \fIuser defined attribute\fP with name \fIattrname\fP and sets it to the value \fIvalue\fP for all specified version objects. This option may also be used to set the value of certain \fIstandard attributes\fP (see list below). If \fIattrname\fP is followed by a single equal-symbol, the respective value of the object is set (or reset) to the specified value. Any previous values will be overwritten. If \fIattrname\fP is immediately followed by the symbols ``plus-equal'' (\fC+=\fP), the specified attribute value will be appended to the current value of the referenced attribute. Accordingly, ``minus-equal'' (\fC-=\fP) should remove the specified value from the given attribute. In the current implementation, removal of single values is not supported. .sp 0.05i There are four basic kinds of user defined attribute values: \fIgenuine values\fP, \fIreference values\fP, \fIexecution values\fP, and \fIpointer values\fP. The kind of an attribute value is determined when it is set. If the first character of \fIvalue\fP is an at character (@), the rest of \fIvalue\fP is taken to be the \fIname of a file\fP the contents of which will be taken as the value of the attribute. This substitution takes place immediately, i.e. the attribute has a genuine value. If the filename is specified as ``\-'', the attributes value will be read from standard input. If the first character is a circumflex character (^), the rest of \fIvalue\fP is interpreted as the name of a file whose contents will be substituted for the attribute when it is cited. If the first character of \fIvalue\fP is an exclamation mark character (!), the rest of \fIvalue\fP is interpreted as the \fIname of a program\fP whose standard output will be substituted for the attribute when it is cited. Execution values can be used to generate highly dynamic attributes or even a primitive form of event triggers. An asterisk (*) as first character of \fIvalue\fP indicates a pointer to another version. In this case, the remainder of value must be a valid bound filename. .sp 0.05i User defined attributes may be of arbitrary length. Any sequence of ASCII characters \- with the exception of \e01 (control-A) \- is allowed to make up an attribute value. If \fIattrname\fP was already set to some value, the previous value will be replaced by the newly specified one. .IP "\fB\-attr\fP\ \fI@attrfile\fP" With a \fI@filename\fP argument, the \fI\-attr\fP option reads names and values of user defined attributes from the named file Each entry (each line) in the attribute file must have a format as described above. The files last character must be a newline character. .IP "\fB\-chaut\fP \fIuser\fP" sets \fIuser\fP the author of a particular revision. Normally, the author of a revision is considered the user who saved that revision. However, as certain permissions are tied to the author attribute of a revision, circumstances may occur that make it necessary to change the author. .IP "\fB\-chmod\fP \fIprotection\fP" changes the access permission code of the specified version objects to the supplied three-octal-digit \fIprotection\fP. Currently, the access permissions are centered around UNIX' notions of \fIowner, group,\fP and \fIworld\fP access as well as the access categories \fIread, write,\fP and \fIexecute\fP. These permissions are inherited upon \fBsave\fP from the permissions of the file representing the \fIbusy object\fP of an AtFS history. See \fBchmod\fP(2) for details. .IP "\fB\-chown\fP \fIuser\fP" sets \fIuser\fP the owner of an entire object history. This option is not supported on BSD type systems, as only the superuser may change the owner of a file. .IP "\fB\-delattr\fP \fIattrname\fP" deletes the user defined attribute \fIattrname\fP from the set of attributes associated with the specified version objects. .IP "\fB\-d,\ \-delete\fP" removes the specified version objects from the object base, provided the objects' status is \fIsaved\fP. Any other status indicates that some kind of project interaction concerning this object might be in progress. If the programmer wants to delete such a version object anyway, he has to \fB\-unpromote\fP the respective objects status to \fIsaved\fP before it can actually be deleted. .IP "\fB\-l,\ \-lock\fP [\fIversion binding\fP]" tries to reserve the privilege to add a new version to an objects history, thus preventing multiple programmers working upon the same object base from interfering with each other by saving concurrent updates. If the locking operation succeeds, write permission is given for the corresponding files in the development directory. When setting a new lock on an object history, the requesting user is prompted for an optional description of the planned changes. .sp 0.05i In order to lock an object history successfully, the history must not be locked by any other programmer, and the programmer requesting the lock must have write permission on the AtFS subdirectory hosting the object base. .sp 0.05i As ShapeTools allows locking of single generations within a history, \fI-lock\fP optionally expects an argument denoting a generation. Default is the most recent generation. The argument may be a generation number (e.g. \fI2\fP), a version number (e.g. \fI1.4\fP), or a version alias (e.g. \fIrelease-4.7\fP). .IP "\fB\-newgen\fP" opens a new generation by duplicating the identified version. The version must be locked. Any existing busy versions are ignored by this action. If no version binding is specified, the last saved version is taken by default. .IP "\fB\-promote\fP" assigns the next-better value to the specified objects' \fIstate\fP attribute. There are six states that an object instance can be in: \fIbusy, saved, proposed, published, accessed, \fPand\fI frozen\fP. Version states are intended to relate to visibility and operational restrictions (see for example \fB\-delete\fP) within a complex project environment. .sp 0.05i Due to the current lack of project library support, the version states have very little actual functionality. Implemented to its full extent, certain state transitions may only be triggered by appropriately authorized users. The transitions \fIbusy\(->saved\fP and \fIsaved\(->proposed\fP will be triggered by regular programmers, whereas the remaining transitions have to be initiated by the \fIproject administrator\fP. .sp 0.05i Each transition corresponds to a specific action or interaction within a general software project communication scheme. As these actions/interactions will be functionally supported by the project support system currently under development, the explicit manipulation of object states will no longer be necessary (except, perhaps for manual adjusting of ill situations). .sp 0.05i The following actions relate to the state transitions: .br \fIsave\fP (\fIbusy\(->saved\fP, performed by programmer) .br \fIsbmt\fP (\fIsaved\(->proposed\fP, performed by programmer) .br \fIaccpt\fP (\fIproposed\(->published\fP, performed by project administrator) .br \fIaccs\fP (\fIpublished\(->accessed\fP, performed by any project member) .br \fIrelease\fP (\fIaccessed\(->frozen\fP, performed by project administrator) .sp 0.05i A different interface to the status control facilities of \fBvadm\fP is provided by the program aliases \fBsbmt\fP, \fBpubl\fP, \fBaccs\fP, and \fBfrze\fP. These commands correspond to conceptual project interactions like \fIsubmit\fP, \fIpublish\fP, \fIaccess\fP, and \fIfreeze\fP. .sp 0.05i \fISubmit\fP is the operation performed by a team programmer when a work result (such as a completed change request) is proposed for inclusion into the official system configuration. The associated status is \fIproposed\fP. .sp 0.05i \fIPublish\fP is an operation that is typically performed by members of the quality assurance group, when a work result, as proposed by a team programmer is approved and thus included into the current official system configuration. The associated status is \fIpublished\fP. .sp 0.05i \fIAccess\fP is an operation that is performed during configuration identification, when component versions of a (sub\-)product are incorporated into some other (partial) (sub\-)system configuration. The associated status is \fIaccessed\fP. .sp 0.05i \fIFreeze\fP is an operation that is performed during configuration identification, when a global release of the entire system configuration is established. The associated status is \fIfrozen\fP .IP "\fB\-set \fP[\fIdescription \fP| \fInote\fP | \fIintent\fP]" allows to set or modify the \fIdescriptive text\fP for an AtFS history object (i.e. an entire version history), the \fInote\fP usually describing the differences of a version object with respect to its preceding version, or an entry describing a planned change. (Re-) setting the change intention may be appropriate, if a previously set change intent has been consumed by a \fBsbmt\fP command that retained the lock on an object history. .sp 0.05i \fBvadm\fP will check the callers environment for the \fIEDITOR\fP variable and invoke the program identified therein. If the \fIEDITOR\fP variable is not set, the systems default editor will be activated. The user may write an arbitrary length descriptive or note entry using the editor. When the user leaves the editor, the resulting text is stored with the object history or the specified version objects. .IP "\fB\-setc\fI\ comment_string\fP" sets \fIcommentstring\fP as the (sequence of) character(s) that opens a comment line within the formalism of the document. This comment_string will be prepended to the lines of the log history when the \fC$__log$\fP attribute is expanded within the text of a revision. .IP "\fB\-unlock\fP" gives up the previously reserved privilege to update the history of an AtFS object and clears the write-permission for the corresponding files. \fB\-unlock\fP may be used by the \fIowner\fP of an object history to \fIbreak a lock\fP previously set by any programmer. This option is useful to resolve deadlock situations resulting from careless use of \fB\-lock\fP, or exceptional circumstances that require immediate updating of an object history, even if the lock holder is not present. The previous owner of a broken lock is notified by a mail message. Under some circumstances mail-notifications upon broken locks can be annoying (e.g. when a development tree has been moved to another system or domain with locked busy-versions; in this case the owner must break the locks to check the busy-versions back into the version archives at the new site). To avoid this effect, the switch \fB\-nomail\fP can be used to suppress mail notification. .br An eventually expressed change intention (see \fB\-lock\fP) will be cleared. .sp 0.05i Technically, the owner of an objects history is the owner of the AtFS subdirectory hosting the object base. .IP "\fB\-unpromote\fP" reverses a state transition carried out through a prior \fB\-promote\fP. The same remarks about functional embedding (and thus \fIhiding\fP the state transitions) of state transitions made for \fB\-promote\fP hold for \fB\-unpromote\fP. .SH PREDEFINED ATTRIBUTE NAMES .nf .ta 2c 7.5c 13.5c \fBName Meaning Value \h'-0.5c'Remarks\fP .sp alias version alias names list of alias names, like 1,3 ``vadm-4.2pre7'' or ``ShapeTools-1.4'' .sp 0.2c atime time of last access e.g. ``Tue Jan 14 18:47:06 1992'' 3 .sp 0.2c author user who saved a version user@do.\&ma.\&in (domain name does 1,3 usually not include the hostname) .sp 0.2c cachekey unique key for cached versions compound numeric built from 3 creation date, process id, and a serial number e.g. ``740148430.18469.6'' .sp 0.2c clead comment line leader symbol dependent on file type 1 e.g. ``# '' for Shapefiles .sp 0.2c ctime time of last status change as \fIatime\fP .sp 0.2c Description descriptive text for module multi line text 2 .sp 0.2c dsize size of delta to previous numeric version in bytes .sp 0.2c generation major revision number numeric 1,3 .sp 0.2c Header RCS-style version header text .sp 0.2c Intent change intent multi line text 2 .sp 0.2c host name of current host e.g. ``avalanche'' 3 .sp 0.2c Log cumulative descriptive entries multi line text of all versions from the first up to this one .sp 0.2c lock/locker user who locks a history as \fIauthor\fP 3 .sp 0.2c ltime time of last lock transaction as \fIatime\fP 3 .sp 0.2c mode access pprotection e.g. ``\-rw\-r\-\-r\-\-'' 1 .sp 0.2c mtime time of last modification as \fIatime\fP 3 .sp 0.2c name name part of an object identifier e.g. ``foo'' for ``foo.c'' 3 .sp 0.2c note short note describing the multi line text 1, 2 changes in this version .sp 0.2c owner user who owns the repository in as \fIauthor\fP 1,3 which this version is archived .sp 0.2c pred bound version identifier of e.g. ``foo.c[3.22]'' or ``n/a'' preceding version .sp 0.2c revision minor revision number numeric 1,3 .sp 0.2c rtime last time when history was locked as \fIatime\fP .sp 0.2c self bound version identifier for e.g. ``foo.c[3.23]'' this version .sp 0.2c selfpath bound version identifier for e.g. ``/usr/proj/sample/foo.c[3.23]'' this version including path .sp 0.2c size size of the version in bytes numeric 3 .sp 0.2c state/status version status symbolic integers (busy, 1,3 saved, proposed, published, accessed, and frozen) .sp 0.2c stime time when the version was saved as \fIatime\fP 3 .sp 0.2c succ bound version identifier of as \fIpred\fP successive version .sp 0.2c syspath pathname part of an object e.g. ``/usr/proj/sample'' 3 identifier for ``/usr/proj/sample/foo.c'' .sp 0.2c type suffix part of an object e.g. ``c'' for ``foo.c'' 3 identifier .sp 0.2c unixname UNIX file name of this version e.g. ``foo.c'' .sp 0.2c unixpath UNIX file name of this version e.g. ``/usr/proj/sample/foo.c'' including path .sp 0.2c version compound version number e.g. ``3.22'' 1,3 consisting of generation and revision number .sp 0.2c vtime version time, modification time as \fIatime\fP for busy versions od save time for saved/cached versions .sp 0.2c xpoff pseudo attribute that turns none off subsequent attribute expansions .sp 0.2c xpon pseudo attribute that turns none subsequent attribute expansion on .sp 1 \- may be modified by \fIvadm -attr name=value\fP. 2 \- may be modified by \fIvadm -set \fP. 3 \- recognized by \fIattr*\fP predicates in version bind rules (see bindrules(7)). .fi .SH ENVIRONMENT EDITOR .SH SEE ALSO save(1), retrv(1), vl(1), vbind(1) .SH AUTHORS Uli.Pralle@cs.tu-berlin.de, Axel.Mahler@cs.tu-berlin.de, Andreas.Lampen@cs.tu-berlin.de