filesync(1)
NAME
filesync - synchronize ordinary, directory or special files
SYNOPSIS
filesync [-aehmnqvy] [-o src | dst] [-f src | dst | old |
new] [-r directory...]
filesync [-aehmnqvy] -s source-dir -d dest-dir filename...
DESCRIPTION
The filesync utility synchronizes files between multiple
computer systems, typically a server and a portable com-
puter. filesync synchronizes ordinary, directory or special
files. Although intended for use on nomadic systems,
filesync is useful for backup and file replication on more
permanently connected systems.
If files are synchronized between systems, the corresponding
files on each of the systems are identical. Changing a file
on one or both of the systems causes the files to become
different (not synchronized). In order to make the files
identical again, the differences between the files must be
reconciled. See Reconciling and Synchronizing Files for
specific details about how filesync reconciles and synchron-
izes files.
There are two forms of the filesync command. The first form
of filesync is invoked without file arguments. This form of
filesync reconciles differences between the files and sys-
tems specified in the $HOME/.packingrules file.
$HOME/.packingrules is a packing rules list for filesync and
cachefspack, and contains a list of files to be kept syn-
chronized. See packingrules(4) and cachefspack(1M).
The second form of filesync copies specific files from a
directory on the source system to a directory on the desti-
nation system. In addition, this form of filesync adds the
file or files specified as arguments (filename) to
$HOME/.packingrules. See -s and -d for information about
specifying directories on source and destination systems.
See OPERANDS for details about specifying file (filename)
arguments.
Multiple filesync commands are cumulative (that is, the
specified files are added to the already existing packing
rules file list). See Multiple filesync Commands.
Reconciling and Synchronizing Files
filesync synchronizes files between computer systems by per-
forming the following two tasks:
1. filesync examines the directories and files specified in
the packing rules file on both systems, and determines
whether or not they are identical. Any file that differs
requires reconciliation.
filesync also maintains a baseline summary in the
$HOME/.filesync-base file for all of the files that are
being monitored. This file lists the names, types, and
sizes of all files as of the last reconciliation.
2. Based on the information contained in the baseline file
and the specified options (see Resolving filesync Con-
flicts), filesync determines which of the various copies
is the correct one, and makes the corresponding changes
to the other system. Once this has been done, the two
copies are, again, identical (synchronized).
If a source file has changed and the destination file has
not, the changes on the source system are propagated to
the destination system. If a destination file has changed
and the corresponding source file has not, the changes on
the destination file are propagated to the source system.
If both systems have changed (and the files are not still
identical) a warning message will be printed out, asking
the user to resolve the conflict manually. See Resolving
filesync Conflicts.
Resolving filesync Conflicts
In cases where files on both sides have changed, filesync
attempts to determine which version should be chosen. If
filesync cannot automatically determine which version should
be selected, it prints out a warning message and leaves the
two incompatible versions of the file unreconciled.
In these cases, you must either resolve the differences
manually, or tell filesync how to choose which file should
win. Use the -o and -f options to tell filesync how to
resolve conflicts (see OPTIONS).
Alternatively, for each conflicting file, you can examine
the two versions, determine which one should be kept, and
manually bring the two versions into agreement (by copying,
deleting, or changing the ownership or protection to be
correct). You can then re-run filesync to see whether or
not any other conflicts remain.
Packing Rules File
The packing rules file $HOME/.packingrules contains a list
of files to be kept synchronized. The syntax of this file is
described in packingrules(4).
The $HOME/.packingrules file is automatically created if
users invoke filesync with filename arguments. By using
filesync options, users
can augment the packing rules in $HOME/.packingrules.
Many users choose to create the packing rules file manually
and edit it by hand. Users can edit $HOME/.packingrules
(using any editor) to permanently change the
$HOME/.packingrules file, or to gain access to more powerful
options that are not available from the command line (such
as IGNORE commands). It is much easier to enter complex
wildcard expressions by editing the $HOME/.packingrules
file.
Baseline File
$HOME/.filesync-base is the filesync baseline summary file.
filesync uses the information in $HOME/.filesync-base to
identify the differences between files during the reconcili-
ation and synchronization process. Users do not create or
edit the baseline file. It is created automatically by
filesync and records the last known state of agreement
between all of the files being maintained.
Multiple filesync Commands
Over a period of time, the set of files you want to keep
synchronized can change. It is common, for instance, to want
to keep files pertaining to only a few active projects on
your notebook. If you continue to keep files associated with
every project you have ever worked on synchronized, your
notebook's disk will fill up with old files. Each filesync
command will waste a lot of time updating files you no
longer care about.
If you delete the files from your notebook, filesync will
want to perform the corresponding deletes on the server,
which would not be what you wanted. Rather, you would like a
way to tell filesync to stop synchronizing some of the
files. There are two ways to do this:
1. Edit $HOME/.packingrules. Delete the rules for the files
that you want to delete.
2. Delete $HOME/.packingrules. Use the filesync command to
specify the files that you want synchronized.
Either way works, and you can choose the one that seems
easiest to you. For minor changes, it is probably easier to
just edit $HOME/.packingrules. For major changes it is prob-
ably easier to start from scratch.
Once filesync is no longer synchronizing a set of files,
you can delete them from your notebook without having any
effect on the server.
Nomadic Machines
When using filesync to keep files synchronized between
nomadic machines and a server, store the packing rules and
baseline files on the nomadic machines, not the server. If,
when logged into your notebook, the HOME environment vari-
able does not normally point to a directory on your note-
book, you can use the FILESYNC environment variable to
specify an alternate location for the packing rules and
baseline files.
Each nomadic machine should carry its own packing rules and
baseline file. Incorrect file synchronization can result if
a server carries a baseline file and multiple nomadic
machines attempt to reconcile against the server's baseline
file. In this case, a nomadic machine could be using a base-
line file that does not accurately describe the state of its
files. This might result in incorrect reconciliations.
To safeguard against the dangers associated with a single
baseline file being shared by more than two machines,
filesync adds a default rule to each new packing rules file.
This default rule prevents the packing rules and baseline
files from being copied.
OPTIONS
The following options are supported:
-a Force the checking of Access Control Lists (ACLs )
and attempt to make them agree for all new and changed
files. If it is not possible to set the ACL for a par-
ticular file, filesync stops ACL synchronization for
that file.
Some file systems do not support ACLs . It is not pos-
sible to synchronize ACLs between file systems that
support ACLs and those that do not; attempting to do
so will result in numerous error messages.
-d dest-dir
Specify the directory on the destination system into
which filename is to be copied. Use with the -s
source-dir option and the filename operand. See -s and
OPERANDS.
-e Flag all differences. It may not be possible to
resolve all conflicts involving modes and ownership
(unless filesync is being run with root privileges).
If you cannot change the ownership or protections on a
file, filesync will normally ignore conflicts in own-
ership and protection. If you specify the -e (every-
thing must agree) flag, however, filesync will flag
these differences.
-f src | dst | old | new
The -f option tells filesync how to resolve conflict-
ing changes. If a file has been changed on both sys-
tems, and an -f option has been specified, filesync
will retain the changes made on the favored system and
discard the changes made on the unfavored system.
Specify -f src to favor the source-system file.
Specify -f dst to favor the destination-system file.
Specify -f old to favor the older version of the file.
Specify -f new to favor the newer version of the file.
It is possible to specify the -f and -o options in
combination if they both specify the same preference
(src and dst). If
-f and -o conflict, the -f option is ignored. See
the -o option description.
-h Halt on error. Normally, if filesync encounters a read
or write error while copying files, it notes the error
and the program continues, in an attempt to reconcile
other files. If the -h option is specified, filesync
will immediately halt when one of these errors occurs
and will not try to process any more files.
-m Ensure that both copies of the file have the same
modification time. The modification time for newly
copied files is set to the time of reconciliation by
default. File changes are ordered by increasing modif-
ication times so that the propagated files have the
same relative modification time ordering as the origi-
nal changes. Users should be warned that there is usu-
ally some time skew between any two systems, and
transferring modification times from one system to
another can occasionally produce strange results.
There are instances in which using filesync to update
some (but not all) files in a directory will confuse
the make program. If, for instance, filesync is keep-
ing .c files synchronized, but ignoring .o files, a
changed .c file may show up with a modification time
prior to a .o file that was built from a prior ver-
sion of the .c file.
-n Do not really make the changes. If the -n option is
specified, filesync determines what changes have been
made to files, and what reconciliations are required
and displays this information on the standard output.
No changes are made to files, including the packing
rules file.
Specifying both the -n and -o options causes filesync
to analyze the prevailing system and report the
changes that have been made on that system. Using -n
and -o in combination is useful if your machine is
disconnected (and you cannot access the server) but
you want to know what changes have been made on the
local machine. See the -o option description.
-o src | dst
The -o option forces a one-way reconciliation, favor-
ing either the source system (src) or destination sys-
tem (dst).
Specify -o src to propagate changes only from the
source system to the destination system. Changes made
on the destination system are ignored. filesync aborts
if it cannot access a source or destination directory.
Specify -o dst to propagate changes only from the des-
tination system to the source system. Changes made on
the source system are ignored. filesync aborts if it
cannot access a source or destination directory.
Specifying -n with the -o option causes filesync to
analyze the prevailing system and reports on what
changes have been made on that system. Using -n and -o
in combination is useful if a machine is disconnected
(and there is no access to the server), but you want
to know what changes have been made on the local
machine. See the -n option description.
It is possible to specify the -o and -f options in
combination if they both specify the same preference
(src or dst). If -o and -f options conflict, the -f
option will be ignored. See the -f option description.
-q Suppress the standard filesync messages that describe
each reconciliation action as it is performed.
The standard filesync message describes each reconcil-
iation action in the form of a UNIX shell command (for
example, mv, ln, cp, rm, chmod, chown, chgrp, setfacl,
and so forth).
-r directory
Limit the reconciliation to directory. Specify multi-
ple directories with multiple -r specifications.
-s source-dir
Specify the directory on the source system from which
the filename to be copied is located. Use with the
-d dest-dir option and the filename operand. See the
-d option description and OPERANDS.
-v Display additional information about each file com-
parison as it is made on the standard output.
-y Bypass safety check prompts. Nomadic machines occa-
sionally move between domains, and many of the files
on which filesync operates are expected to be accessed
by NFS. There is a danger that someday filesync will
be asked to reconcile local changes against the wrong
file system or server. This could result in a large
number of inappropriate copies and deletions. To
prevent such a mishap, filesync performs a few safety
checks prior to reconciliation. If large numbers of
files are likely to be deleted, or if high level
directories have changed their I-node numbers,
filesync prompts for a confirmation before reconcilia-
tion. If you know that this is likely, and do not want
to be prompted, use the -y (yes) option to automati-
cally confirm these prompts.
OPERANDS
The following operands are supported:
filename
The name of the ordinary file, directory, symbolic
link, or special file in the specified source direc-
tory (source-dir) to be synchronized. Specify multiple
files by separating each filename by spaces. Use the
filename operand with the -s and -d options. See
OPTIONS.
If filename is an ordinary file, that ordinary file
will be replicated (with the same filename) in the
specified destination directory (dest-dir).
If filename is a directory, that directory and all of
the files and subdirectories under it will be repli-
cated (recursively) in the specified destination
directory (dest-dir).
If filename is a symbolic link, a copy of that sym-
bolic link will be replicated in the specified desti-
nation directory (dest-dir).
If filename is a special file, a special file with the
same major or minor device numbers will be replicated
in the specified destination directory. (dest-dir).
Only super-users can use filesync to create special
files.
Files created in the destination directory (dest-dir)
will have the same owner, group and other permissions
as the files in the source directory.
If filename contains escaped shell wildcard charac-
ters, the wildcard characters are stored in
$HOME/.packingrules and evaluated each time filesync
is run.
For example, the following would make sure that the
two specified files, currently in $RHOME, were repli-
cated in $HOME:
filesync -s $RHOME -d $HOME a.c b.c
The following example would ensure that all of the *.c
files in $RHOME were replicated in $HOME, even if
those files were not created until later.
filesync -s $RHOME -d $HOME '*.c'
If any of the destination files already exist,
filesync ensures that they are identical and issues
warnings if they are not.
Once files have been copied, the distinction between
the source and destination is a relatively arbitrary
one (except for its use in the -o and -f switches).
ENVIRONMENT VARIABLES
FILESYNC
Specifies the default location of the filesync packing
rules and baseline files. The default value for this
variable is $HOME. The suffixes .packingrules and
.filesync-base will be appended to form the names of
the packing rules and baseline files.
LC_MESSAGES
Determines how diagnostic and informative messages are
presented. In the "C" locale, the messages are
presented in the default form found in the program
itself (in most cases, U.S. English).
EXIT STATUS
Normally, if all files are already up-to-date, or if all
files were successfully reconciled, filesync will exit with
a status of 0. However, if either the -n option was speci-
fied or any errors occurred, the exit status will be the
logical OR of the following:
0 No conflicts, all files up to date.
1 Some resolvable conflicts.
2 Some conflicts requiring manual resolution.
4 Some specified files did not exist.
8 Insufficient permission for some files.
16 Errors accessing packing rules or baseline file.
32 Invalid arguments.
64 Unable to access either or both of the specified src
or dst directories.
128 Miscellaneous other failures.
FILES
$HOME/.packingrules
list of files to be kept synchronized
$HOME/.filesync-base
baseline summary file
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWrcmdc |
|_____________________________|_____________________________|
SEE ALSO
cachefspack(1M), packingrules(4), attributes(5)
Man(1) output converted with
man2html