vadm(1)

💖 vadm(1) · ShapeTools 💖

✨ NAME ✨

vadm - manipulate and administer version object base 🎀

✨ SYNOPSIS ✨

vadm [ version binding options ] [ options ] [ action ] name..

Options: [ -?fq ] [ -cache ] [ -force ] [ -help ] [ -nomail ] [ -quiet ]
         [ -stdin ] [ -version ]

Actions: [ -alias version alias name ] [ -attr attribute ]
         [ -chaut user ] [ -chmod protection ] [ -chown user ]
         [ -delattr attribute name ] [ -d (or -delete) ]
         [ -l (or -lock) [version binding] ] [ -newgen ] [ -promote ]
         [ -set description | note | intent ] [ -setc comment leader ]
         [ -unlock [version binding] ] [ -unpromote ]

vattr [ version binding options ] attribute name..

vrm [ version binding options ]  name..

sbmt [ version binding options ] name..

publ [ version binding options ] name..

accs [ version binding options ] name..

frze [ version binding options ] name..

✨ DESCRIPTION ✨

Okay bestie, vadm is a general purpose command that handles basically ALL the admin stuff for parts of an AtFS object repository 💅 Need to lock or unlock an AtFS object so it can be modified? 🔒 vadm has you. Want to delete one particular object instance? 🗑️ vadm. It also does symbolic (alias) names for version objects 🏷️, promoting or unpromoting certain version objects from one status to another 🚀, changing an object's access permissions 🔑, setting or editing the descriptive entry of particular version objects 📝, setting or editing an eventual change intention 💭, and setting or unsetting object attributes like the author or any user defined attributes 🎀. Main character energy, no cap.

vattr and vrm are short forms for vadm -attr and vadm -delete. Check the descriptions of the -attr and -delete options for the deets 🦋.

sbmt, publ, accs, and frze are alternate program names for vadm that handle status-change operations for version objects. See the description of option -promote for details 💜.

The typical command invocation is made up of one or more command options, version binding options that define the versions to act upon, an action specifier that says what kind of action to perform, and a set of object names that define the starting subset of the object base you're going to manipulate 🧚.

Object names can be written in bound version notation, which identifies one particular version of an object, like mkattr.c[2.4] 🌸. You can also use a previously assigned symbolic name instead of a numerical version identification, like mkattr.c[tools-V4R3] ✨.

🙈 Bestie, make sure to escape the bracket symbols when using csh(1) or tcsh(1), because those shells have their own meaning for brackets.

✨ OPTIONS ✨

For version selection, you can give any version binding option described on the vbind(1) manual page, or add a version bind directive in brackets to the file name 🎯.

• -?, -help — pulls up brief instructions on using vadm 📖
• -cache — applies the requested operation to objects living in the derived object cache 🗄️. The set of actions you can perform on binary pool objects is limited, so don't expect miracles 🙈
• -f, -force — don't ask for confirmation when deleting versions from a history 😤
• -nomail — suppresses the notification mail to the user holding the lock on a history when you break that lock (the -unlock option) 📭
• -q, -quiet — shhh 🤫 suppresses any prompts, informal messages, and user dialogues. Default values get assumed for everything that would otherwise be asked interactively. Super useful for batch operation 🤖
• -stdin — forces vadm to read a descriptive text, note, or intent from standard input when the -set action is selected. The note is used for all specified AtFS objects. Otherwise, your favorite editor (taken from the EDITOR environment variable) pops up 🖊️
• -version — prints version information about the vadm program itself. No action gets performed on the database, so it's just a peek 👀

vadm performs all of its operations upon a specified set of AtFS version objects. If no such set is specified, the operation is applied to the most recently saved versions of the named object(s) 💖.

✨ ACTIONS ✨

The kind of action you want is indicated by a keyword. The following actions are defined 🎀:

