1filesync(1) User Commands filesync(1)
2
6 filesync - synchronize ordinary, directory or special files
7
9 filesync [-aehmnqvy] [-o src | dst]
10 [-f src | dst | old | new] [-r directory]...
11 filesync [-aehmnqvy] -s source-dir -d dest-dir filename...
14
17 The filesync utility synchronizes files between multiple computer sys‐
18 tems, typically a server and a portable computer. filesync synchronizes
19 ordinary, directory or special files. Although intended for use on
20 nomadic systems, filesync is useful for backup and file replication on
21 more permanently connected systems.
22 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 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 $HOME/.pack‐
35 ingrules file. $HOME/.packingrules is a packing rules list for filesync
36 and cachefspack, and contains a list of files to be kept synchronized.
37 See packingrules(4) and cachefspack(1M).
38 The second form of filesync copies specific files from a directory on
41 the source system to a directory on the destination system. In addi‐
42 tion, this form of filesync adds the file or files specified as argu‐
43 ments (filename) to $HOME/.packingrules. See -s and -d for information
44 about specifying directories on source and destination systems. See OP‐
45 ERANDS for details about specifying file (filename) arguments.
46 Multiple filesync commands are cumulative (that is, the specified files
49 are added to the already existing packing rules file list). See Multi‐
50 ple filesync Commands.
51 Reconciling and Synchronizing Files
53 filesync synchronizes files between computer systems by performing the
54 following two tasks:
55 1. filesync examines the directories and files specified in the
57 packing rules file on both systems, and determines whether
58 or not they are identical. Any file that differs requires
59 reconciliation.
60 filesync also maintains a baseline summary in the
62 $HOME/.filesync-base file for all of the files that are
63 being monitored. This file lists the names, types, and sizes
64 of all files as of the last reconciliation.
65 2. Based on the information contained in the baseline file and
67 the specified options (see Resolving filesync Conflicts),
68 filesync determines which of the various copies is the cor‐
69 rect one, and makes the corresponding changes to the other
70 system. Once this has been done, the two copies are, again,
71 identical (synchronized).
72 If a source file has changed and the destination file has
74 not, the changes on the source system are propagated to the
75 destination system. If a destination file has changed and
76 the corresponding source file has not, the changes on the
77 destination file are propagated to the source system. If
78 both systems have changed (and the files are not still iden‐
79 tical) a warning message will be printed out, asking the
80 user to resolve the conflict manually. See Resolving
81 filesync Conflicts.
82 Resolving filesync Conflicts
84 In cases where files on both sides have changed, filesync attempts to
85 determine which version should be chosen. If filesync cannot automati‐
86 cally determine which version should be selected, it prints out a warn‐
87 ing message and leaves the two incompatible versions of the file unrec‐
88 onciled.
89 In these cases, you must either resolve the differences manually, or
92 tell filesync how to choose which file should win. Use the -o and -f
93 options to tell filesync how to resolve conflicts (see OPTIONS).
94 Alternatively, for each conflicting file, you can examine the two ver‐
97 sions, determine which one should be kept, and manually bring the two
98 versions into agreement (by copying, deleting, or changing the owner‐
99 ship or protection to be correct). You can then re-run filesync to see
100 whether or not any other conflicts remain.
101 Packing Rules File
103 The packing rules file $HOME/.packingrules contains a list of files to
104 be kept synchronized. The syntax of this file is described in pack‐
105 ingrules(4).
106 The $HOME/.packingrules file is automatically created if users invoke
109 filesync with filename arguments. By using filesync options, users can
110 augment the packing rules in $HOME/.packingrules.
111 Many users choose to create the packing rules file manually and edit it
114 by hand. Users can edit $HOME/.packingrules (using any editor) to per‐
115 manently change the $HOME/.packingrules file, or to gain access to
116 more powerful options that are not available from the command line
117 (such as IGNORE commands). It is much easier to enter complex wildcard
118 expressions by editing the $HOME/.packingrules file.
119 Baseline File
121 $HOME/.filesync-base is the filesync baseline summary file. filesync
122 uses the information in $HOME/.filesync-base to identify the differ‐
123 ences between files during the reconciliation and synchronization
124 process. Users do not create or edit the baseline file. It is created
125 automatically by filesync and records the last known state of agree‐
126 ment between all of the files being maintained.
127 Multiple filesync Commands
129 Over a period of time, the set of files you want to keep synchronized
130 can change. It is common, for instance, to want to keep files pertain‐
131 ing to only a few active projects on your notebook. If you continue to
132 keep files associated with every project you have ever worked on syn‐
133 chronized, your notebook's disk will fill up with old files. Each
134 filesync command will waste a lot of time updating files you no longer
135 care about.
136 If you delete the files from your notebook, filesync will want to per‐
139 form the corresponding deletes on the server, which would not be what
140 you wanted. Rather, you would like a way to tell filesync to stop syn‐
141 chronizing some of the files. There are two ways to do this:
142 1. Edit $HOME/.packingrules. Delete the rules for the files
144 that you want to delete.
145 2. Delete $HOME/.packingrules. Use the filesync command to
147 specify the files that you want synchronized.
148 Either way works, and you can choose the one that seems easiest to you.
151 For minor changes, it is probably easier to just edit $HOME/.pack‐
152 ingrules. For major changes it is probably easier to start from
153 scratch.
154 Once filesync is no longer synchronizing a set of files, you can
157 delete them from your notebook without having any effect on the server.
158 Nomadic Machines
160 When using filesync to keep files synchronized between nomadic machines
161 and a server, store the packing rules and baseline files on the nomadic
162 machines, not the server. If, when logged into your notebook, the HOME
163 environment variable does not normally point to a directory on your
164 notebook, you can use the FILESYNC environment variable to specify an
165 alternate location for the packing rules and baseline files.
166 Each nomadic machine should carry its own packing rules and baseline
169 file. Incorrect file synchronization can result if a server carries a
170 baseline file and multiple nomadic machines attempt to reconcile
171 against the server's baseline file. In this case, a nomadic machine
172 could be using a baseline file that does not accurately describe the
173 state of its files. This might result in incorrect reconciliations.
174 To safeguard against the dangers associated with a single baseline
177 file being shared by more than two machines, filesync adds a default
178 rule to each new packing rules file. This default rule prevents the
179 packing rules and baseline files from being copied.
180
182 The following options are supported:
183 -a Force the checking of Access Control Lists
185 (ACLs ) and attempt to make them agree for
186 all new and changed files. If it is not
187 possible to set the ACL for a particular
188 file, filesync stops ACL synchronization
189 for that file.
190 Some file systems do not support ACLs . It
192 is not possible to synchronize ACLs between
193 file systems that support ACLs and those
194 that do not; attempting to do so will
195 result in numerous error messages.
196 -d dest-dir Specify the directory on the destination
199 system into which filename is to be copied.
200 Use with the -s source-dir option and the
201 filename operand. See -s and OPERANDS.
202 -e Flag all differences. It may not be possi‐
205 ble to resolve all conflicts involving
206 modes and ownership (unless filesync is
207 being run with root privileges). If you
208 cannot change the ownership or protections
209 on a file, filesync will normally ignore
210 conflicts in ownership and protection. If
211 you specify the -e (everything must agree)
212 flag, however, filesync will flag these
213 differences.
214 -f src | dst | old | new The -f option tells filesync how to resolve
217 conflicting changes. If a file has been
218 changed on both systems, and an -f option
219 has been specified, filesync will retain
220 the changes made on the favored system and
221 discard the changes made on the unfavored
222 system.
223 Specify -f src to favor the source-system
225 file. Specify -f dst to favor the destina‐
226 tion-system file. Specify -f old to favor
227 the older version of the file. Specify -f
228 new to favor the newer version of the file.
229 It is possible to specify the -f and -o
231 options in combination if they both spec‐
232 ify the same preference (src and dst). If
233 -f and -o conflict, the -f option is
234 ignored. See the -o option description.
235 -h Halt on error. Normally, if filesync
238 encounters a read or write error while
239 copying files, it notes the error and the
240 program continues, in an attempt to recon‐
241 cile other files. If the -h option is spec‐
242 ified, filesync will immediately halt when
243 one of these errors occurs and will not try
244 to process any more files.
245 -m Ensure that both copies of the file have
248 the same modification time. The modifica‐
249 tion time for newly copied files is set to
250 the time of reconciliation by default. File
251 changes are ordered by increasing modifica‐
252 tion times so that the propagated files
253 have the same relative modification time
254 ordering as the original changes. Users
255 should be warned that there is usually some
256 time skew between any two systems, and
257 transferring modification times from one
258 system to another can occasionally produce
259 strange results.
260 There are instances in which using filesync
262 to update some (but not all) files in a
263 directory will confuse the make program.
264 If, for instance, filesync is keeping .c
265 files synchronized, but ignoring .o files,
266 a changed .c file may show up with a modi‐
267 fication time prior to a .o file that was
268 built from a prior version of the .c file.
269 -n Do not really make the changes. If the -n
272 option is specified, filesync determines
273 what changes have been made to files, and
274 what reconciliations are required and dis‐
275 plays this information on the standard out‐
276 put. No changes are made to files, includ‐
277 ing the packing rules file.
278 Specifying both the -n and -o options
280 causes filesync to analyze the prevailing
281 system and report the changes that have
282 been made on that system. Using -n and -o
283 in combination is useful if your machine is
284 disconnected (and you cannot access the
285 server) but you want to know what changes
286 have been made on the local machine. See
287 the -o option description.
288 -o src | dst The -o option forces a one-way reconcilia‐
291 tion, favoring either the source system
292 (src) or destination system (dst).
293 Specify -o src to propagate changes only
295 from the source system to the destination
296 system. Changes made on the destination
297 system are ignored. filesync aborts if it
298 cannot access a source or destination
299 directory.
300 Specify -o dst to propagate changes only
302 from the destination system to the source
303 system. Changes made on the source system
304 are ignored. filesync aborts if it cannot
305 access a source or destination directory.
306 Specifying -n with the -o option causes
308 filesync to analyze the prevailing system
309 and reports on what changes have been made
310 on that system. Using -n and -o in combina‐
311 tion is useful if a machine is disconnected
312 (and there is no access to the server), but
313 you want to know what changes have been
314 made on the local machine. See the -n
315 option description.
316 It is possible to specify the -o and -f
318 options in combination if they both specify
319 the same preference (src or dst). If -o and
320 -f options conflict, the -f option will be
321 ignored. See the -f option description.
322 -q Suppress the standard filesync messages
325 that describe each reconciliation action as
326 it is performed.
327 The standard filesync message describes
329 each reconciliation action in the form of a
330 UNIX shell command (for example, mv, ln,
331 cp, rm, chmod, chown, chgrp, setfacl, and
332 so forth).
333 -r directory Limit the reconciliation to directory.
336 Specify multiple directories with multiple
337 -r specifications.
338 -s source-dir Specify the directory on the source system
341 from which the filename to be copied is
342 located. Use with the -d dest-dir option
343 and the filename operand. See the -d option
344 description and OPERANDS.
345 -v Display additional information about each
348 file comparison as it is made on the stan‐
349 dard output.
350 -y Bypass safety check prompts. Nomadic
353 machines occasionally move between domains,
354 and many of the files on which filesync
355 operates are expected to be accessed by
356 NFS. There is a danger that someday
357 filesync will be asked to reconcile local
358 changes against the wrong file system or
359 server. This could result in a large number
360 of inappropriate copies and deletions. To
361 prevent such a mishap, filesync performs a
362 few safety checks prior to reconciliation.
363 If large numbers of files are likely to be
364 deleted, or if high level directories have
365 changed their I-node numbers, filesync
366 prompts for a confirmation before reconcil‐
367 iation. If you know that this is likely,
368 and do not want to be prompted, use the -y
369 (yes) option to automatically confirm these
370 prompts.
371
374 The following operands are supported:
375 filename The name of the ordinary file, directory, symbolic link, or
377 special file in the specified source directory (source-dir)
378 to be synchronized. Specify multiple files by separating
379 each filename by spaces. Use the filename operand with the
380 -s and -d options. See OPTIONS.
381 If filename is an ordinary file, that ordinary file will be
383 replicated (with the same filename) in the specified desti‐
384 nation directory (dest-dir).
385 If filename is a directory, that directory and all of the
387 files and subdirectories under it will be replicated
388 (recursively) in the specified destination directory (dest-
389 dir).
390 If filename is a symbolic link, a copy of that symbolic
392 link will be replicated in the specified destination direc‐
393 tory (dest-dir).
394 If filename is a special file, a special file with the same
396 major or minor device numbers will be replicated in the
397 specified destination directory. (dest-dir). Only super-
398 users can use filesync to create special files.
399 Files created in the destination directory (dest-dir) will
401 have the same owner, group and other permissions as the
402 files in the source directory.
403 If filename contains escaped shell wildcard characters, the
405 wildcard characters are stored in $HOME/.packingrules and
406 evaluated each time filesync is run.
407 For example, the following would make sure that the two
409 specified files, currently in $RHOME, were replicated in
410 $HOME:
411 filesync -s $RHOME -d $HOME a.c b.c
413 The following example would ensure that all of the *.c
416 files in $RHOME were replicated in $HOME, even if those
417 files were not created until later.
418 filesync -s $RHOME -d $HOME '*.c'
420 If any of the destination files already exist, filesync
423 ensures that they are identical and issues warnings if they
424 are not.
425 Once files have been copied, the distinction between the
427 source and destination is a relatively arbitrary one
428 (except for its use in the -o and -f switches).
429
432 FILESYNC Specifies the default location of the filesync packing
433 rules and baseline files. The default value for this
434 variable is $HOME. The suffixes .packingrules and
435 .filesync-base will be appended to form the names of the
436 packing rules and baseline files.
437 LC_MESSAGES Determines how diagnostic and informative messages are
440 presented. In the "C" locale, the messages are presented
441 in the default form found in the program itself (in most
442 cases, U.S. English).
443
446 Normally, if all files are already up-to-date, or if all files were
447 successfully reconciled, filesync will exit with a status of 0. How‐
448 ever, if either the -n option was specified or any errors occurred, the
449 exit status will be the logical OR of the following:
450 0 No conflicts, all files up to date.
452 1 Some resolvable conflicts.
455 2 Some conflicts requiring manual resolution.
458 4 Some specified files did not exist.
461 8 Insufficient permission for some files.
464 16 Errors accessing packing rules or baseline file.
467 32 Invalid arguments.
470 64 Unable to access either or both of the specified src or dst
473 directories.
474 128 Miscellaneous other failures.
477
480 $HOME/.packingrules list of files to be kept synchronized
481 $HOME/.filesync-base baseline summary file
484
487 See attributes(5) for descriptions of the following attributes:
488 ┌─────────────────────────────┬─────────────────────────────┐
493 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
494 ├─────────────────────────────┼─────────────────────────────┤
495 │Availability │SUNWrcmdc │
496 └─────────────────────────────┴─────────────────────────────┘
497
499 cachefspack(1M), packingrules(4), attributes(5)
500SunOS 5.11 6 Nov 2000 filesync(1)