Use your favorite editor to create a file to hold the new
item. If you want, use verdad print item-name to dump an
existing item like the one you want to add to use as a template.
When you have the item ready to check in, save the file and
exit your editor. Use verdad ci filename to check in the
item in the file.
You can put more than one item into a file. Just separate each with a newline (for readability).
As files get bigger, the amount of time Verdad spends parsing them gets much bigger. (This is a known problem.) The workaround is to put items into separate files. This is really only an issue for input files over 200 lines long. For ten items or so, don't worry about it.
For more detailed information on the item format, see the document named ``Item Format''.
Do this:
verdad edit item-substring [ item-substring... ]
Your editor of choice (based on the EDITOR environment variable) will start up with the item in it. Make your edits and exit the editor. Then your editor will start again with a place to put comments. When you save and exit the comments, you're done.
If you decide you don't want to edit it after all, exit with no
changes. Exit the comment editor with no changes too, and Verdad
will say ``Empty message file. edit aborted.'' There is a bug
right now that leaves the item(s) locked, so run this
to unlock all items you have locked:
verdad unlock -u $LOGNAME
If you want to use a program to edit the items (for instance, because you need to do some automated edit) you can check out the items into a file, then edit that. Do this:
verdad co item-substring [item-substring...]
You will get a file in the current working directory with the matching items in it. Edit that file using your favorite text editor, or sed, or Perl, or awk, or whatever.
When you have made your changes, check the items in the file back into Verdad using:
verdad ci filename
If you just want to dump it out so you can see it in text form, do this:
verdad print item-substring [item-substring...]
You can put one or more substrings, and all matching items will be printed.
Items that are locked are being edited by the user that locked them. If you unlock the item, when they check in their changes, they might stomp your changes.
You still want to unlock the item and risk having your changes stomped? OK, but don't say we didn't warn you.
You can unlock items using the ``unlock'' option of the verdad command line tool. See the man page for it for more info.
The Verdad item format does not support a comment character, since the comment would be immediately lost when the item was parsed and saved in the database. Instead, you can include one or more comments inside the item using a tag named ``comment''.
When Verdad displays an item in a web browser, it puts all the comment fields, separated by spaces, up on top of the item. Using simple HTML constructs like the B and I tag in the comment is perfectly fine. It would be best to stay away from tables and the like.
When interacting with Verdad via the command-line tool, the comments are visible as just another one of the tags. You can edit them just like you'd edit any other tag.
When you use the normal ``verdad co item-names...'' and ``verdad ci filename'' syntax, Verdad takes care of locking for you. You don't get any items that other people hold locks on, and you are granted locks on the items you get from the checkout command.
If you checkout some items, then want to unlock them without checking in any changes, use the ``unlock'' command to do so. Read that section of the verdad man page for help.
If you need to unlock an item that someone else has left locked, you can use the unlock command for that too. But be careful... Verdad implements locking for a reason. Getting your changes stepped on by someone else is never any fun.
Jeff R. Allen <jra@nella.org>