User Commands 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.
SunOS 5.11 Last change: 6 Nov 2000 1
User Commands filesync(1)
Reconciling and Synchronizing Files
filesync synchronizes files between computer systems by per-
forming the following two tasks:
1. filesync examines the directories and files speci-
fied 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 recon-
ciliation.
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 system. If a destina-
tion file has changed and the corresponding source
file has not, the changes on the destination file
are propagated to the source system. If both sys-
tems 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
SunOS 5.11 Last change: 6 Nov 2000 2
User Commands filesync(1)
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.
SunOS 5.11 Last change: 6 Nov 2000 3
User Commands filesync(1)
2. Delete $HOME/.packingrules. Use the filesync com-
mand to specify the files that you want synchron-
ized.
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 particular file, filesync
stops ACL synchronization for
that file.
SunOS 5.11 Last change: 6 Nov 2000 4
User Commands filesync(1)
Some file systems do not support
ACLs . It is not possible 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 con-
flicts involving modes and own-
ership (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 ownership and pro-
tection. 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 version of the file.
It is possible to specify the
-f and -o options in
SunOS 5.11 Last change: 6 Nov 2000 5
User Commands filesync(1)
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 pro-
gram 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 modifica-
tion times so that the pro-
pagated files have the same
relative modification time ord-
ering 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 system to another can
occasionally produce strange
results.
There are instances in which
using filesync to update some
(but not all) files in a direc-
tory will confuse the make pro-
gram. If, for instance, filesync
is keeping .c files synchron-
ized, 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.
SunOS 5.11 Last change: 6 Nov 2000 6
User Commands filesync(1)
-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 out-
put. 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 use-
ful if your machine is discon-
nected (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 des-
tination system (dst).
Specify -o src to propagate
changes only from the source
system to the destination sys-
tem. Changes made on the desti-
nation system are ignored.
filesync aborts if it cannot
access a source or destination
directory.
Specify -o dst to propagate
changes only from the destina-
tion system to the source sys-
tem. 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
SunOS 5.11 Last change: 6 Nov 2000 7
User Commands filesync(1)
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 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
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 comparison as it
is made on the standard output.
-y Bypass safety check prompts.
Nomadic machines occasionally
SunOS 5.11 Last change: 6 Nov 2000 8
User Commands filesync(1)
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 dele-
tions. 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 confirma-
tion 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, sym-
bolic link, or special file in the specified
source directory (source-dir) to be synchron-
ized. 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 replicated (recursively) in the speci-
fied destination directory (dest-dir).
If filename is a symbolic link, a copy of that
symbolic link will be replicated in the speci-
fied destination directory (dest-dir).
If filename is a special file, a special file
with the same major or minor device numbers will
SunOS 5.11 Last change: 6 Nov 2000 9
User Commands filesync(1)
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/.packingrules 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 rela-
tively 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.
LCMESAGES 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
SunOS 5.11 Last change: 6 Nov 2000 10
User Commands filesync(1)
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 synchron-
ized
$HOME/.filesync-base baseline summary file
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 6 Nov 2000 11
User Commands filesync(1)
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWrcmdc
SEE ALSO
cachefspack(1M), packingrules(4), attributes(5)
SunOS 5.11 Last change: 6 Nov 2000 12
|
