vbind(1)

📦 version 1.4pl6, in debian bookworm, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

🎀 vbind 💅 — it's the vbind(1) page from ShapeTools, bestie 🦋

okay so. welcome to the manual page for vbind, which lives in the ShapeTools toolkit (yes, the whole vbind(1) family). this is part 1, so grab a snack 🍓, we're going in.

✨ NAME ✨

vbind — bind name to version. that's it, that's the whole job, and she does it flawlessly 👑

🌸 SYNOPSIS 🌸

vbind [ options ] filenames ..

General version binding options:

     [ -bind version binding ] [ -before baseline ] [ -since baseline ]
     [ -last ] [ -lastsaved ] [ -uniq ] [ -nonuniq ]
     [ -rule rulebody | rulename ] [ -rulefile filename ] [ -trace ]

vbind command specific options:

     [ -? (or -help) ] [ -alias version alias ] [ -date date ]
     [ -vnum version number ] [ -nomsg ] [ -ruledump ] [ -ruleerr ]
     [ -rulelist ] [ -ruletest ] [ -version ]

👑 OVERVIEW 👑

so this manual page is the ✨official✨ description of the ShapeTools Version Binding mechanism, which shows up in most commands of the toolkit. the general version binding options described down below are available in loads of commands like vl(1), vcat(1), vadm(1), save(1) and retrv(1) — just naming the most important ones, iykyk. the vbind command specific options are private to the vbind command itself (peep below 👇).

Version binding is literally the process of selecting one or more versions out of a filename's history so you can actually get access to that version (or those versions). it's carried out by version bind directives (or just version bindings, same vibe), and a version binding can be any one of these:

  • version numbers — "1.2" (version), "1." (generation), ".2" (revision)
  • version alias names — "ShapeTools-1.4", or "AtFS-2.0". version alias names are symbolic names tagged to single versions. they must be unique throughout a history, no cap.
  • date specifications — "10.2.93" or "4.3." (European), "Feb 10, 1993" or "Mar 4{ (American). a date may additionally contain a time in the form hh:mm or hh:mm:ss. see sttime(3) for a complete list of recognized date formats.
  • bind rule names — "most_recent:" (plain), "from_release(VC-4.0):" (with argument). the colon is not part of the rule name. see the bindrules(7) manual page for a description on how to define version bind rules.

by default, version binding selects all versions fulfilling the given version bind requirements. the -uniq option changes this behavior and treats only unique identification as success. with this option given, version bind ignores all histories with more than one selected version. the -last and -lastsaved options unify a non unique selection by choosing the last version (modification/saving time) or the last saved version (saving time) from the bind hit set of each name.

the file $SHAPETOOLS/lib/shape/BindRules contains predefined rules for various cases. you may also define your own rule file and invoke this by either the -rulefile option or by extending the search space defined by the SHAPETOOLS environment variable. for information on how to write version bind rules, see the bindrules(7) manual page. 💜

🦋 VERSION BINDING IN ACTION 🦋

version bind directives can be given either in brackets, directly following the name to be bound, or as option arguments. options may be user to set version bindings to be applied to all name arguments (-bind and -rule options) or to define version ranges (-since and -before options).

version identification by version number or version alias either results in a unique selection or fails, when no appropriate version was found. 😭

foo[1.2]        Identifies a specific version by it's version number.

foo[release-2]  Is interpreted as identification by version alias name.

version identification by date selects the versions from a history that have been the most recently saved versions at the given date. identification by date may lead to multiple versions when development work in multiple generations happened simultaneously at the given date. vbind understands various date formats such as in the list below. the sttime(3) manual page lists all recognized date formats.

foo[Jan 31, 1992]

foo[92/01/31]

foo[10.5.92 7:00:00]

version bind rules describe general version binding policies. they are usually not dependent on particular file histories and may be applied to all histories. version bind rules may have arguments enclosed in parentheses following the name.

foo[bind_rule:]

foo[bind_rule(arg1,arg2,...argN):]

when the colon at the end of the rule name in brackets is omitted, vbind first interprets the given string as version alias. when no version with this alias name was found, vbind treats the string as rule name and gives it a second try. slay, persistence 💅

Plain filenames are those not followed by any version bind directive in square brackets. without a rule given with the -rule option on the command line, plain filenames are bound using the default version bind rule. it selects the busy version if there is one, or the most recent non busy version otherwise.

eq (state, busy); max (version).

the default version binding may also be indicated by an empty pair of brackets: foo[]

🌈 NAME PATTERNS 🌈

the ShapeTools version binding mechanism performs filename substitution for given name patterns similar to sh(1). this is necessary, as shell filename substitution does not recognize the names of saved versions. the magic cookies are:

  • * — matching any string, including the empty string,
  • ? — matching any single character,
  • [c...] — matching any one of the characters enclosed in the square brackets,
  • [l-r] — matching any character lexically between the left (l) and the right (r) character, inclusive, and
  • [!c...]
  • [!l-r] — matching any character not recognized by their counterparts above.

as square brackets on the command line may either be part of a pattern (e.g. *.[ch]) or a version binding (e.g. *[release-2]), this may lead to some confusion. 🙈 the leftmost pair of brackets is always interpreted as version binding. hence, in the first case, the string will be misinterpreted and you must add an explicit version binding to avoid this (e.g. *.[ch][], default version binding added).

