List of settings that modify FSVS' behaviour. More...
List of settings that modify FSVS' behaviour.
FSVS understands some options that modify its behaviour in various small ways.
This document lists all available options in FSVS, in an full listing and in groups.
Furthermore you can see their relative priorities and some examples.
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 debug_buffer
- Using a debug buffer 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 empty_message
- Avoid commits without a commit message filter
- Filtering entries, but see -f. group_stats
- Getting grouping/ignore statistics. limit
- "fsvs log" revision limit log_output
- "fsvs log" output format merge_prg
, merge_opt
- Options regarding the "merge" program mkdir_base
- Creating directories in the repository above the URL path
- Displaying paths softroot
- Using an alternate root directory stat_color
- Status output coloring stop_change
- Checking for changes in a script verbose
- Verbosity flags warning
- Setting warning behaviour, but see -W. waa
- waa. The priorities are
FSVS_
{upper-case option name}. $HOME/.fsvs/wc-dir/config
$FSVS_CONF/wc-dir/config
$HOME/.fsvs/config
$FSVS_CONF/config
$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.
Using the commandline:
fsvs -o path=environment fsvs -opath=environment
Using environment variables:
FSVS_PATH=absolute fsvs st
A configuration file, from $FSVS_CONF/config
or in a WC-specific path below $FSVS_CONF
:
# FSVS configuration file path=wcroot
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 no
, will cause children of removed entries to be omitted.
Example for the config file:
all_removed=no
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.
-odir_sort=no
.Please see the command line parameter for -f, which is identical.
fsvs -o filter=mtime
There are some defaults for the number of revisions that are shown on a "fsvs log"
command:
-rX:Y
): abs
(X-Y)+1, ie. all revisions in that range. HEAD
to 1, with a maximum of 100. As this option can only be used to set an upper limit of revisions, it makes most sense for the no-revision-arguments case.
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. 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.
log_output=color
,indent in the global config file, and use log_output=color
on the commandline, only colors are used. This is different to the Filtering entries option, which is cumulating.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
absolute
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
full-environment
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 .mC. 1001 ./etc/X11/xorg.conf $ fsvs -o path=absolute st .mC. 1001 /etc/X11/xorg.conf $ fsvs -o path=parameters st .mC. 1001 X11/xorg.conf $ fsvs -o path=parameters st . .mC. 1001 ./X11/xorg.conf $ fsvs -o path=parameters st / .mC. 1001 /etc/X11/xorg.conf $ fsvs -o path=parameters st X11 .mC. 1001 X11/xorg.conf $ fsvs -o path=parameters st ../dev/.. .mC. 1001 ../dev/../etc/X11/xorg.conf $ fsvs -o path=parameters st X11 ../etc .mC. 1001 X11/xorg.conf $ fsvs -o path=parameters st ../etc X11 .mC. 1001 ../etc/X11/xorg.conf $ fsvs -o path=environ st .mC. 1001 ./etc/X11/xorg.conf $ WCBAR=/etc fsvs -o path=wcroot st .mC. 1001 $WCBAR/X11/xorg.conf $ WCBAR=/etc fsvs -o path=wcroot st / .mC. 1001 $WCBAR/X11/xorg.conf $ WCBAR=/e fsvs -o path=wcroot st .mC. 1001 /etc/X11/xorg.conf $ WCBAR=/etc WCFOO=/etc/X11 fsvs -o path=wcroot st .mC. 1001 $WCFOO/xorg.conf $ touch /etc/X11/xinit/xinitrc $ fsvs -o path=parameters st .mC. 1001 X11/xorg.conf .m.? 1001 X11/xinit/xinitrc $ fsvs -o path=parameters st X11 /etc/X11/xinit .mC. 1001 X11/xorg.conf .m.? 1001 /etc/X11/xinit/xinitrc
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.
If you want to use FSVS in scripts, you might simply want to know whether anything was changed.
In this case use the stop_on_change
option, possibly combined with Filtering entries; this gives you no output on STDOUT
, but an error code on the first change seen:
fsvs -o stop_change=yes st /etc if fsvs status -o stop_change=yes -o filter=text /etc/init.d then echo No change found ... else echo Changes seen. fi
If you want a bit more control about the data you're getting you can use some specific flags for the verbose
options.
none
,veryquiet - reset the bitmask, don't display anything. quiet
- only a few output lines. changes
- the characters showing what has changed for an entry. size
- the size for files, or the textual description (like "dir"
). path
- the path of the file, formatted according to the path option. default
- The default value, ie. changes
, size
and name
. meta
- One more than the default so it can be used via a single "-v"
, it marks that the mtime and owner/group changes get reported as two characters.If "-v"
is used to achieve that, even entries without changes are reported, unless overridden by Filtering entries. url
- Displays the entries' top priority URL copyfrom
- Displays the URL this entry has been copied from (see copy). group
- The group this entry belongs to, see group urls
- Displays all known URLs of this entry stacktrace
- Print the full stacktrace when reporting errors; useful for debugging. all
- Sets all flags. Mostly useful for debugging. Please note that if you want to display fewer items than per default, you'll have to clear the bitmask first, like this:
fsvs status -o verbose=none,changes,path
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
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
.Advanced users might be interested in exported environment variables, too; with their help you can eg. start different diff
programs depending on the filename.
If you have colordiff
installed on your system, you might be interested in the colordiff
option.
It can take one of these values:
no
, off
or false:
Don't use colordiff
. colordiff
as executable, but don't throw an error if it can't be started; just pipe the data as-is to STDOUT
. (Auto mode.) 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.
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.
The conflict must be solved manually, and the solution made known to FSVS via the resolve command.
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 (again) have to tell FSVS that the conflict is solved, by using the resolve command.
svn
the auxiliary files are seen as new, although that might change in the future (so that they automatically get ignored).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
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.
sshd_config
needs the PermitUserEnvironment
setting; you can also take a look at the AcceptEnv
and SendEnv
documentation.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
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
If you don't like the behaviour that FSVS does commits with an empty message received from $EDITOR
(eg if you found out that you don't want to commit after all), you can change this option to no
; then FSVS won't allow empty commit messages.
Example for the config file:
empty_message=no
If you want to keep some data versioned, the first commit is normally the creation of the base directories above the given URL (to keep that data separate from the other repository data).
Previously this had to be done manually, ie. with a svn mkdir $URL --parents
or similar command.
With the mkdir_base
option you can tell FSVS to create directories as needed; this is mostly useful on the first commit.
fsvs urls ... fsvs group 'group:ignore,./**' fsvs ci -m "First post!" -o mkdir_base=yes
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
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
none | Resets the check bitmask to "no checks". |
file_mtime | Check files for modifications (via MD5) and directories for new entries, if the mtime is different - default |
dir | Check all directories for new entries, regardless of the timestamp. |
allfiles | Check all files with MD5 for changes ( |
full | All available checks. |
You can give multiple options; they're accumulated unless overridden by none
.
fsvs -o change_check=allfiles status
dir
option, to avoid missing new files.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
(for "expensive", which takes the usual yes
(default) and no
arguments.
fsvs copyfrom-detect -o copyfrom_exp=no some_directory
If you need to ignore many entries of your working copy, you might find that the ignore pattern matching takes some valuable time.
In order to optimize the order of your patterns you can specify this option to print the number of tests and matches for each pattern.
$ fsvs status -o group_stats=yes -q Grouping statistics (tested, matched, groupname, pattern): 4705 80 ignore group:ignore,.
For optimizing you'll want to put often matching patterns at the front (to make them match sooner, and avoid unnecessary tests); but if you are using other groups than ignore
(like take
), you will have to take care to keep the patterns within a group together.
Please note that the first line shows how many entries were tested, and that the next lines differ by the number of matches entries for the current line, as all entries being tested against some pattern get tested for the next too, unless they match the current pattern.
This option is available for status and the ignore test commands.
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
$FSVS_CONF
resp. $FSVS_WAA
) or as command line parameter; settings in config files are ignored.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
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.)
$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.
chroot()
would not work, as some needed programs (eg. the decoder for update, see Special property names) would not be available.softroot
is: If you want to do a chroot()
into the given directory (or boot with it as /
), you'll want this set.The next two options could be set in the global configuration file, to automatically get the last debug messages when an error happens.
To provide an easy way to get on-line debugging again, debug_output
and debug_buffer
are both reset to non-redirected, on-line output, if more than a single -d
is specified on the command line, like this:
fsvs commit -m "..." -d -d filenames
In this case you'll get a message telling you about that.
You can specify the debug output destination with the option debug_output
. This can be a simple filename (which gets truncated on open), or, if it starts with a |, a command that the output gets piped into.
If the destination cannot be opened (or none is given), debug output goes to STDOUT
(for easier tracing via less
).
Example:
fsvs -o debug_output=/tmp/debug.out -d st /etc
-o debug_output=... -d
.An example: writing the last 200 lines of debug output into a file.
fsvs -o debug_output='| tail -200 > /tmp/debug.log' -d ....
With the debug_buffer
option you can specify the size of a buffer (in kB) that is used to capture the output, and which gets printed automatically if an error occurs.
This must be done before debugging starts, like with the debug_output specification.
fsvs -o debug_buffer=128 ...
Please see the command line parameter -W, which is identical.
fsvs -o warning=diff-status=ignore