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)