• -alias version alias name — assigns the alias alias name 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. You can give the same symbolic name to version objects in different object histories, though. An object history is usually denoted by a name, similar to a file's name. Using alias names is a simple but effective way to tie together component members of a system configuration. Typical symbolic names look something like Mysystem_Release_4.22, which tells you that version objects with this name are part of release 4.22 of that system 🧁
• -attr attrname — returns the value of the named attribute 🔍. This can be a standard attribute or a user defined attribute. Check the list below for a complete list of standard attribute names 📋
• -attr attrname[+|-]=[@|^|!|*]value — defines a user defined attribute called attrname and sets it to value for all specified version objects ✨. This can also set the value of certain standard attributes (see the list below) 💅
  • A single equal sign (=) sets, or resets, the value of the object to the specified value. Any previous values get overwritten 🔄
  • +=, the "plus-equal", appends the specified attribute value to the current value of the referenced attribute ➕
  • -=, the "minus-equal", should remove the specified value from the given attribute. In the current implementation, removal of single values is not supported 🙅
  • There are four basic kinds of user defined attribute values: genuine values, reference values, execution values, and pointer values. The kind is determined when the value gets set 🧠
    • If the first character of value is an at sign (@), the rest of value is the name of a file, and that file's contents become the attribute's value. This substitution happens immediately, so the attribute ends up with a genuine value 📄. If the filename is -, the value gets read from standard input ⌨️
    • If the first character is a circumflex (^), the rest of value is a file name whose contents get substituted for the attribute when it's cited 📎
    • If the first character of value is an exclamation mark (!), the rest is the name of a program whose standard output gets substituted for the attribute when it's cited 🪄. Execution values can make highly dynamic attributes, or even a primitive form of event triggers ⚡
    • An asterisk (*) as the first character means a pointer to another version. In that case the remainder of value must be a valid bound filename 🔗
  • User defined attributes can be any length. Any sequence of ASCII characters is allowed to make up an attribute value, except \01 (control-A) 🚫. If attrname was already set to some value, the previous value gets replaced by the newly specified one 🫶
• -attr @attrfile — with a @filename argument, the -attr option reads the names and values of user defined attributes from the named file 📂. Each entry (each line) in the attribute file must have the format described above. The file's last character must be a newline character 📝
• -chaut user — sets user as the author of a particular revision 🖊️. Normally the author of a revision is whoever saved that revision. But certain permissions are tied to the author attribute, so sometimes you need to change it 🔐
• -chmod protection — changes the access permission code of the specified version objects to the supplied three-octal-digit protection 🔑. Permissions are centered around UNIX' notions of owner, group, and world access, plus the access categories read, write, and execute. These permissions are inherited upon save from the permissions of the file representing the busy object of an AtFS history. See chmod(2) for details 📚
• -chown user — sets user as 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 🙈
• -delattr attrname — deletes the user defined attribute attrname from the set of attributes associated with the specified version objects 🗑️
• -d, -delete — removes the specified version objects from the object base, provided the objects' status is saved 💀. 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, they have to -unpromote that object's status to saved before it can actually be deleted 🧹

👀 Bestie, only saved versions can be deleted. Any other status means something might be going on with the project, so double-check before you go for it.

• -l, -lock [version binding]: okay so this one tries to reserve the privilege to add a new version to an object's history 🔒 That way, programmers working on the same object base can't clobber each other's saves with concurrent updates 💅 If the lock works, you get write permission on the matching files in the development directory ✨ When you set a new lock, vadm asks for an optional description of your planned changes 🎀
  • To lock an object history successfully, no other programmer can have it locked, and you need write permission on the AtFS subdirectory hosting the object base 🙈
  • ShapeTools lets you lock single generations inside a history, so -lock optionally takes an argument naming a generation. The default is the most recent generation. The argument can be a generation number (e.g. 2), a version number (e.g. 1.4), or a version alias (e.g. release-4.7) 🌈