lowkey the most important thing on this whole page: leftmost brackets = version binding. always. periodt. 👑

💖 GENERAL VERSION BINDING OPTIONS 💖

  • -before baseline — define the lower boundary of a time interval for selecting all versions evolved in this interval. baseline can be any version bind directive uniquely selecting a version (e.g. version number, version alias, or date). the saving date of the baseline version is the interval start time. the boundary version (exactly matching the time given) is not included in the result set.
  • -bind version binding — use version binding for binding each name on the command line that has no explicit version binding in brackets.
  • -last — select the last (modification/saving time) version of each nonunique selection. this causes the resulting version list to contain at most one version of each history. -last may be combined with other version bindings.
  • -lastsaved — like -last, but busy versions are ignored. ✨
  • -nonuniq — force non-unique version identification. this option can be used to swich off the default behavior of some commands (e.g. vadm) that suggests unique version identification.
  • -rule rulename | rulebody — with a name argument, this option sets the named rule as default rule for binding all names on the command line. alternatively, a rule body (a version selection rule without a name) may be given as argument, which will be evaluated for each name on the command line. this option disables any previous -bind or -rule definition. it does not affect names with a version binding in brackets.
  • -rulefile filename — read in the named rule file and add all contained rules to the list of known rules. a syntactical error, detected while parsing a rule, causes the according rule to be skipped. use vbind(1) with the -ruleerr option for inspecting bind rule files. multiple rule files may be specified on the command line.
  • -since baseline — define the upper boundary of a time interval for selecting all versions evolved in this interval. baseline can be any version bind directive uniquely selecting a version (e.g. version number, version alias, or date. the saving date of the baseline version is the interval end time. the boundary version (exactly matching the time given) is not included in the result set.
  • -trace — trace the evaluation. each evaluated predicate is reported to standard output. additionally, the set of versions fulfilling the expressed (the hits set) is displayed after evaluation of each predicate.
  • -uniq — require unique version identification. all history names on the command line, where multiple versions meet the version bind requirements, are ignored.

okay so that's the general stuff 🫶 — the vbind command's own private options are coming up in the next part, so don't go anywhere 💜

🎀 THE VBIND COMMAND 🎀

Okay bestie, so here's the whole deal with the command itself: vbind does a version binding, and it hands you back a bound filename for every version it selects. And what's a bound filename, you ask? It's just a filename with a version number chilling in brackets right after it — like foo[1.2]. That's it, that's the whole aesthetic 💅

✨ OPTIONS ✨

  • -?, -help — shows you a short lil usage description so you know what you're doing. 🫶
  • -alias version alias — uses version alias to bind all the names on the command line. Heads up though: this disables any previous -alias, -bind, -date, -rule or -vnum definition you had going. It does not touch names that are in pseudo bound version notation, okay? 👑
  • -date date — uses date to bind all the names showing up on the command line. Same energy as above: this disables any previous -alias, -bind, date, -rule or -vnum definition. And again, it does not affect names in pseudo bound version notation. (yes, the original really writes that list as -alias, -bind, date, -rule or -vnum — one of them is missing its dash and I am simply reporting the lore, no cap 💀)
  • -nomsg — Suppress output produced by version bind rules. 🌸 (in the source this one gets printed all mushed together with no space, looking like -nomsgSuppress — iconic typo behavior fr fr, but that's literally how it appears, so there you go)
  • -ruledump — makes all the known version bind rules get written out to standard output. The generated output contains every rule definition in regular format, which means you can absolutely use it as an input rulefile for later calls of vbind. Recycling era ♻️✨
  • -ruleerr — this one's for when you're testing a new, hand written file full of bind rules. It makes syntax errors detected in the rule file get reported to standard error. ⚠️ And listen: make sure this option shows up on the command line prior to the rulefile you want inspected. Order matters, bestie, don't play yourself.
  • -rulelist — writes a list of all known rule names to standard output. Simple, clean, slay. 📝
  • -ruletest — interprets all the names on the command line as rule names, and then tests whether equally named rules exist in the list of known rules. Like a vibe check for your rules. 🔍
  • -version — prints the version identification of the vbind command and the libraries it used. 🏷️
  • -vnum version number — uses version number to bind all the names on the command line. And yup, you guessed it: this disables any previous -alias, -bind, -date, -rule or -vnum definition. It does not affect names in pseudo bound version notation. 💜

🌈 ENVIRONMENT 🌈

  • SHAPETOOLS — a list of path names that acts as the search space for files containing version bind rules. Those bind rule files must be named BindRules. The default path is /usr/local/lib/shape. 🦋

🍓 FILES 🍓

$SHAPETOOLS/lib/shape/BindRules

👀 SEE ALSO 👀

vl(1), sttime(3), bindrules(7)

💖 AUTHOR 💖

Andreas.Lampen@cs.tu-berlin.de

and that's the whole page, bestie!! 💖✨ this was AtFStk-1.12, dated Thu Mar 10 12:15:43 1994, which is lowkey ancient but highkey iconic — go forth and bind those versions, you absolute main character 👑🎀🦋

📦 where this page comes from