SYNOPSIS
cfv [global_options] command [command_options] [command_arguments]
cfv [--version]
cfv [--help]
DESCRIPTION
This manual page documents briefly the cfv command, version 0.5.4.
cfvers is a version control system designed for the management of con-
figuration files in Unix-like operating systems..
cfv is the command-line client used to register files into cfvers,
restore them, display information about the contents of the reposito-
ries, etc.
ESSENTIAL COMMANDS
cfv provides several command for working with files and repositories,
each of them having their options. The most used of them are:
cfv add item...
Registers new items into the repsository. This signals the
intent to track a file for changes.
cfv store item...
Stores a new version of item into the repsository.
cfv retrieve item...
Retrieves an item from the repository. If it denotes a direc-
tory, all items registered in the repository underneath it
are restored.
OPTIONS
These options follow the usual GNU command line syntax, with long
options starting with two dashes (`-'). cfv has two classes of options:
global options and command options.
GLOBAL OPTIONS
These are the global options to cfv
-h, --help
Show summary of options.
--version Show the version of the program and copyright information.
--local Connect directly to the repository, in contrast to connecting
through the cfversd server. When selecting this option, you
can specify the repository through:
--rtype Selects the repository type: either sqlite or post-
The name or address of the server.
-p, --port PORT
The port on which the server is listening.
-u, --username USER
The username used for authentication to the server
Note that unless you put in the configuration file (~/.cfvers) the
password for the client and server or in the environment, you will be
prompted for them.
-aAREA, --area=AREA
Selects the area to be used. By default, the area used is the
one called 'default'.
cfv command summary
Here are the brief descriptions of the cfv commands:
add Registers a file for tracking.
addnew Registers new files in the directories already tracked by the
repository.
cat Shows the contents of a item from the repository. For regular
files, this will be the contents of the file, while for other
type of items this will be a textual representation of the
item.
diff Shows differences between the contents of the repository and
the filesystem, or between versions in the repository for the
arguments. The items are checked in differences in both data
and metadata.
export Exports the contents of the repository either in ``tar'' or
``sha1sum'' format.
find Searches the entries in the repository by their attributes.
list Lists the items in the repository.
log Show the changelog of the revision(s) selected. By default,
show the full changelog of all versions.
register Registers a virtual file for tracking.
retrieve Retrieve some or all items from the repository.
stat Show information about the metadata of selected items, like
the stat command-line utility from GNU coreutils.
store Stores new versions of files to the repository.
sions are needed, they should be given separated by a colon
(:).
FINDING ENTRIES OPTIONS
This section describes the command options that are available for
selecting entries. These options are common to the find and export com-
mands.
--all-areas
Entries from all areas will be included in the search, not
only from the current area
--all-entries
Return all matching entries for a file, not only latest. For
example, when selecting revisions lower than 15, by default
only the greatest revision lower than 15 would be selected.
With this option, all revisions lower than 15 will be taken
into consideration
--logmsg REGEX PATTERN
The revisions with the log message matching the regular
expression pattern given will be selected.
--revno COMPARISON_OPERATOR REVNO
Check for matching revision numbers using the given compari-
son operator and revision number.
--empty Select empty regular files and empty directories.
--gid COMPARISON_OPERATOR NUMERIC_GID
Select files having the group ID match the given comparison
operator and numeric value.
--group TEXT_OPERATOR GROUP_NAME
Select files having the group name match the given text oper-
ator and string value.
--uid COMPARISON_OPERATOR NUMERIC_UID
Select files having the user ID match the given comparison
operator and numeric value.
--user TEXT_OPERATOR USER_NAME
Select files having the user name match the given text opera-
tor and string value.
--regex PATTERN
Select files having names matching regular expression PAT-
TERN; this is a match on the whole path, not a search.
--iregex PATTERN
Like --regex, but the match is case insensitive.
b for block devices
c for character devices
p for pipes
s for sockets
v for virtual files
--nouser No user corresponded to file's numeric user ID at store time.
--nogroup No group corresponded to file's numeric group ID at store
time.
--name GLOB
Base of file name (the path with the leading directories
removed) matches the given shell pattern.
--iname GLOB
Like --name, but the match is case insensitive.
--path GLOB
File name (including path) matches the given shell pattern.
--ipath GLOB
Like --path, but the match is case insensitive.
--lname GLOB
File is a symbolic link whose target matches the given shell
pattern.
--ilname GLOB
Like --lname, but the match is case insensitive.
--links COMPARISON_OPERATOR VALUE
File's number of links match the given comparison operator
and numeric value.
--inum COMPARISON_OPERATOR N
File's inode number match the given comparison operator and
numeric value.
--perm EQ | LT | GT MODE
The file's permission bits are equal to, contain any bits in,
or contain all bits in the given MODE (octal value).
CFV COMMANDS
Here (finally) are details on all the cfv commands and the options each
accepts.
-c, --commiter
Information about the commiter can be given using the -c
option. This should be used with something like 'cron-auto-
commit', 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.
-n, --no-recursive
For directories, don't also add the files they contain.
-q, --quiet
Show only errors; the usual statistics are not shown.
-v, --verbose
Show additional information about all item being added.
--store=LEVEL
For each item, cfvers can store a variable amount of informa-
tion, determined at its registration time. The LEVEL argument
can take the values:
o metadata, meaning only the metadata of the files is
stored and no information about their contents; this
means that at most a stat(2) system call is made on the
file;
o checksum, meaning that in addition to the metadata, a
checksum of the file (SHA1) is computed and stored;
o full, meaning that metadata, checksum and file contents
are stored;
-i, --inputfile=FILE
The contents of the FILE (separated by newfiles) are added as
additional file names to register. The FILE can also be -, in
which case standard input is used.
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:
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 modi-
fied, 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
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:
o normal characters except %
o a '%%' sequence to denote an % in the actual output
o 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 reposi-
tory. 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 col-
lisions), but the repository is kept small.
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:
-m, --logmsg MESSAGE
The revision will have MESSAGE as the log message. If not
given and standard input is a tty, it will be read (using
$EDITOR or $VISUAL); otherwise the operation will abort.
-c, --commiter
Information about the commiter can be given using the -c
option. This should be used with something like 'cron-auto-
commit', 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.
-q, --quiet
Show only errors; the usual statistics are not shown.
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.
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:
regular files, device files, FIFOs
These files will have almost all attributes restored. Of
course, devices files restoration won't restore your devices
:-)
directories
The restoration of directories is special, since they are
non-leaf items. All other types currently supported by cfvers
are leaf items and thus can be restored fully by themselves.
However, the content of directories cannot be restored if it
hasn't been stored in the repository.
Also, the mtime attribute of directories is not currently
restored correctly, since the order of restoration is impor-
tant: it should be depth first, but the parent directories
need to be created first. To fix this, we need to make a dou-
ble pass - currently all restores are one-shot.
symbolic links
The problem with simbolic links is that POSIX doesn't specify
functions to set some attributes of the symbolic links them-
selves: for example, utime(2) or utimes(2) always act on the
symbolic link target. Also, the chown(2) doesn't work on sym-
bolic links. The owner/group can be changed, though, using
the lchown function.
sockets These are not restored, as they don't contain any payload,
and they are usually created by the application at startup
time.
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.
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 informa-
tion from there. By default, the commiter string is equal to the login
name of the user.
SEE ALSO
cfvadmin(1), cfvers.conf(5), cfvers user manual
cvs(1), svn(1)
AUTHOR
This manual page was written by Iustin Pop iusty@k1024.org
The manual pages cvs(1) and svn(1) were used as sources of inspiration
(and copy-paste in some cases), since these are real versioning pro-
grams :-), with proper man pages.
CFV(1)
Man(1) output converted with
man2html