CFV

add

add [-m MESSAGE ] [-c COMMITER ] [-n] [-q | -v] [--store=LEVEL] {-i FILE | ITEMS}

Register new files to be tracked in cfvers. The files can be given as arguments to the command or in a file denoted by the -i option. The options mean:

cat

cat [-r REVNO ] {ITEM}

Show the data contents of the specified ITEM. By default, the latest version of the items is given; a different version can be selected by using the -r option, with a single revision number.

The data contents is defined as:

diff

diff [-r REVNO ] [-l] {ITEM...}

Shows the difference between two versions of the arguments given. By default, the diff is made between the latest revision in the repository and the current version (in the filesystem).

The diff command can also be used to check which items have been modified, by using the -l. In this case, the output will just contain the names of the items which are different between the revisions selected, one item per line.

For each item, the diff output has two parts, each optional. If the item's version differ in data contents, an unified diff over the two versions will be shows. If the versions differ in metadata, an unified diff over a textual representation of the metadata will be shown.

export

export [-F FORMAT ] [-o FILENAME ]

Exports the content of the repository. The export format can be "tar" or "sha1sum" (the default).

The entries to be exported can be filtered using the options under the Finding entries section.

The output destination can be specified with the -o option. The default is standard output, which cand also be specifically denoted using "-" as the destination.

If the search options specify all revisions, then the file names will be prefixed with the path r=REVNO/.

find

find [-l] [-d]

The find command searches the contents of the repository.

The tests available are those described under the Find entries options section.

Output control: by default, the listing format is one item name per line, but it can be changed using the options -l and -d.

The -d show an expanded format with informations like:

	    File /etc
	    Registered at: 2003-10-13 21:33:17
	    Has revisions: 1-3, 4, 6, 8-10
 
	    File /etc/.pwd.lock
	    Created at: 2003-10-13 21:33:18
	    Has revisions: 8-10

The -l option shows an 'ls -l' like format, with the following fields:

1. mode representation (e.g. -rwxrwxrwx)

2. number of revisions in the repository

3. owner registered in last version

4. group registered in last version

5. size of item's last version

6. time, in ISO format: YYYY-MM-DD HH:MM:SS

7. name

list

list [--regexp REGEXP ] [--name GLOB ] [--format FORMAT ]

The list command lists all the items which are being tracked by the repository. Note that being tracked does not necesarily mean there is data in the repository about them, except their name. An item could have no entries, or it could exist in the repository just to let the software know it must not store any information about it.

The --regexp and --name options restrict the output to names matching (not anchored) the regexp, respectively the shell globbing pattern.

The --format option changes the output. Its argument is a string (used by Python interpolation mechanism), which can contain:

• normal characters except %

• a '%%' sequence to denote an % in the actual output

• a % character, followed by the name of a property of the item in paranthesis, followed by a C printf format specifier.. The allowed properties are:

  id

  The id of the item, of type integer. You can use either the 'i', 'd', 'x' or 's' conversion specifiers.

  ctime

  The time when the item has been added to the repository. It is of type string.

  name

  The name of the item, type string.

  flag

  A single character expressing the desired storage level of an item. Currently defined values:

  N

  No information will ever be stored about this file.

  M

  A regular file with only metadata stored (the information collected by a stat(2) call.

  C

  A regular file with metadata and checksum stored. This means that differences in file contents will be detected by the diff command (hopefully, as long as there are no SHA1 collisions), but the repository is kept small.

  F

  A regular will with all attributes stored: metadata, checksum and contents.

  V

  A virtual file.

  ?

  Unknown status. Probably a desynchronisation between cfv and the cfvers library.

  For example, the default format specifier is: %(id)5d %(f_metadata)c%(f_checksum)c%(f_contents)c %(name)s, which means: the id formatted as an integer, occupying five space, the three flags, each one characther, followed by the name of the file.

log

log [-r REVNO[:REVNO] ] {ITEM...}

The log command shows the log messages of the repository. By default, the full log is shown, however you can restrict the log to a revision or a range of revisions using the -r option with one or two arguments. The one argument form will restrict the output to only one revision, while the two-argument form will restrict the output to all revisions between those given (inclusive).

You can also restrict the log messages to some items by giving them as arguments to the command.

The final set of the revisions show is the intersection of the set of selected revisions (using -r) and the set computed as the union of the revisions numbers of the items given.

register

register [-m MESSAGE ] [-c COMMITER ] [-q] {NAME} {CMDLINE...}

Register a virtual file to be tracked in cfvers. The file look like a normal file, except that its contents is taken from the output of a command, not from an actual file. Beside that, it does not have the usual metadata (owner, permissions, etc.) but it has an additional attribute: the exit code. The options mean:

retrieve

retrieve [-r REVNO ] [-d DIRECTORY ] [-n] [-s] [-q] {ITEM...}

The retrieve command restores the given items to the filesystem. By default, the latest version in the repository is restored; use -rREVNUM to restore another version.

A message is shown for each item restored; this can be disabled using the -q option.

By default, the items are restored to their original location; this behavior can be modified using the -d and -s switches.

Also by default, any items given which are directories will be processed recursively, restoring all items which can be reached starting with them. To disable this behavior, use the -n option.

The -dDIRECTORY option can be used to change to top directory of the restore process: for example, the item /etc/passwd can be restored under /tmp/etc/passwd by giving the option -d/tmp.

The -s option can be used to disable the restoration of paths from the filenames. With the above example, to restore the file /etc/passwd to /tmp/passwd you can use the command line cfv retrieve -d/tmp -s /etc/passwd. Note that using just -s alone, all files will be restored under /.

Note that the restoration process will not be able to restore the ctime of any items. This is by design in the POSIX filesystem layer: the ctime is for metadata modifications, and the mtime/atime pair for data write/read accesses. Thus a ctime modification would trigger a ctime modification, since the ctime itself is part of metadata, rendering useless the ctime modification :). A read attribute for the metadata would be innapropriate, IMHO, because such reads are made in a great amount. The list of other restrictions in the restore process follows:

stat

stat [-r REVNO ] [ITEM...]

The 'stat' command displays information about the metadata of the given items (or all items in the repository), as recorded when they were stored in the repository.

By default, information about the latest revision is given, however you can select a certain revision by passing the -rREVNO option.

The output is formatted to look like the output of the command line utility stat from GNU coreutils.

store

store [-n] [-m MESSAGE ] [-c COMMITER ] [-q] {ITEM...}

This command stores new version of the items, if they have been modified. Note that if no items can't be read, the operation will abort; with at least one item successfully read, the operation will continue, generating warnings for items with problems.

A log message is shown for each item being stored; to disable this, use the -q option.

The log message must be given using the -m option.

Information about the commiter can be given using the -c option. This should be used with something like 'cron-autocommit', or 'pre-upgrade-autocommit', since cfvers is designed to also run in automated mode; here the uid/gid would be 0 always, so we wouldn't get useful information from there. By default, the commiter string is equal to the login name of the user.