Provided by: fsvs_1.2.9-2ubuntu0.23.10.1_amd64 bug

NAME

       Further options for FSVS. -

       List of settings that modify FSVS' behaviour.  List of settings that modify FSVS'
       behaviour.

       FSVS understands some options that modify its behaviour in various small ways.

Overview

   This document
       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.

   Semantic groupsOutput settings and entry filteringDiffing and merging on updateOptions for commitPerformance and tuning related optionsBase configurationDebugging and diagnosing
   Sorted 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
       • 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_exclude_mtime - Ignore mtime-metadata changes for directories
       • 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.
   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, from $FSVS_CONF/config or in a WC-specific path below $FSVS_CONF:
            # FSVS configuration file
            path=wcroot

Output settings and entry filtering

   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 no, will
       cause children of removed entries to be omitted.
       Example for the config file:
           all_removed=no

   Ignore mtime-metadata changes for directories
       When this option is enabled, directories where only the mtime changed are not reported on
       status anymore.
       This is useful in situations where temporary files are created in directories, eg. by text
       editors. (Example: VIM swapfiles when no directory option is configured).
       Example for the config file:
           dir_exclude_mtime=yes

   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.
       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 command line with
           -odir_sort=no.
   Filtering entries
       Please see the command line parameter for -f, which is identical.
           fsvs -o filter=mtime
   '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.
       As this option can only be used to set an upper limit of revisions, it makes most sense
       for the no-revision-arguments case.
   '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 reset; 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 different to the Filtering entries option,
           which is cumulating.
   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 match.
       •
          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, or for using them
         in pipelines.
       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 finds 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.
   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.
   Checking for changes in a script
       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

   Verbosity flags
       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

Diffing and merging on update

   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.
       Advanced users might be interested in exported environment variables, too; with their help
       you can eg. start different diff programs depending on the filename.
   Using colordiff
       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.
       • 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. (Auto mode.)
       • 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.
   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.
       The conflict must be solved manually, and the solution made known to FSVS via the resolve
       command.
       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 should 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 (again) have to tell
       FSVS that the conflict is solved, by using the resolve command.
       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' program
       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

Options for commit

   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

   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

   Avoid commits without a commit message
       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

   Creating directories in the repository above the URL
       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
   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

Performance and tuning related options

   Change detection
       This options allows one 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) and directories for new entries, if the
       mtime is different - default dirCheck all directories for new entries, regardless of the
       timestamp. 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 aeficpfda'copyfrom-detect'n, to avoid missing new files.
   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 (for 'expensive', which takes the usual yes
       (default) and no arguments.
               fsvs copyfrom-detect -o copyfrom_exp=no some_directory
   Getting grouping/ignore statistics
       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.

Base configuration

   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/svn/.
       /etc/fsvs/config could have eg.
           config_dir=/root/.subversion

       Please note that this directory can hold an auth directory, and the servers and config
       files.
   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.

Debugging and diagnosing

       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.
   Destination for debug output
       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

       Note:
           That string is taken only once - at the first debug output line. So you have to use
           the correct order of parameters: -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 ....

   Using a debug buffer
       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 ...
       Note:
           If this option is specified in the configuration file or via the environment, only the
           buffer is allocated; if it is used on the command line, debugging is automatically
           turned on, too.
   Setting warning behaviour
       Please see the command line parameter -W, which is identical.
           fsvs -o warning=diff-status=ignore

Author

       Generated automatically by Doxygen for fsvs from the source code.