1 FILESYNC(1)                      User Commands                     FILESYNC(1)
   2 
   3 
   4 
   5 NAME
   6        filesync - synchronize ordinary, directory or special files
   7 
   8 SYNOPSIS
   9        filesync [-aehmnqvy] [-o src | dst]
  10             [-f src | dst | old | new] [-r directory]...
  11 
  12 
  13        filesync [-aehmnqvy] -s source-dir -d dest-dir filename...
  14 
  15 
  16 DESCRIPTION
  17        The filesync utility synchronizes files between multiple computer
  18        systems, typically a server and a portable computer. filesync
  19        synchronizes ordinary, directory or special files. Although intended
  20        for use on nomadic systems, filesync is useful for backup and file
  21        replication on more permanently connected systems.
  22 
  23 
  24        If files are synchronized between systems, the corresponding files on
  25        each of the systems are identical. Changing a file on one or both of
  26        the systems causes the files to become different (not synchronized). In
  27        order to make the files identical again, the differences between the
  28        files must be reconciled. See Reconciling and Synchronizing Files  for
  29        specific details about how filesync reconciles and synchronizes files.
  30 
  31 
  32        There are two forms of the filesync command. The first form of filesync
  33        is invoked without file arguments. This form of filesync reconciles
  34        differences between the files and systems specified in the
  35        $HOME/.packingrules file. $HOME/.packingrules is a packing rules list
  36        for filesync and contains a list of files to be kept synchronized. See
  37        packingrules(4).
  38 
  39 
  40        The second form of filesync copies specific files from a directory on
  41        the source system to a directory on the destination system. In
  42        addition, this form of filesync adds the file or files specified as
  43        arguments (filename) to $HOME/.packingrules. See -s and -d for
  44        information about specifying directories on source and destination
  45        systems. See OPERANDS for details about specifying file (filename)
  46        arguments.
  47 
  48 
  49        Multiple filesync commands are cumulative (that is, the specified files
  50        are added to the already existing packing rules file list). See
  51        Multiple filesync Commands.
  52 
  53    Reconciling and Synchronizing Files
  54        filesync synchronizes files between computer systems by performing the
  55        following two tasks:
  56 
  57            1.     filesync examines the directories and files specified in the
  58                   packing rules file on both systems, and determines whether
  59                   or not they are identical.  Any file that differs requires
  60                   reconciliation.
  61 
  62                   filesync also maintains a baseline summary in the
  63                   $HOME/.filesync-base file for all of the files that are being
  64                   monitored.  This file lists the names, types, and sizes of
  65                   all files as of the last reconciliation.
  66 
  67            2.     Based on the information contained in the baseline file and
  68                   the specified options (see  Resolving filesync Conflicts),
  69                   filesync determines which of the various copies is the
  70                   correct one, and makes the corresponding changes to the
  71                   other system. Once this has been done, the two copies are,
  72                   again, identical (synchronized).
  73 
  74                   If a source file has changed and the destination file has
  75                   not, the changes on the source system are propagated to the
  76                   destination system. If a destination file has changed and
  77                   the corresponding source file has not, the changes on the
  78                   destination file are propagated to the source system. If
  79                   both systems have changed (and the files are not still
  80                   identical) a warning message will be printed out, asking the
  81                   user to resolve the conflict manually. See Resolving
  82                   filesync Conflicts.
  83 
  84    Resolving filesync Conflicts
  85        In cases where files on both sides have changed,  filesync attempts to
  86        determine which version should be chosen. If  filesync cannot
  87        automatically determine which version should be selected, it prints out
  88        a warning message and leaves the two incompatible versions of the file
  89        unreconciled.
  90 
  91 
  92        In these cases, you must either resolve the differences manually, or
  93        tell filesync how to choose which file should win. Use the  -o and -f
  94        options to tell  filesync how to resolve conflicts (see OPTIONS).
  95 
  96 
  97        Alternatively, for each conflicting file, you can examine the two
  98        versions, determine which one should be kept, and manually bring the
  99        two versions into agreement (by copying, deleting, or changing the
 100        ownership or protection to be correct). You can then re-run  filesync to
 101        see whether or not any other conflicts remain.
 102 
 103    Packing Rules File
 104        The packing rules file $HOME/.packingrules contains a list of files to
 105        be kept synchronized. The syntax of this file is described in
 106        packingrules(4).
 107 
 108 
 109        The $HOME/.packingrules file is automatically created if users invoke
 110        filesync with filename arguments. By using filesync options, users can
 111        augment the packing rules in $HOME/.packingrules.
 112 
 113 
 114        Many users choose to create the packing rules file manually and edit it
 115        by hand. Users can edit $HOME/.packingrules (using any editor) to
 116        permanently change the  $HOME/.packingrules file, or to gain access to
 117        more powerful options  that are not available from the command line
 118        (such as IGNORE commands). It is much easier to enter complex wildcard
 119        expressions by editing the $HOME/.packingrules file.
 120 
 121    Baseline File
 122        $HOME/.filesync-base is the filesync baseline summary file.  filesync
 123        uses the information in $HOME/.filesync-base to identify the differences
 124        between files during the reconciliation and synchronization process.
 125        Users do not create or edit the baseline file. It is created
 126        automatically by filesync and records the last known state of
 127        agreement between all of the files being maintained.
 128 
 129    Multiple filesync Commands
 130        Over a period of time, the set of files you want to keep synchronized
 131        can change. It is common, for instance, to want to keep files
 132        pertaining to only a few active projects on your notebook. If you
 133        continue to keep files associated with every project you have ever
 134        worked on synchronized, your notebook's disk will fill up with old
 135        files. Each  filesync command will waste a lot of time updating files
 136        you no longer care about.
 137 
 138 
 139        If you delete the files from your notebook, filesync will want to
 140        perform the corresponding deletes on the server, which would not be
 141        what you wanted.  Rather, you would like a way to tell filesync to stop
 142        synchronizing some of the files. There are two ways to do this:
 143 
 144            1.     Edit  $HOME/.packingrules. Delete the rules for the files
 145                   that you want to delete.
 146 
 147            2.     Delete $HOME/.packingrules. Use the  filesync command to
 148                   specify the files that you want synchronized.
 149 
 150 
 151        Either way works, and you can choose the one that seems easiest to you.
 152        For minor changes, it is probably easier to just edit
 153        $HOME/.packingrules.  For major changes it is probably easier to start
 154        from scratch.
 155 
 156 
 157        Once  filesync is no longer synchronizing a set of files, you can
 158        delete them from your notebook without having any effect on the server.
 159 
 160    Nomadic Machines
 161        When using filesync to keep files synchronized between nomadic machines
 162        and a server, store the packing rules and baseline files on the nomadic
 163        machines, not the server. If, when logged into your notebook, the HOME
 164        environment variable does not normally point to a directory on your
 165        notebook, you can use the FILESYNC environment variable to specify an
 166        alternate location for the packing rules and baseline files.
 167 
 168 
 169        Each nomadic machine should carry its own packing rules and baseline
 170        file.  Incorrect file synchronization can result if a server carries a
 171        baseline file and multiple nomadic machines attempt to reconcile
 172        against the server's baseline file. In this case, a nomadic machine
 173        could be using a baseline file that does not accurately describe the
 174        state of its files. This might result in incorrect reconciliations.
 175 
 176 
 177        To safeguard against the dangers associated with a single  baseline
 178        file being shared by more than two machines,  filesync adds a default
 179        rule to each new packing rules file. This default rule prevents the
 180        packing rules and baseline files from being copied.
 181 
 182 OPTIONS
 183        The following options are supported:
 184 
 185        -a
 186                                    Force the checking of Access Control Lists
 187                                    (ACLs )  and attempt to make them agree for
 188                                    all new and changed files. If it is not
 189                                    possible to set the ACL for a particular
 190                                    file, filesync stops ACL synchronization
 191                                    for that file.
 192 
 193                                    Some file systems do not support ACLs . It
 194                                    is not possible to synchronize ACLs between
 195                                    file systems that support ACLs and those
 196                                    that do not; attempting to do so will
 197                                    result in numerous error messages.
 198 
 199 
 200        -d dest-dir
 201                                    Specify the directory on the destination
 202                                    system into which filename is to be copied.
 203                                    Use with the -s source-dir option and the
 204                                    filename operand. See -s and  OPERANDS.
 205 
 206 
 207        -e
 208                                    Flag all differences. It may not be
 209                                    possible to resolve all conflicts involving
 210                                    modes and ownership (unless filesync is
 211                                    being run with root privileges).  If you
 212                                    cannot change the ownership or protections
 213                                    on a file, filesync will normally ignore
 214                                    conflicts in ownership and protection. If
 215                                    you specify the -e (everything must agree)
 216                                    flag, however, filesync will flag these
 217                                    differences.
 218 
 219 
 220        -f src | dst | old | new
 221                                    The -f option tells filesync how to resolve
 222                                    conflicting changes. If a file has been
 223                                    changed on both systems, and an -f option
 224                                    has been specified, filesync will retain
 225                                    the changes made on the favored system and
 226                                    discard the changes made on the unfavored
 227                                    system.
 228 
 229                                    Specify -f src to favor the  source-system
 230                                    file. Specify -f dst to favor the
 231                                    destination-system file. Specify -f old to
 232                                    favor the older version of the file.
 233                                    Specify -f new to favor the newer version of
 234                                    the file.
 235 
 236                                    It is possible to specify the  -f and  -o
 237                                    options in combination if they both specify
 238                                    the same preference  (src and dst). If -f
 239                                    and  -o conflict, the  -f option is ignored.
 240                                    See the -o option description.
 241 
 242 
 243        -h
 244                                    Halt on error. Normally, if filesync
 245                                    encounters a read or write error while
 246                                    copying files, it notes the error and the
 247                                    program continues, in an attempt to
 248                                    reconcile other files. If the -h option is
 249                                    specified, filesync will immediately halt
 250                                    when one of these errors occurs and will
 251                                    not try to process any more files.
 252 
 253 
 254        -m
 255                                    Ensure that both copies of the file have
 256                                    the same modification time. The
 257                                    modification time for newly copied files is
 258                                    set to the time of reconciliation by
 259                                    default. File changes are ordered by
 260                                    increasing modification times so that the
 261                                    propagated files have the same relative
 262                                    modification time ordering as the original
 263                                    changes. Users should be warned that there
 264                                    is usually some time skew between  any two
 265                                    systems, and transferring modification
 266                                    times from one system to another can
 267                                    occasionally produce strange results.
 268 
 269                                    There are instances in which using filesync
 270                                    to update some (but not all) files in a
 271                                    directory will confuse the  make program.
 272                                    If, for instance, filesync is keeping  .c
 273                                    files synchronized, but ignoring .o files,
 274                                    a changed  .c file may show up with a
 275                                    modification time prior to a  .o file that
 276                                    was built from a prior version of the .c
 277                                    file.
 278 
 279 
 280        -n
 281                                    Do not really make the changes. If the  -n
 282                                    option is specified, filesync determines
 283                                    what changes have been made to files, and
 284                                    what reconciliations are required and
 285                                    displays this information on the standard
 286                                    output. No changes are made to files,
 287                                    including the packing rules file.
 288 
 289                                    Specifying both the -n and -o options causes
 290                                    filesync to analyze the prevailing system
 291                                    and report the changes that have been made
 292                                    on that system. Using -n and -o in
 293                                    combination is useful if your machine is
 294                                    disconnected (and you cannot access the
 295                                    server) but you want to know what changes
 296                                    have been made on the local machine. See
 297                                    the -o option description.
 298 
 299 
 300        -o src | dst
 301                                    The -o option forces a one-way
 302                                    reconciliation, favoring either the source
 303                                    system (src) or destination system (dst).
 304 
 305                                    Specify -o src to propagate changes only
 306                                    from the source system to the destination
 307                                    system. Changes made on the destination
 308                                    system are ignored.  filesync aborts if it
 309                                    cannot access a source or destination
 310                                    directory.
 311 
 312                                    Specify -o dst to propagate changes only
 313                                    from the destination system to the source
 314                                    system. Changes made on the source system
 315                                    are ignored.  filesync aborts if it cannot
 316                                    access a source or destination directory.
 317 
 318                                    Specifying -n with the -o option causes
 319                                    filesync to analyze the prevailing system
 320                                    and reports on what changes have been made
 321                                    on that system. Using -n and -o in
 322                                    combination is useful if a machine is
 323                                    disconnected (and there is no access to the
 324                                    server), but you want to know what changes
 325                                    have been made on the local machine. See
 326                                    the -n option description.
 327 
 328                                    It is possible to specify the -o and -f
 329                                    options in combination if they both specify
 330                                    the same preference (src or dst). If -o and
 331                                    -f options conflict, the -f option will be
 332                                    ignored. See the -f option description.
 333 
 334 
 335        -q
 336                                    Suppress the standard filesync messages
 337                                    that describe each reconciliation action as
 338                                    it is performed.
 339 
 340                                    The standard filesync message describes
 341                                    each reconciliation action in the form of a
 342                                    UNIX shell command (for example, mv, ln,
 343                                    cp, rm, chmod, chown, chgrp, setfacl, and
 344                                    so forth).
 345 
 346 
 347        -r directory
 348                                    Limit the reconciliation to  directory.
 349                                    Specify multiple directories with multiple
 350                                    -r specifications.
 351 
 352 
 353        -s source-dir
 354                                    Specify the directory on the source system
 355                                    from which the  filename to be copied is
 356                                    located. Use with the  -d dest-dir option and
 357                                    the filename operand. See the -d option
 358                                    description and OPERANDS.
 359 
 360 
 361        -v
 362                                    Display additional information about each
 363                                    file comparison as it is made on the
 364                                    standard output.
 365 
 366 
 367        -y
 368                                    Bypass safety check prompts. Nomadic
 369                                    machines occasionally move between domains,
 370                                    and many of the files on which filesync
 371                                    operates are expected to be accessed by
 372                                    NFS. There is a danger that someday
 373                                    filesync will be asked to reconcile local
 374                                    changes against the wrong file system or
 375                                    server. This could result in a large number
 376                                    of inappropriate copies and deletions. To
 377                                    prevent such a mishap,  filesync performs a
 378                                    few safety checks prior to reconciliation.
 379                                    If large numbers of files are likely to  be
 380                                    deleted, or if high level directories have
 381                                    changed their I-node numbers,  filesync
 382                                    prompts for a confirmation before
 383                                    reconciliation. If you know that this is
 384                                    likely, and do not want to be prompted, use
 385                                    the -y (yes) option to automatically confirm
 386                                    these prompts.
 387 
 388 
 389 OPERANDS
 390        The following operands are supported:
 391 
 392        filename
 393                    The name of the ordinary file, directory, symbolic link, or
 394                    special file in the specified source directory (source-dir)
 395                    to be synchronized. Specify multiple files by separating
 396                    each filename by spaces. Use the filename operand with the
 397                    -s and -d options. See  OPTIONS.
 398 
 399                    If filename is an ordinary file, that ordinary file will be
 400                    replicated (with the same filename) in the specified
 401                    destination directory (dest-dir).
 402 
 403                    If filename is a directory, that directory and all of the
 404                    files and subdirectories under it will be replicated
 405                    (recursively) in the specified destination directory (dest-
 406                    dir).
 407 
 408                    If  filename is a symbolic link, a copy of that symbolic
 409                    link will be replicated in the specified destination
 410                    directory (dest-dir).
 411 
 412                    If filename is a special file, a special file with the same
 413                    major or minor device numbers will be replicated in the
 414                    specified destination directory.  (dest-dir). Only super-
 415                    users can use filesync to create special files.
 416 
 417                    Files created in the destination directory (dest-dir) will
 418                    have the same owner, group and other permissions as the
 419                    files in the source directory.
 420 
 421                    If filename contains escaped shell wildcard characters, the
 422                    wildcard characters are stored in $HOME/.packingrules and
 423                    evaluated each time filesync is run.
 424 
 425                    For example, the following would make sure that the two
 426                    specified files, currently in $RHOME, were replicated in
 427                    $HOME:
 428 
 429                      filesync -s $RHOME  -d $HOME a.c b.c
 430 
 431 
 432                    The following example would ensure that all of the *.c
 433                    files in $RHOME were replicated in  $HOME, even if those
 434                    files were not created until later.
 435 
 436                      filesync -s $RHOME -d $HOME '*.c'
 437 
 438 
 439                    If any of the destination files already exist,  filesync
 440                    ensures that they are identical and issues warnings if they
 441                    are not.
 442 
 443                    Once files have been copied, the distinction between the
 444                    source and destination is a relatively arbitrary  one
 445                    (except for its use in the -o and -f switches).
 446 
 447 
 448 ENVIRONMENT VARIABLES
 449        FILESYNC
 450                       Specifies the default location of the filesync packing
 451                       rules and baseline files. The default value for this
 452                       variable is $HOME. The suffixes .packingrules and
 453                       .filesync-base will be appended to form the names of the
 454                       packing rules and baseline files.
 455 
 456 
 457        LC_MESSAGES
 458                       Determines how diagnostic and informative messages are
 459                       presented. In the "C" locale, the messages are presented
 460                       in the default form found in the program itself (in most
 461                       cases, U.S. English).
 462 
 463 
 464 EXIT STATUS
 465        Normally, if all files are already up-to-date, or if all files were
 466        successfully reconciled, filesync will exit with a status of 0.
 467        However, if either the -n option was specified or any errors occurred,
 468        the exit status will be the logical OR of the following:
 469 
 470        0
 471               No conflicts, all files up to date.
 472 
 473 
 474        1
 475               Some resolvable conflicts.
 476 
 477 
 478        2
 479               Some conflicts requiring manual resolution.
 480 
 481 
 482        4
 483               Some specified files did not exist.
 484 
 485 
 486        8
 487               Insufficient permission for some files.
 488 
 489 
 490        16
 491               Errors accessing packing rules or baseline file.
 492 
 493 
 494        32
 495               Invalid arguments.
 496 
 497 
 498        64
 499               Unable to access either or both of the specified src or dst
 500               directories.
 501 
 502 
 503        128
 504               Miscellaneous other failures.
 505 
 506 
 507 FILES
 508        $HOME/.packingrules
 509                                list of files to be kept synchronized
 510 
 511 
 512        $HOME/.filesync-base
 513                                baseline summary file
 514 
 515 
 516 SEE ALSO
 517        packingrules(4), attributes(5)
 518 
 519 
 520 
 521                                September 8, 2015                   FILESYNC(1)