• -newgen: main character energy 🌸 This opens a new generation by duplicating the version you point at. The version has to be locked first. Any existing busy versions get ignored by this action 🙅‍♀️ If you don't specify a version binding, the last saved version is taken by default 💜
• -promote: this one bumps the state attribute of the specified objects up to the next-better value 🦋 An object instance can be in one of six states: busy, saved, proposed, published, accessed, or frozen. Version states are meant to tie into visibility and operational restrictions (see for example -delete) inside a complex project environment 👑
  • Ngl, the version states don't do much yet 💀 Project library support isn't really there, so they have very little actual functionality. Once fully implemented, certain transitions could only be triggered by appropriately authorized users. The busy→saved and saved→proposed transitions would be triggered by regular programmers, and the rest would have to be initiated by the project administrator 👑
  • Each transition matches a specific action or interaction in a general software project communication scheme. The project support system under development is going to functionally support these actions, so manually manipulating object states won't be necessary anymore (except, perhaps, for manual adjusting of ill situations) 🩹
  • The state transitions line up with these actions:

save (busy→saved, performed by programmer)
sbmt (saved→proposed, performed by programmer)
accpt (proposed→published, performed by project administrator)
accs (published→accessed, performed by any project member)
release (accessed→frozen, performed by project administrator)

• vadm has a different interface to the status control facilities, through the program aliases sbmt, publ, accs, and frze. These match the conceptual project interactions submit, publish, access, and freeze 🎀
  • sbmt (submit): a team programmer does this when a work result, like a completed change request, gets proposed for inclusion in the official system configuration. The status becomes proposed ✨
  • publ (publish): usually done by members of the quality assurance group when a work result proposed by a team programmer gets approved and included in the current official system configuration. The status becomes published 🧚
  • accs (access): happens during configuration identification, when component versions of a (sub-)product get incorporated into some other (partial) (sub-)system configuration. The status becomes accessed 🦋
  • frze (freeze): also happens during configuration identification, when a global release of the entire system configuration gets established. The status becomes frozen 🧊

• -set [description | note | intent]: lets you set or modify the descriptive text for an AtFS history object (the entire version history) ✍️ The note usually describes how a version object differs from its preceding version, or it's an entry describing a planned change 💭 Re-setting the change intention can be appropriate if a previously set change intent got consumed by a sbmt command that kept the lock on the object history 🔁
  • vadm checks your environment for the EDITOR variable and invokes whatever program it names. If EDITOR isn't set, the system's default editor gets activated instead 📝
  • You can write an arbitrary-length descriptive or note entry in the editor. When you leave the editor, the resulting text gets stored with the object history or the specified version objects 💖
• -setc comment_string: sets comment_string as the character or sequence of characters that opens a comment line within the formalism of the document 🌈 That comment_string gets prepended to the lines of the log history whenever the $__log$ attribute is expanded within the text of a revision 🫶
• -unlock: this gives up the privilege you reserved to update an object's history and clears the write permission on the corresponding files 🔓 The owner of an object history can use -unlock to break a lock set by any programmer. It's super useful for resolving deadlock situations caused by careless use of -lock, or for exceptional circumstances that need an immediate update to the object history even when the lock holder isn't around 🚨 The previous owner of a broken lock gets notified by a mail message 📬
  • Mail notifications can get annoying 🙄 For example, if a development tree gets moved to another system or domain with locked busy-versions, the owner has to break the locks to check the busy-versions back into the version archives at the new site.
  • To avoid this, the switch -nomail can be used to suppress mail notification 🤫
  • Any change intention expressed earlier (see -lock) will be cleared ✨
  • Technically, the owner of an object history is the owner of the AtFS subdirectory hosting the object base 👑
• -unpromote: reverses a state transition carried out through a prior -promote 🔄 The same remarks about functional embedding (and thus hiding the state transitions) that hold for -promote hold for -unpromote too 🫶

✨ PREDEFINED ATTRIBUTE NAMES ✨

Okay so here's the squad of built-in attributes vadm already knows about 🧚 Each one has a name, a meaning, and the kind of value it takes. Those little footnote numbers are lowkey important, so don't skip the legend at the bottom 💖

