vd - command line interface to Verdad
vd [opt] [command] [command-options]
[opt] is:
-v version
-h help
-m message
[command] is one of:
ci co edit find print rename delete undelete
unlock expand history findtags locks recent
txn
[command-options] depends on the command
Verdad is a system for managing data. It has features that make it well suited to managing operational data, like the configuration of the components of a large service.
The vd script is a command line interface to Verdad. It's principle purpose is to let users quickly and easily interact with Verdad items in a text (as opposed to web browser) environment. It can be used to bulk-load a large group of items, or to extract a bunch of items which will be edited with a text-based tool like sed or perl.
For most small changes, Verdad's web interface will probably be more useful.
The command line interface for Verdad has a few other features for administrative use, including the rename, delete, undelete and unlock functions.
Options that are generally useful to all commands go before the command, and are called "common options". These include:
Provides a usage message.
Allows you to specify the message to be used with checkin, rename, delete, or undelete operations, to avoid going into the interactive editor. This is useful for terminally lazy people, or for scripts that want to make checkins without dealing with having an editor spawned for them.
The edit command is actually a synonym for the co command. Use it when you want checkout, edit, and checkin some items in single step.
As it is a synonym, it takes precisely the same filtering arguments as the co command, below.
The co command lets you bring some items out of the Verdad database into a text file for viewing or editing.
You can pass one or more regular expressions on the command line. For more info about the regular expression syntax supported, see http://www.mysql.com/doc/R/e/Regexp.html
If you use the -exact option, the regular expression capability is turned off and you need to specify full item names.
Alternatively, you can specify the items by a tag search. Put one or more -tag options on the commandline, and any item which matches all of the tag=value filters will be selected. The empty tag matches all tags, so "-tag =192.168" will match any item in the database which has the string 192.168 in any tag. The value part of the tag=value option is interpreted as a regular expression.
You can also use -is to filter based on inheritance. The argument to the -is filter must be an existing item name.
You can use any of the three filtering methods, or combine them. The result is the intersection of all the items selected by the filters.
This option prints the items only. It does not lock them in your name. Use this when you only want to look at some items, or check them out as a template. Unless you set the filename explicitly, this option sets it to standard output.
A shortcut for vd co -p is vd print.
This option is like -print, but it only prints the item name, not the entire item. It is designed to be used in scripts which need to find a certain set of items and take action on them.
A shortcut for vd co -find is vd find.
This option is like -print, but it prefixes the tags and values in the item with change information. This includes the revision, user, and date of each change.
This optional argument lets you specify the filename where the items will be sent. If you use "-", they will go to standard output. If you do not use this argument, vd will choose a filename for you.
A filter. See above for description of filtering.
A filter. See above for description of filtering.
The -rev option will display a certain revision of the item. If used, it forces the -print option on, and turns off the -tag, -is and -find options.
Revision numbers can be seen via the history command.
Negative revision numbers count backwards...so, -1 will be the previous revision, -2 two revisions back, etc.
The -yml option will display output as YML. If used, it forces the -print option on.
The -deleted option allows you to search through deleted items.
The -u flag is for programmatically editing the selected items. The syntax for editexpr is documented below.
When used with one or more -u flags, causes vd to not exec your $EDITOR to edit the resulting item. Useful when driving vd from a script.
The syntax for the editexpr given to the -u flag is a bit baroque. For full documentation, see the code. Here's a quick-reference:
(also: tag X=val, tag ~= val, tag x= val, tag := val) Set 'tag' == 'val'. If tag already exists, value is replaced. In the case where a policy is specified, (X=, x=, :=, ~=), the policy for 'tag' is changed. Note that for 'X=' and 'x=', there must be a space after the tagname or the 'x' will be part of the tag.
=item I<tag>[I<n>]=I<val> ('=' can also be policy: X=,x=,:=,~=)
Set array item 'n' to val. If array item 'n' doesn't exist, an error is raised. If 'n' is not given (i.e.: tag[]=val), then 'val' is appended to 'tag' as a new array element. If 'n' begins with a '+', then the value is inserted before item 'n'.
=item -I<tag> or -?I<tag> or -I<tag>[I<n>] or -?I<tag>[I<n>]
Remove 'tag' from item. If the value of the tag is array, all values are removed. If the '?' is present, then no error is raised if the tag doesn't exist.
Remove tag from item if value == val. If 'tag' has more than one array element, remove element matching 'val' from array item 'tag'. If the '?' is present, then no error is raised if the tag doesn't exist.
The ci command parses one or more files looking for items, then inserts the items into the database.
For more information on the file format used by Verdad, see the "Item Format" document that comes with it, and should be available from the web interface.
Use this to rename an item. The old item will be deleted and a new item with the same contents will be created. The comment you give Verdad will be used for both the deletion and for the new item.
The old item name must be an exact match for an item in the database.
Delete lets you mark an item as deleted.
The item-name parameters on the command line after the delete command must be exact matches for items in the database.
If -file is used, delete all item-names listed in file.
Undelete marks an item as no longer deleted. However, because it is currently a hack-job, it does not recover the contents of the item from their state at the time it was deleted.
The item-name parameters on the command line after the delete command must be exact matches for items in the database.
Locks displays the a list of locked items, along with the user who locked the item and the date stamp of the lock.
You can display all items locked by a particular user using the -u user option.
The item-name parameters are regular expression matches for items in the database.
The -u and "item-name ..." methods of selecting items to display locks are mutually-exclusive. If you use -u, all other arguments will be ignored.
Unlock allows you to mark an item as unlocked. This can be useful when a coworker has left an item locked. It can be harmful if they are in fact still working on the items, and plan to checkin their changed versions on top of yours. Word to the wise: coordinate with the locker before using the unlock function.
You can unlock all items locked by a particular user using the -u user option. If you only use -u, vd unlocks all of your locked items.
As with delete, the item-name parameters must be exact matches for items in the database.
The -u and "item-name ..." methods of selecting items to unlock are mutually-exclusive. If you use -u, all other arguments will be ignored.
A shortcut for "vd co -print".
A shortcut for "vd co -find".
A shortcut for "vd co -annotate".
Add in tags as specified by the current setting of schema-check
and its implementation of itemExpand(). Show the resulting
item on stdout.
If you use the -exact option, the regular expression capability is turned off and you need to specify full tag names.
If you use the -i option, the inheritance information is displayed as well.
For each item, it generates a report showing who touched that item, when, and why.
If you use the -exact option, the regular expression capability is turned off and you need to specify full tag names.
The -deleted option allows you to search through deleted items.
For each tag regular expression, it prints out the item and tags that match (with values).
If you use the -exact option, the regular expression capability is turned off and you need to specify full tag names.
Prints the list of recent changes to stdout. The -user option limits changes to a particular user, the -num option limits the number of changes displayed, and the -header option removes the header line.
Prints the details of each transaction number provided.
For each item regular expression, the differences between revisions are printed. You must provide one or two -rev/-x options. If just one is used, the differences are based on the latest revision.
If you use the -exact option, the regular expression capability is turned off and you need to specify full item names.
Please be sure to read the rest of the online documentation to find out what kind of data Verdad can handle, and how to get the most out of the inheritance feature.
Jeff R. Allen <jra@nella.org>
Updates by Bryan Stansell <bryan@tellme.com>