NAME
Further options for FSVS. - FSVS understands some other options, that
modify its behaviour.
Short list of options
FSVS currently knows:
· all_removed - Trimming the list of deleted entries
· author - Author
· change_check - Change detection
· colordiff - Using colordiff
· commit_to - Destination URL for commit
· conflict - How to resolve conflicts on update
· conf - Path definitions for the config and WAA area.
· config_dir - Configuration directory for the subversion libraries.
· copyfrom_exp - Avoiding expensive compares on copyfrom-detect
· debug_output - Destination for debug output
· delay - Waiting for a time change after working copy operations
· diff_prg, diff_opt, diff_extra - Options relating to the ’diff’
action
· dir_sort - Directory sorting
· empty_commit - Doing empty commits
· filter - Filtering entries, but see -f.
· limit - ’fsvs log’ revision limit
· log_output - ’fsvs log’ output format
· merge_prg, merge_opt - Options regarding the ’merge’ programm
· path - Displaying paths
· softroot - Using an alternate root directory
· stat_color - Status output coloring
· stop_on_change - Stopping status reports as soon as changes are found
· warning - Setting warning behaviour, but see -W.
· waa - o_waa.
Priorities for option setting
The priorities are
· Command line (highest)
· Environment variables. These are named as FSVS_{upper-case option
name}.
· $HOME/.fsvs/wc-dir/config
· $FSVS_CONF/wc-dir/config
· $HOME/.fsvs/config
· $FSVS_CONF/config
· Default value, compiled in (lowest)
Note:
The $HOME-dependent configuration files are not implemented
currently. Volunteers?
Furthermore there are ’intelligent’ run-time dependent settings, like
turning off colour output when the output is redirected. Their priority
is just below the command line - so they can always be overridden if
necessary.
Examples
Using the commandline:
fsvs -o path=environment
fsvs -opath=environment
Using environment variables:
FSVS_PATH=absolute fsvs st
A configuration file:
# FSVS configuration file
path=wcroot
Displaying paths
You can specify how paths printed by FSVS should look like; this is
used for the entry status output of the various actions, and for the
diff header lines.
There are several possible settings, of which one can be chosen via the
path option.
· wcroot
This is the old, traditional FSVS setting, where all paths are
printed relative to the working copy root.
· parameter
With this setting FSVS works like most other programs - it uses the
first best-matching parameter given by the user, and appends the rest
of the path.
This is the new default.
Note:
Internally FSVS still first parses all arguments, and then does a
single run through the entries. So if some entry matches more than
one parameter, it is printed using the first.
· absolute
All paths are printed in absolute form. This is useful if you want
to paste them into other consoles without worrying whether the
current directory matches.
The next two are nearly identical to absolute, but the beginning of
paths are substituted by environment variables. This makes sense if you
want the advantage of full paths, but have some of them abbreviated.
· environment
Match variables to directories after reading the known entries, and
use this cached information. This is faster, but might miss the best
case if new entries are found (which would not be checked against
possible longer hits).
Furthermore, as this works via associating environment variables to
entries, the environment variables must at least match the working
copy base - shorter paths won’t be substituted.
· full-environment
Check for matches just before printing the path.
This is slower, but find the best fit.
Note:
The string of the environment variables must match a directory
name; the filename is always printed literally, and partial string
matches are not allowed. Feedback wanted.
Only environment variables whose names start with WC are used for
substitution, to avoid using variables like $PWD, $OLDPWD, $HOME
and similar which might differ between sessions. Maybe the allowed
prefixes for the environment variables should be settable in the
configuration. Opinions to the users mailing list, please.
Example, with / as working copy base:
$ cd /etc
$ fsvs -o path=wcroot st
$ fsvs -o path=absolute st
$ fsvs -o path=parameters st
$ fsvs -o path=parameters st .
$ fsvs -o path=parameters st /
$ fsvs -o path=parameters st X11
$ fsvs -o path=parameters st ../dev/..
$ fsvs -o path=parameters st X11 ../etc
$ fsvs -o path=parameters st ../etc X11
$ fsvs -o path=environ st
$ WCBAR=/etc fsvs -o path=wcroot st
$ WCBAR=/etc fsvs -o path=wcroot st /
$ WCBAR=/e fsvs -o path=wcroot st
$ WCBAR=/etc WCFOO=/etc/X11 fsvs -o path=wcroot st
$ touch /etc/X11/xinit/xinitrc
$ fsvs -o path=parameters st
$ fsvs -o path=parameters st X11 /etc/X11/xinit
Note:
At least for the command line options the strings can be
abbreviated, as long as they’re still identifiable. Please use the
full strings in the configuration file, to avoid having problems in
future versions when more options are available.
Options relating to the ’diff’ action
The diff is not done internally in FSVS, but some other program is
called, to get the highest flexibility.
There are several option values:
· diff_prg: The executable name, default ’diff’.
· diff_opt: The default options, default ’-pu’.
· diff_extra: Extra options, no default.
The call is done as
$diff_prg $diff_opt $file1 --label ’$label1’ $file2 --label ’$label2’ diff_extra
Note:
In diff_opt you should use only use command line flags without
parameters; in diff_extra you can encode a single flag with
parameter (like ’-U5’). If you need more flexibility, write a shell
script and pass its name as diff_prg.
Very advanced users might be interested in exported
environmentvariables’, too.
Using colordiff
If you have colordiff installed on your system, you might be interested
in the colordiff option.
It can take on of these values:
· no, off or false: Don’t use colordiff.
· empty (default value): Try to use colordiff as executable, but don’t
throw an error if it can’t be started; just pipe the data as-is to
STDOUT.
· anything else: Pipe the output of the diff program (see Options
relating to the ’diff’ action) to the given executable.
Please note that if STDOUT is not a tty (eg. is redirected into a
file), this option must be given on the command line to take effect.
Filtering entries
Please see the command line parameter for -f, which is identical.
fsvs -o filter=mtime
Trimming the list of deleted entries
If you remove a directory, all entries below are implicitly known to be
deleted, too. To make the status output shorter there’s the all_removed
option; which, if set to yes, will cause children of removed entries to
be omitted.
Example for the config file:
all_removed=yes
Change detection
This options allows to specify the trade-off between speed and
accuracy.
A file with a changed size can immediately be known as changed; but if
only the modification time is changed, this is not so easy. Per default
FSVS does a MD5 check on the file in this case; if you don’t want that,
or if you want to do the checksum calculation for every file (in case a
file has changed, but its mtime not), you can use this option to change
FSVS’ behaviour.
On the command line there’s a shortcut for that: for every ’-C’ another
check in this option is chosen.
The recognized specifications are noneResets the check bitmask to ’no
checks’. file_mtimeCheck files for modifications via MD5 if the mtime
is different - default dirCheck all directories for new entries - this
happens normally if a directory ha allfilesCheck all files with MD5 for
changes (tripwire -like operation). fullAll available checks.
You can give multiple options; they’re accumulated unless overridden by
none.
fsvs -o change_check=allfiles status
Note:
commit and update set additionally the dir option, to avoid missing
new files.
Setting warning behaviour
Please see the command line parameter -W, which is identical.
fsvs -o warning=diff-status=ignore
Using an alternate root directory
This is a path that is prepended to $FSVS_WAA and $FSVS_CONF (or their
default values, see Files used by fsvs), if they do not already start
with it, and it is cut off for the directory-name MD5 calculation.
When is that needed? Imagine that you’ve booted from some Live-CD like
Knoppix; if you want to setup or restore a non-working system, you’d
have to transfer all files needed by the fsvs binary to it, and then
start in some kind of chroot environment.
With this parameter you can tell fsvs that it should load its libraries
from the current filesystem, but use the given path as root directory
for its administrative data.
This is used for recovery; see the example in Recovery for a non-
booting system.
So how does this work?
· The internal data paths derived from $FSVS_WAA and $FSVS_CONF use the
value given for softroot as a base directory, if they do not already
start with it.
(If that creates a conflict for you, eg. in that you want to use
/var as the softroot, and your $FSVS_WAA should be /var/fsvs, you can
make the string comparison fail by using /./var for either path.)
· When a directory name for $FSVS_CONF or $FSVS_WAA is derived from
some file path, the part matching softroot is cut off, so that the
generated names match the situation after rebooting.
Previously you’d have to export your data back to the filesystem and
call urls ’fsvs urls’ and fsvs sync-repos again, to get the WAA data
back.
Note:
A plain chroot() would not work, as some needed programs (eg. the
decoder for update, see Special property names) would not be
available.
The easy way to understand softroot is: If you want to do a
chroot() into the given directory (or boot with it as /), you’ll
want this set.
As this value is used for finding the correct working copy root (by
trying to find a conf-path, it cannot be set from a per-wc config
file. Only the environment, global configuration or command line
parameter make sense.
’fsvs log’ revision limit
There are some defaults for the number of revisions that are shown on a
’fsvs log’ command:
· 2 revisions given (-rX:Y): abs(X-Y)+1, ie. all revisions in that
range.
· 1 revision given: exactly that one.
· no revisions given: from HEAD to 1, with a maximum of 100.
So this command is mostly useful to get more than the default number of
revisions on when running without revision arguments, or to get fewer.
’fsvs log’ output format
You can modify aspects of the fsvs log output format by setting the
log_output option to a combination of these flags:
· color: This uses color in the output, similar to cg-log (cogito-log);
the header and separator lines are highlighted.
Note:
This uses ANSI escape sequences, and tries to restore the default
color; if you know how to do that better (and more compatible),
please tell the developer mailing list.
· indent: Additionally you can shift the log message itself a space to
the right, to make the borders clearer.
Furthermore the value normal is available; this turns off all special
handling.
Note:
If you start such an option, the value is reseted; so if you
specify log_output=color,indent in the global config file, and use
log_output=color on the commandline, only colors are used. This is
a difference to the Filtering entries option, which is cumulating.
Status output coloring
FSVS can colorize the output of the status lines; removed entries will
be printed in red, new ones in green, and otherwise changed in blue.
Unchanged (for -v) will be given in the default color.
For this you can set stat_color=yes; this is turned off per default.
As with the other colorizing options this gets turned off automatically
if the output is not on a tty; on the command line you can override
this, though.
Directory sorting
If you’d like to have the output of status sorted, you can use the
option dir_sort=yes. FSVS will do a run through the tree, to read the
status of the entries, and then go through it again, but sorted by
name. (See dir_enumerator().)
Note:
If FSVS aborts with an error during status output, you might want
to turn this option off again, to see where fsvs stops; the easiest
way is on the commandline with -odir_sort=no.
Author
You can specify an author to be used on commit. This option has a
special behaviour; if the first character of the value is an ’$’, the
value is replaced by the environment variable named.
Empty strings are ignored; that allows an /etc/fsvs/config like this:
author=unknown
author=$LOGNAME
author=$SUDO_USER
where the last non-empty value is taken; and if your .authorized_keys
has lines like
environment=’FSVS_AUTHOR=some_user’ ssh-rsa ...
that would override the config values.
Note:
Your sshd_config needs the PermitUserEnvironment setting; you can
also take a look at the AcceptEnv and SendEnv documentation.
Destination URL for commit
If you defined multiple URLs for your working copy, FSVS needs to know
which URL to commit to.
For this you would set commit_to to the name of the URL; see this
example:
fsvs urls N:master,P:10,http://... N:local,P:20,file:///...
fsvs ci /etc/passwd -m ’New user defined’ -ocommit_to=local
Destination for debug output
See -d.
Example:
fsvs -o debug_output=/tmp/debug.out -d st /etc
Doing empty commits
In the default settings FSVS will happily create empty commits, ie.
revisions without any changed entry. These just have a revision number,
an author and a timestamp; this is nice if FSVS is run via CRON, and
you want to see when FSVS gets run.
If you would like to avoid such revisions, set this option to no; then
such commits will be avoided.
Example:
fsvs commit -o empty_commit=no -m ’cron’ /etc
ef cpfd ’copyfrom-detect’
Avoiding expensive compares on
If you’ve got big files that are seen as new, doing the MD5 comparison
can be time consuming. So there’s the option copyfrom_exp, which takes
the usual yes (default) and no arguments.
fsvs copyfrom-detect -o copyfrom_exp=no some_directory
Waiting for a time change after working copy operations
If you’re using fsvs in automated systems, you might see that changes
that happen in the same second as a commit are not seen with status
later; this is because the timestamp granularity of fsvs is 1 second.
For backward compatibility the default value is no (don’t delay). You
can set it to any combination of
· commit,
· update,
· revert and/or
· checkout;
for yes all of these actions are delayed until the clock seconds
change.
Example how to set that option via an environment variable:
export FSVS_DELAY=commit,revert
Stopping status reports as soon as changes are found
If you want to use FSVS in scripts, you might simply want to know
whether anything was changed.
For this use the stop_on_change option, possibly combined with
Filtering entries :
fsvs -o stop_change=yes st /etc
fsvs -o stop_change=yes -o filter=text status /etc/init.d
How to resolve conflicts on update
If you start an update, but one of the entries that was changed in the
repository is changed locally too, you get a conflict.
There are some ways to resolve a conflict:
· local - Just take the local entry, ignore the repository.
· remote - Overwrite any local change with the remote version.
· both - Keep the local modifications in the file renamed to
filename.mine, and save the repository version as filename.rXXX, ie.
put the revision number after the filename.
These files will be seen as New; the conflict must be solved manually,
and the resolution made known to FSVS via resolve.
Note:
As there’s no known good version after this renaming, a zero byte
file gets created.
Any resolve or revert command would make that current, and the
changes that are kept in filename.mine would be lost!
You could only revert to the last repository version, ie. the data
of filename.rXXX.
· merge - Call the program merge with the common ancestor, the local
and the remote version.
If it is a clean merge, no further work is necessary; else you’ll get
the (partly) merged file, and the two other versions just like with the
both variant, and have to tell FSVS that the conflict is resolved by
resolve.
Note:
As in the subversion command line client svn the auxiliary files
are seen as new, although that might change in the future (so that
they automatically get ignored).
Options regarding the ’merge’ programm
Like with diff, the merge operation is not done internally in FSVS.
To have better control
· merge_prg: The executable name, default ’merge’.
· merge_opt: The default options, default ’-A’.
The option ’-p’ is always used:
$merge_prg $merge_opt -p $file1 $common $file2
Path definitions for the config and WAA area
The paths given here are used to store the persistent configuration
data needed by FSVS; please see Files used by fsvs and Priorities for
option setting for more details, and the Using an alternate root
directory parameter as well as the Recovery for a non-booting system
for further discussion.
FSVS_CONF=/home/user/.fsvs-conf fsvs -o waa=/home/user/.fsvs-waa st
Note:
Please note that these paths can be given only as environment
variables ($FSVS_CONF resp. $FSVS_WAA) or as command line
parameter; settings in config files are ignored.
Configuration directory for the subversion libraries
This path specifies where the subversion libraries should take their
configuration data from; the most important aspect of that is
authentication data, especially for certificate authentication.
The default value is $FSVS_CONF/auth/.
/etc/fsvs/config could have eg.
config_dir=/root/.subversion