• alias — version alias names 🎀. Value: list of alias names, like "vadm-4.2pre7" or "ShapeTools-1.4". Footnotes 1, 3.
• atime — time of last access 👀. Value: e.g. "Tue Jan 14 18:47:06 1992". Footnote 3.
• author — user who saved a version ✍️. Value: user@do.ma.in (the domain name usually doesn't include the hostname). Footnotes 1, 3.
• cachekey — unique key for cached versions 🔑. Value: a compound numeric built from creation date, process id, and a serial number, e.g. 740148430.18469.6. Footnote 3.
• clead — comment line leader symbol 💬. Value: depends on file type, e.g. "# " for Shapefiles. Footnote 1.
• ctime — time of last status change 🕰️. Value: as atime.
• Description — descriptive text for module 📝. Value: multi line text. Footnote 2.
• dsize — size of the delta to the previous version, in bytes 📏. Value: numeric.
• generation — major revision number 🌱. Value: numeric. Footnotes 1, 3.
• Header — RCS-style version header 🧾. Value: text.
• Intent — change intent 🎯. Value: multi line text. Footnote 2.
• host — name of current host 🖥️. Value: e.g. "avalanche". Footnote 3.
• Log — cumulative descriptive entries of all versions, from the first up to this one 📚. Value: multi line text.
• lock/locker — user who locks a history 🔒. Value: as author. Footnote 3.
• ltime — time of last lock transaction ⏰. Value: as atime. Footnote 3.
• mode — access protection 🛡️. Value: e.g. -rw-r--r--. Footnote 1.
• mtime — time of last modification ✏️. Value: as atime. Footnote 3.
• name — name part of an object identifier 🏷️. Value: e.g. "foo" for "foo.c". Footnote 3.
• note — short note describing the changes in this version 🗒️. Value: multi line text. Footnotes 1, 2.
• owner — user who owns the repository this version is archived in 👑. Value: as author. Footnotes 1, 3.
• pred — bound version identifier of the preceding version ⬅️. Value: e.g. "foo.c[3.22]" or "n/a".
• revision — minor revision number 🌿. Value: numeric. Footnotes 1, 3.
• rtime — last time the history was locked 🔐. Value: as atime.
• self — bound version identifier for this version 🪞. Value: e.g. "foo.c[3.23]".
• selfpath — bound version identifier for this version, including path 🗺️. Value: e.g. "/usr/proj/sample/foo.c[3.23]".
• size — size of the version in bytes 📦. Value: numeric. Footnote 3.
• state/status — version status 🚦. Value: symbolic integers (busy, saved, proposed, published, accessed, and frozen). Footnotes 1, 3.
• stime — time when the version was saved 💾. Value: as atime. Footnote 3.
• succ — bound version identifier of the successive version ➡️. Value: as pred.
• syspath — pathname part of an object identifier 📂. Value: e.g. "/usr/proj/sample" for "/usr/proj/sample/foo.c". Footnote 3.
• type — suffix part of an object identifier 🧩. Value: e.g. "c" for "foo.c". Footnote 3.
• unixname — UNIX file name of this version 📄. Value: e.g. "foo.c".
• unixpath — UNIX file name of this version, including path 🛤️. Value: e.g. "/usr/proj/sample/foo.c".
• version — compound version number made of the generation and revision numbers 🔢. Value: e.g. "3.22". Footnotes 1, 3.
• vtime — version time: modification time for busy versions, or save time for saved/cached versions ⌛. Value: as atime.
• xpoff — pseudo attribute that turns off subsequent attribute expansions 🙅. Value: none.
• xpon — pseudo attribute that turns subsequent attribute expansion on 🙆. Value: none.

🔖 Footnotes

• 1 — may be modified by vadm -attr name=value.
• 2 — may be modified by vadm -set <type>.
• 3 — recognized by attr* predicates in version bind rules (see bindrules(7)).

---

🌸 ENVIRONMENT 🌸

• EDITOR — the only environment variable listed here. The page doesn't say anything more about it, so that's all the tea ☕

🦋 SEE ALSO 🦋

save(1), retrv(1), vl(1), vbind(1) — the sibling pages, iykyk 💜

👑 AUTHORS 👑

Uli.Pralle@cs.tu-berlin.de, Axel.Mahler@cs.tu-berlin.de, Andreas.Lampen@cs.tu-berlin.de — the squad who made this 🫶

---

And that's the whole page, bestie! 🌈 We covered vadm 4.10, last updated Friday, July 9, 1993. Go forth and attribute responsibly, you absolute legend 💅✨