filesync(1) User Commands filesync(1)NAMEfilesync - synchronize ordinary, directory or special files
SYNOPSISfilesync [-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 sys‐
tems, typically a server and a portable computer. 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 synchronizes 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 systems specified in the $HOME/.pack‐
ingrules file. $HOME/.packingrules is a packing rules list for filesync
and cachefspack, and contains a list of files to be kept synchronized.
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 destination system. In addi‐
tion, this form of filesync adds the file or files specified as argu‐
ments (filename) to $HOME/.packingrules. See -s and -d for information
about specifying directories on source and destination systems. See OP‐
ERANDS 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 Multi‐
ple filesync Commands.
Reconciling and Synchronizing Files
filesync synchronizes files between computer systems by performing the
following two tasks:
1. filesync examines the directories and files specified in the pack‐
ing 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 rec‐
onciliation.
2. Based on the information contained in the baseline file and the
specified options (see Resolving filesync Conflicts), 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 sys‐
tem. 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 automati‐
cally determine which version should be selected, it prints out a warn‐
ing message and leaves the two incompatible versions of the file unrec‐
onciled.
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 ver‐
sions, determine which one should be kept, and manually bring the two
versions into agreement (by copying, deleting, or changing the owner‐
ship 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 pack‐
ingrules(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 per‐
manently 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 differ‐
ences between files during the reconciliation 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 agree‐
ment 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 pertain‐
ing to only a few active projects on your notebook. If you continue to
keep files associated with every project you have ever worked on syn‐
chronized, 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 per‐
form the corresponding deletes on the server, which would not be what
you wanted. Rather, you would like a way to tell filesync to stop syn‐
chronizing 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/.pack‐
ingrules. For major changes it is probably 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 variable does not normally point to a directory on your
notebook, 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 baseline 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 possi‐
ble to set the ACL for a particular file, filesync stops ACL syn‐
chronization for that file.
Some file systems do not support ACLs . It is not possible to syn‐
chronize 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 file‐
name operand. See -s and OPERANDS.
-e
Flag all differences. It may not be possible to resolve all con‐
flicts involving modes and ownership (unless filesync is being run
with root privileges). If you cannot change the ownership or pro‐
tections on a file, filesync will normally ignore conflicts in own‐
ership and protection. If you specify the -e (everything must
agree) flag, however, filesync will flag these differences.
-f src | dst | old | new
The -f option tells filesync how to resolve conflicting changes. If
a file has been changed on both systems, 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 ver‐
sion 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 con‐
tinues, 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 modification times so that the propagated files have the
same relative modification time ordering as the original changes.
Users should be warned that there is usually some time skew between
any two systems, and transferring modification times from one sys‐
tem 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 keeping .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 version 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 pack‐
ing 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, favoring either the
source system (src) or destination system (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 destina‐
tion directory.
Specify -o dst to propagate changes only from the destination sys‐
tem to the source system. Changes made on the source system are
ignored. filesync aborts if it cannot access a source or destina‐
tion 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 recon‐
ciliation action as it is performed.
The standard filesync message describes each reconciliation 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 multiple directo‐
ries 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 comparison as it is
made on the standard output.
-y
Bypass safety check prompts. Nomadic machines occasionally 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 inap‐
propriate copies and deletions. To prevent such a mishap, filesync
performs a few safety checks prior to reconciliation. If large num‐
bers of files are likely to be deleted, or if high level directo‐
ries have changed their I-node numbers, filesync prompts for a
confirmation before reconciliation. If you know that this is
likely, and do not want to be prompted, use the -y (yes) option to
automatically 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 directory
(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 direc‐
tory (dest-dir).
If filename is a symbolic link, a copy of that sym‐
bolic link will be replicated in the specified destina‐
tion 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 characters,
the wildcard characters are stored in $HOME/.pack‐
ingrules and evaluated each time filesync is run.
For example, the following would make sure that the two
specified files, currently in $RHOME, were replicated
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 mes‐
sages 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. How‐
ever, if either the -n option was specified 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 attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Availability │SUNWrcmdc │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOcachefspack(1M), packingrules(4), attributes(5)SunOS 5.10 6 Nov 2000 filesync(1)