|void||sigUSR1 (int num)|
fsvs command [options] [args]
The following commands are understood by FSVS:
Define working copy base directories by their URL(s)
Get a list of changed entries
Display detailed information about single entries
Fetch the log messages from the repository
Get differences between files (local and remote)
Ask FSVS about probably copied/moved/renamed entries; see cp
Define ignore patterns
Remove entries from versioning
Add entries that would be ignored
Tell FSVS that entries were copied
Send changed data to the repository
Get updates from the repository
Fetch some part of the repository, and register it as working copy
Get a file from the directory
Undo local changes and entry markings
Ask what an update would bring
The return code is
0 for success, or
2 for an error.
1 is returned if the option Stopping status reports as soon as changes are is used, and changes are found; see also Filtering entries.
-Vmakes FSVS print the version and a copyright notice, and exit.
If FSVS was compiled using
--enable-debugyou can enable printing of debug messages (to
-d. Per default all messages are printed; if you're only interested in a subset, you can use
-Dstart-of-function-name.would call the status action, printing all debug messages of all WAA functions -fsvs -d -D waa_ status
-Rswitches in effect just decrement/increment a counter; the behavious is chosen depending on that. So
-N -N -N -R -Ris equivalent to
set/clear verbosity flags, and so give more/less output.
Please see the verbose option for more details.
-Cchooses to use more change detection checks; please see the change_check option for more details.
This parameter allows to do a bit of filtering of entries, or, for some operations, modification of the work done on given entries.
It requires a specification at the end, which can be any combination of
def use the default value.
By giving eg. the value
text, with a status action only entries that are new or changed are shown; with
mtime,group only entries whose group or modification time has changed are printed.
If an entry gets replaced with an entry of a different type (eg. a directory gets replaced by a file), that counts as
If you use
-v, it's used as a
If an entry gets replaced with an entry of a different type (eg. a directory gets replaced by a file), that counts as
If you use the string
none, it resets the bitmask to no entries shown; then you can built a new mask. So
owner,none,any,none,delete would show deleted entries. If the value after all commandline parsing is
none, it is reset to the default.
Here you can define the behaviour for certain situations that should not normally happen, but which you might encounter.
The general format here is specification = action, where specification is a string matching the start of at least one of the defined situations, and action is one of these:
If specification matches more than one situation, all of them are set; eg. for meta=ignore all of meta-mtime, meta-user etc. are ignored.
If at least a single warning that is not ignored is encountered during the program run, a list of warnings along with the number of messages it would have printed with the setting always is displayed, to inform the user of possible problems.
The following situations can be handled with this:
meta-mtime, meta-user, meta-group, meta-umask These warnings are issued if a meta-data property that was fetched from the repository couldn't be parsed. This can only happen if some other program or a user changes properties on entries.
In this case you can use
-Wmeta=count, until the repository is clean again.
no-urllist This warning is issued if a info action is executed, but no URLs have been defined yet. charset-invalid If the function
nl_langinfo(3) couldn't return the name of the current character encoding, a default of UTF-8 is used. You might need that for a minimal system installation, eg. on recovery.
chmod-eperm, chown-eperm If you update a working copy as normal user, and get to update a file which has another owner but you may modify, you'll get errors because neither the user, group, nor mode can be set. chmod-other, chown-other If you get another error than
EPERM in the situation above, you might find these useful.
overlayed-entries This is not yet used. mixed-rev-wc If you specify some revision number on a revert, it will complain that mixed-revision working copies are not allowed. By using this specification you cannot enable mixed-revision working copies, of course, but you can avoid getting told every time. propname-reserved It is normally not allowed to set a property with the prop-set action with a name matching some reserved prefixes. ignpat-wcbase This warning is issued if an absolute ignore pattern" does not match the working copy base directory. diff-status GNU diff has defined that it returns an exit code 2 in case of an error; sadly it returns that also for binary files, so that a simply
fsvs diff some-binary-file text-file would abort without printing the diff for the second file. So the exit status of diff is per default ignored, but can be used by setting this option to eg. stop.
Also an environment variable FSVS_WARNINGS is used and parsed; it is simply a whitespace-separated list of option specifications.
Some commands can be reduced to a subset of defined URLs; the update command is a example.
If you have more than a single URL in use for your working copy,
update normally updates all entries from all URLs. By using this parameter you can tell FSVS to update only the specified URLs.
The parameter can be used repeatedly; the value can have multiple URLs, separated by whitespace or one of
fsvs up -u base_install,boot@32 -u gcc
This would get
gcc, and set the target revision of the
boot URL at 32.
This is used for setting some seldom used option, for which default can be set in a configuration file (to be implemented, currently only command-line).
For a list of these please see options.
fsvs add [-u URLNAME] PATH [PATH...]
With this command you can explicitly define entries to be versioned, even if they have a matching ignore pattern. They will be sent to the repository on the next commit, just like other new entries, and will therefore be reported as New .
-u option can be used if you're have more than one URL defined for this working copy and want to have the entries pinned to the this URL.
Say, you're versioning your home directory, and gave an ignore pattern of
./.*to ignore all
.*entries in your home-directory. Now you want
.ssh/config, and your complete
.kde3-treesaved, just like other data.
So you tell fsvs to not ignore these entries:
fsvs add .bashrc .ssh/config .kde3
.kde3 would match your earlier
./.* pattern (as a match at the beginning is sufficient), so you have to insert a negative ignore pattern (a take pattern):
fsvs ignore prepend t./.kde3
fsvs st would show your entries as New , and the next commit will send them to the repository.
fsvs unversion PATH [PATH...]
This command flags the given paths locally as removed. On the next commit they will be deleted in the repository, and the local information of them will be removed, but not the entries themselves. So they will show up as New again, and you get another chance at ignoring them.
Say, you're versioning your home directory, and found that you no longer want
.sh_historyversioned. So you doand these files will be reported asfsvs unversion .bash_history .sh_history
d(will be deleted, but only in the repository).
Then you do a
Now fsvs would report these files as
New , as it does no longer know anything about them; but that can be cured by
fsvs ignore "./.*sh_history"
The example also shows why the given paths are not just entered as separate ignore patterns - they are just single cases of a (probably) much broader pattern.
This is used mainly for debugging. It traverses the filesystem and build a new entries file. In production it should not be used - as the revision of the entries is unknown, we can only use 0 - and loose information this way!
This command delays execution until the time has passed at least to the next second after writing the dir and urls files. So, where previously the delay option was used, this can be substituted by the given command followed by the
The advantage is over the Waiting for a time change after working copy operations option is, that read-only commands can be used in the meantime.
fsvs commit /etc/X11 -m "Backup of X11"
... read-only commands, like "status"
fsvs delay /etc/X11
... read-write commands, like "commit"
In the testing framework it is used to save a bit of time; in normal operation, where FSVS commands are not so tightly packed, it is normally preferable to use the delay option.
fsvs cat [-r rev] path
Fetches a file with the specified revision or, if not given, BASE, from the repository, and outputs it to
fsvs checkout [path] URL [URLs...]
Sets one or more URLs for the current working directory (or the directory
path), and does an checkout of these URLs.
fsvs checkout . http://svn/repos/installation/machine-1/trunk
The distinction whether a directory is given or not is done based on the result of URL-parsing -- if it looks like an URL, it is used as an URL.
Please mind that at most a single path is allowed; as soon as two non-URLs are found an error message is printed.
If no directory is given,
. is used; this differs from the usual subversion usage, but might be better suited for usage as a recovery tool (where versioning
/ is common). Opinions welcome.
path must exist, and should be empty -- FSVS will abort on conflicts, ie. if files that should be created already exist.
If there's a need to create that directory, please say so; patches for some parameter like
-p are welcome.
fsvs commit [-m "message"|-F filename] [-v] [-C [-C]] [PATH [PATH ...]]
Commits the current state into the repository. It is possible to commit only parts of a working copy into the repository.
Your working copy is
/etc , and you've set it up and committed already. Now you've changed
/etc/hosts , and
/etc/inittab . Since these are non-related changes, you'd like them to be in separate commits.
So you simply run these commands:
fsvs commit -m "Added some host" /etc/hosts
fsvs commit -m "Tweaked default runlevel" /etc/inittab
If you're currently in
/etc , you can even drop the
/etc/ in front, and just use the filenames.
fsvs cp [-r rev] SRC DEST fsvs cp dump fsvs cp load
copy command marks
DEST as a copy of
SRC at revision
rev, so that on the next commit of
DEST the corresponding source path is sent as copy source.
The default value for
BASE, ie. the revision the
SRC (locally) is at.
Please note that this command works always on a directory structure - if you say to copy a directory, the whole structure is marked as copy. That means that if some entries below the copy are missing, they are reported as removed from the copy on the next commit.
(Of course it is possible to mark files as copied, too; non-recursive copies are not possible.)
If this command are used without parameters, the currently defined relations are printed; please keep in mind that the key is the destination name, ie. the 2nd line of each pair!
copy will try to run the
cp command, whereas
copied will just remember the relation.
The input format for
load is newline-separated - first a
SRC line, followed by a
DEST line, then an line with just a dot (
".") as delimiter. If you've got filenames with newlines or other special characters, you have to give the paths as arguments.
Internally the paths are stored relative to the working copy base directory, and they're printed that way, too.
Later definitions are appended to the internal database; to undo mistakes, use the revert action.
load necessary? Should
dump print the source revision number?
load as first parameter for copyfrom relations, give some path, too, as in
$ fsvs cp a b
$ rm a/1
$ fsvs ci a
$ fsvs ci b
But it is not implementd to give an URL as copyfrom source directly - we'd have to fetch a list (and possibly the data!) from the repository.
fsvs copyfrom-detect [paths...]
This command tells FSVS to look through the new entries, and see whether it can find some that seem to be copied from others already known.
It will output a list with source and destination path and why it could match.
This is just for information purposes and doesn't change any FSVS state, unless some option/parameter is set. (TODO)
The list format is on purpose incompatible with the
load syntax, as the best match normally has to be taken manually.
If verbose is used, an additional value giving the percentage of matching blocks, and the count of possibly copied entries is printed.
The abbreviations are:
md5 The MD5 of the new file is identical to that of one or more already committed files; there is no percentage. inode The device/inode number is identical to the given known entry; this could mean that the old entry has been renamed or hardlinked. Note: Not all filesystems have persistent inode numbers (eg. NFS) - so depending on your filesystems this might not be a good indicator! name The entry has the same name as another entry. manber Analysing files of similar size shows some percentage of (variable-sized) common blocks (ignoring the order of the blocks). dirlist The new directory has similar files to the old directory.
The percentage is (number_of_common_entries)/(files_in_dir1 + files_in_dir2 - number_of_common_entries).
If too many possible matches are found, not all may be printed; only the indicator
... is shown at the end.
If too many possible matches are found, not all may be printed; only the indicator
fsvs uncopy DEST [DEST ...]
uncopy command removes a
copyfrom mark from the destination entry. This will make the entry unknown again, and reported as
New on the next invocations.
Only the base of a copy can be un-copied; if a directory structure was copied, and the given entry is just implicitly copied, this command will give you an error.
This is not folded in revert, because it's not clear whether
revert should restore the original copyfrom data or remove the copy attribute; by using a special command this is no longer ambiguous.
$ fsvs copy SourceFile DestFile
# Whoops, was wrong!
$ fsvs uncopy DestFile
fsvs diff [-v] [-r rev[:rev2]] [-R] PATH [PATH...]
This command gives you diffs between local and repository files.
-v the meta-data is additionally printed, and changes shown.
If you don't give the revision arguments, you get a diff of the base revision in the repository (the last commit) against your current local file. With one revision, you diff this repository version against you local file. With both revisions given, the difference between these repository versions is calculated.
You'll need the
diff program, as the files are simply passed as parameters to it.
The default is to do non-recursive diffs; so
fsvs diff . will output the changes in all files in the current directory.
The output for non-files is not defined.
For entries marked as copy the diff against the (clean) source entry is printed.
fsvs export REPOS_URL [-r rev]
If you want to export a directory from your repository without having to have an WAA-area, you can use this command. This restores all meta-data - owner, group, access mask and modification time. Its primary use is for data recovery.
The data gets written (in the correct directory structure) below the current working directory; if entries already exist, the export will stop, so this should be an empty directory.
This command shows general or specific help (for the given command). A similar function is available by using
-? after a command.
fsvs groups dump|load
fsvs groups [prepend|append|at=n] group-definition [group-def. ...]
fsvs ignore [prepend|append|at=n] pattern [pattern ...]
fsvs groups test [-v|-q] [pattern ...]
This command adds patterns to the end of the pattern list, or, with
prepend, puts them at the beginning of the list. With
at=x the patterns are inserted at the position
x , counting from 0.
The difference between
ignore is that the first requires a group name, whereas the latter just assumes the default group
For the specification please see the documentation Specification of groups and patterns .
fsvs dump prints the patterns to
STDOUT . If there are special characters like
LF embedded in the pattern without encoding (like
\n), the output will be garbled.
The patterns may include
? as wildcards in one directory level, or
** for arbitrary strings.
These patterns are only matched against new files; entries that are already versioned are not invalidated. If the given path matches a new directory, entries below aren't found, either; but if this directory or entries below are already versioned, the pattern doesn't work, as the match is restricted to the directory.
fsvs ignore ./tmp
tmp; but if it has already been committed, existing entries would have to be unmarked with fsvs unversion. Normally it's better to use
fsvs ignore ./tmp/**
fsvs group group:unreadable,mode:4:0
fsvs group 'group:secrets,/etc/*shadow'
fsvs ignore ./proc
fsvs ignore ./dev/pts
fsvs ignore './var/log/*-*'
fsvs ignore './**~'
fsvs ignore './**/*.bak'
fsvs ignore prepend 't./**.txt'
fsvs ignore append 't./**.svg'
fsvs ignore at=1 './**.tmp'
fsvs group dump
fsvs group dump -v
echo "./**.doc" | fsvs ignore load
To see more easily what different patterns do you can use the
testsubcommand. The following combinations are available:
fsvs groups test patternTests only the given pattern against all new entries in your working copy, and prints the matching paths. The pattern is not stored in the pattern list.
fsvs groups test
Uses the already defined pattern on the new entries, and prints the group name, a tab, and the path.
-vyou can see the matching pattern in the middle column, too.
-q you can avoid getting the long list; this makes sense if you use the group_stats option at the same time.
fsvs rel-ignore [prepend|append|at=n] path-spec [path-spec ...] fsvs ri [prepend|append|at=n] path-spec [path-spec ...]
If you use more than a single working copy for the same data, it will be stored in different paths - and that makes absolute ignore patterns infeasible. But relative ignore patterns are anchored at the beginning of the WC root - which is a bit tiring if you're deep in your WC hierarchy and want to ignore some files.
To make that easier you can use the
rel-ignore (abbreviated as
ri) command; this converts all given path-specifications (that may include wildcards as per the shell pattern specification above) to WC-relative values before storing them.
/etc as working copy root:
fsvs rel-ignore '/etc/X11/xorg.conf.*'
fsvs rel-ignore 'xorg.conf.*'
fsvs info [-R [-R]] [PATH...]
Use this command to show information regarding one or more entries in your working copy. Currently you must be at the working copy root; but that will change. You can use
-v to obtain slightly more information.
This may sometimes be helpful for locating bugs, or to obtain the URL and revision a working copy is currently at.
$ fsvs info
.... 200 .
MTime: Thu Aug 17 16:34:24 2006
CTime: Thu Aug 17 16:34:24 2006
The default is to print information about the given entry only. With a single
-R you'll get this data about all entries of a given directory; with a second
-R you'll get the whole (sub-)tree.
fsvs log [-v] [-r rev1[:rev2]] [-u name] [path]
This command views the log information associated with the given path, or, if none, the highest priority URL.
The optional rev1 and rev2 can be used to restrict the revisions that are shown; if no values are given, the logs are given starting from
HEAD downwards, and then a limit on the number of revisions is applied (but see the limit option).
If you use the -v -option, you get the files changed in each revision printed, too.
There is an option controlling the output format; see "fsvs log" output format.
Optionally the name of an URL can be given after
-u; then the log of this URL is shown.
fsvs options dump fsvs options help
load, as FSVS wouldn't know where to store the settings.
Please see options for the list of options, their values and meanings.
fsvs prop-get PROPERTY-NAME PATH...
You get the data of the property printed to STDOUT.
If you want a safe way to look at the properties, use prop-list with the
fsvs prop-set [-u URLNAME] PROPERTY-NAME VALUE PATH...
This command sets an arbitrary property value for the given path(s).
If you're using a multi-URL setup you can pin new entries to one URL with the
-u parameter; please see the add command for more details.
svn: throws a (fatal) warning, and
fsvs: is already used, too. See Special property names.
fsvs prop-del PROPERTY-NAME PATH...
This command removes property value for the given path(s).
See also prop-set.
fsvs prop-list [-v] PATH...
Lists the names of all properties for the given entry. With
-v, the value is printed as well; special characters will be translated, to not mess with your terminal.
If you need raw output, post a patch for
--raw, or loop with prop-get.
fsvs remote-status PATH [-r rev]
Per default it compares to
HEAD, but you can choose another revision with the
fsvs resolve PATH [PATH...]
When FSVS tries to update local files which have been changed, a conflict might occur. (For various ways of handling these please see the conflict option.)
This command lets you mark such conflicts as resolved.
fsvs revert [-rRev] [-R] PATH [PATH...]
This command undoes local modifications:
Please note that on implicitly copied entries (entries that are marked as copied because some parent directory is the base of a copy) cannot be un-copied; they can only be reverted to their original (copied-from) data, or removed.
See also HOWTO: Understand the entries' statii.
If a directory is given on the command line all known entries in this directory are reverted to the old state; this behaviour can be modified with -R/-N, or see below.
The reverted entries are printed, along with the status they had before the revert (because the new status is per definition unchanged).
If a revision is given, the entries' data is taken from this revision; furthermore, the new status of that entry is shown.
revert without a revision arguments gives you that.
If you find that something doesn't work as it should, you can revert entries until you are satisfied, and directly commit the new state.
In contrast, if you update to an older version, you
If you need a switch (like
rsync(1)) to remove unknown (new, not yet versioned) entries, to get the directory in the exact state it is in the repository, say so.
revert, as FSVS no longer knows about them.
TODO: If a revision is given, take a look there, and ignore the local data?
fsvs complains. We plan to provide a switch (probably
-p), which would create (a sparse) tree up to this entry.
When the user specifies a non-directory entry (file, device, symlink), this entry is reverted to the old state. This is the easy case.
If the user specifies a directory entry, see this table for the restoration results:
command line switch result
this directory only (meta-data), none this directory, and direct children of the directory,
this directory, and the complete tree below.
If an entry is marked as copied from another entry (and not committed!), a
revertwill fetch the original copyfrom source. To undo the copy setting use the uncp command.
fsvs status [-C [-C]] [-v] [PATHs...]
This command shows the entries that have changed since the last commit.
The output is formatted as follows:
-v , five) characters. There are either flags or a "." printed, so that it's easily parsed by scripts -- the number of columns is only changed by -q, -v -- verbose/quiet.
"dir" for a directory, or
"dev" for a device.
The status column can show the following flags:
-v additionally causes the
'm' -flag to be split into two, see below.
'N' are used for deleted and new entries.
'n' are used for entries which are to be unversioned or added on the next commit; the characters were chosen as little delete (only in the repository, not removed locally) and little new (although ignored). See add and unversion.
If such an entry does not exist, it is marked with an
'!' -- because it has been manually marked, and for both types removing the entry makes no sense.
'R' (replaced), ie. as removed and newly added.
If the modification or status change timestamps (mtime, ctime) are changed, but the size is still the same, the entry is marked as possibly changed (a question mark
'?' is printed) - but see change detection for details.
'm' shows meta-data changes like properties, modification timestamp and/or the rights (owner, group, mode); depending on the -v/-q command line parameters, it may be splitted into
't' (time) and
'P' is shown for the non-verbose case, it means only property changes, ie. the entries filesystem meta-data is unchanged.
'+' is printed for files with a copy-from history; to see the URL of the copyfrom source, use
'x' signifies a conflict.
Here's a table with the characters and their positions:
* Without -v With -v
* .... ......
* NmC? NtpPC?
* DPx! D x!
* R + R +
* d d
* n n
Furthermore please take a look at Status output coloring.
fsvs sync-repos [-r rev] [working copy base]
This command loads the file list from the repository. A following commit will send all differences and make the repository data identical to the local.
This is normally not needed; the use cases are
It is (currently) important if you want to backup two similar machines. Then you can commit one machine into a subdirectory of your repository, make a copy of that directory for another machine, and sync this other directory on the other machine.
A commit then will transfer only _changed_ files; so if the two machines share 2GB of binaries (
/lib , ...) then these 2GB are still shared in the repository, although over time they will deviate (as both committing machines know nothing of the other path with identical files).
This kind of backup could be substituted by several levels of repository paths, which get "overlayed" in a defined priority. So the base directory, which all machines derive from, will be committed from one machine, and it's no longer necessary for all machines to send identical files into the repository.
The revision argument should only ever be used for debugging; if you fetch a filelist for a revision, and then commit against later revisions, problems are bound to occur.
fsvs update [-r rev] [working copy base] fsvs update [-u url@rev ...] [working copy base]
This command does an update on all specified URLs for the current working copy, or, if none is given via -u, all URLs.
It first reads all changes in the repositories, overlays them (so that only the highest-priority entries are used), and fetches all necessary changes.
fsvs urls URL [URLs...] fsvs urls dump fsvs urls load
Initializes a working copy administrative area and connects
the current working directory to
REPOS_URL. All commits and updates will be done to this directory and against the given URL.
fsvs urls http://svn/repos/installation/machine-1/trunk
For a format definition of the URLs please see the chapter Format of URLs.
true | fsvs urls load
You can load a list of URLs from
STDIN; use the
loadsubcommand for that.
( echo 'N:local,prio:10,http://svn/repos/install/machine-1/trunk' ;
echo 'P:50,name:common,http://svn/repos/install/common/trunk' ) |
fsvs urls load
Empty lines are ignored.
To see which URLs are in use for the current WC, you can use
As an optional parameter you can give a format statement:
internal number for this URL
printf()-format; only these and a few
\ sequences are recognized.
fsvs urls dump " %u %n:%p\\n"
The default format is
"name:%n,prio:%p,target:%t,ro:%r,%u\\n"; for a more readable version you can use -v.
You can change the various parameters of the defined URLs like this:
SIGUSR1(to make it more verbose) or
Referenced by main().