Tribblix: manual page: filesync.1

FILESYNC(1) 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 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/.packingrules file. $HOME/.packingrules is a packing rules list
for filesync and contains a list of files to be kept synchronized.
See packingrules(5).

The second form of filesync copies specific files from a directory on
the source system to a directory on the destination 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 performing
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
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 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(5).

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 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 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 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 possible to set the ACL for a
particular file, filesync stops ACL
synchronization for that file.

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 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 ownership 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 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 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
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 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 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, 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 destination
directory.

Specify -o dst to propagate changes only
from the destination 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 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 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 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 replicated
(recursively) in the specified destination directory
(dest-dir).

If filename is a symbolic link, a copy of that symbolic
link will be replicated in the specified destination
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/.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 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 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