-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathrsync.1.html
4514 lines (4340 loc) · 279 KB
/
rsync.1.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<html><head>
<title>rsync(1) manpage</title>
<meta charset="UTF-8"/>
<link href="https://fonts.googleapis.com/css2?family=Roboto&family=Roboto+Mono&display=swap" rel="stylesheet">
<style>
body {
max-width: 50em;
margin: auto;
}
body, b, strong, u {
font-family: 'Roboto', sans-serif;
}
a.tgt { font-face: symbol; font-weight: 400; font-size: 70%; visibility: hidden; text-decoration: none; color: #ddd; padding: 0 4px; border: 0; }
a.tgt:after { content: '🔗'; }
a.tgt:hover { color: #444; background-color: #eaeaea; }
h1:hover > a.tgt, h2:hover > a.tgt, h3:hover > a.tgt, dt:hover > a.tgt { visibility: visible; }
code {
font-family: 'Roboto Mono', monospace;
font-weight: bold;
white-space: pre;
}
pre code {
display: block;
font-weight: normal;
}
blockquote pre code {
background: #f1f1f1;
}
dd p:first-of-type {
margin-block-start: 0em;
}
</style>
</head><body>
<h2 id="NAME">NAME<a href="#NAME" class="tgt"></a></h2>
<p>rsync -⁠ a fast, versatile, remote (and local) file-copying tool</p>
<h2 id="SYNOPSIS">SYNOPSIS<a href="#SYNOPSIS" class="tgt"></a></h2>
<pre><code>Local:
rsync [OPTION...] SRC... [DEST]
Access via remote shell:
Pull:
rsync [OPTION...] [USER@]HOST:SRC... [DEST]
Push:
rsync [OPTION...] SRC... [USER@]HOST:DEST
Access via rsync daemon:
Pull:
rsync [OPTION...] [USER@]HOST::SRC... [DEST]
rsync [OPTION...] rsync://[USER@]HOST[:PORT]/SRC... [DEST]
Push:
rsync [OPTION...] SRC... [USER@]HOST::DEST
rsync [OPTION...] SRC... rsync://[USER@]HOST[:PORT]/DEST)
</code></pre>
<p>Usages with just one SRC arg and no DEST arg will list the source files instead
of copying.</p>
<p>The online version of this manpage (that includes cross-linking of topics)
is available at <a href="https://download.samba.org/pub/rsync/rsync.1">https://download.samba.org/pub/rsync/rsync.1</a>.</p>
<h2 id="DESCRIPTION">DESCRIPTION<a href="#DESCRIPTION" class="tgt"></a></h2>
<p>Rsync is a fast and extraordinarily versatile file copying tool. It can copy
locally, to/from another host over any remote shell, or to/from a remote rsync
daemon. It offers a large number of options that control every aspect of its
behavior and permit very flexible specification of the set of files to be
copied. It is famous for its delta-transfer algorithm, which reduces the
amount of data sent over the network by sending only the differences between
the source files and the existing files in the destination. Rsync is widely
used for backups and mirroring and as an improved copy command for everyday
use.</p>
<p>Rsync finds files that need to be transferred using a "quick check" algorithm
(by default) that looks for files that have changed in size or in last-modified
time. Any changes in the other preserved attributes (as requested by options)
are made on the destination file directly when the quick check indicates that
the file's data does not need to be updated.</p>
<p>Some of the additional features of rsync are:</p>
<ul>
<li>support for copying links, devices, owners, groups, and permissions</li>
<li>exclude and exclude-from options similar to GNU tar</li>
<li>a CVS exclude mode for ignoring the same files that CVS would ignore</li>
<li>can use any transparent remote shell, including ssh or rsh</li>
<li>does not require super-user privileges</li>
<li>pipelining of file transfers to minimize latency costs</li>
<li>support for anonymous or authenticated rsync daemons (ideal for mirroring)</li>
</ul>
<h2 id="GENERAL">GENERAL<a href="#GENERAL" class="tgt"></a></h2>
<p>Rsync copies files either to or from a remote host, or locally on the current
host (it does not support copying files between two remote hosts).</p>
<p>There are two different ways for rsync to contact a remote system: using a
remote-shell program as the transport (such as ssh or rsh) or contacting an
rsync daemon directly via TCP. The remote-shell transport is used whenever the
source or destination path contains a single colon (:) separator after a host
specification. Contacting an rsync daemon directly happens when the source or
destination path contains a double colon (::) separator after a host
specification, OR when an rsync:// URL is specified (see also the <a href="#USING_RSYNC-DAEMON_FEATURES_VIA_A_REMOTE-SHELL_CONNECTION">USING
RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION</a> section for an
exception to this latter rule).</p>
<p>As a special case, if a single source arg is specified without a destination,
the files are listed in an output format similar to "<code>ls -l</code>".</p>
<p>As expected, if neither the source or destination path specify a remote host,
the copy occurs locally (see also the <a href="#opt--list-only"><code>--list-only</code></a> option).</p>
<p>Rsync refers to the local side as the client and the remote side as the server.
Don't confuse server with an rsync daemon. A daemon is always a server, but a
server can be either a daemon or a remote-shell spawned process.</p>
<h2 id="SETUP">SETUP<a href="#SETUP" class="tgt"></a></h2>
<p>See the file README.md for installation instructions.</p>
<p>Once installed, you can use rsync to any machine that you can access via a
remote shell (as well as some that you can access using the rsync daemon-mode
protocol). For remote transfers, a modern rsync uses ssh for its
communications, but it may have been configured to use a different remote shell
by default, such as rsh or remsh.</p>
<p>You can also specify any remote shell you like, either by using the <a href="#opt-e"><code>-e</code></a>
command line option, or by setting the <a href="#RSYNC_RSH"><code>RSYNC_RSH</code></a> environment variable.</p>
<p>Note that rsync must be installed on both the source and destination machines.</p>
<h2 id="USAGE">USAGE<a href="#USAGE" class="tgt"></a></h2>
<p>You use rsync in the same way you use rcp. You must specify a source and a
destination, one of which may be remote.</p>
<p>Perhaps the best way to explain the syntax is with some examples:</p>
<blockquote>
<pre><code>rsync -t *.c foo:src/
</code></pre>
</blockquote>
<p>This would transfer all files matching the pattern <code>*.c</code> from the current
directory to the directory src on the machine foo. If any of the files already
exist on the remote system then the rsync remote-update protocol is used to
update the file by sending only the differences in the data. Note that the
expansion of wildcards on the command-line (<code>*.c</code>) into a list of files is
handled by the shell before it runs rsync and not by rsync itself (exactly the
same as all other Posix-style programs).</p>
<blockquote>
<pre><code>rsync -avz foo:src/bar /data/tmp
</code></pre>
</blockquote>
<p>This would recursively transfer all files from the directory src/bar on the
machine foo into the /data/tmp/bar directory on the local machine. The files
are transferred in archive mode, which ensures that symbolic links, devices,
attributes, permissions, ownerships, etc. are preserved in the transfer.
Additionally, compression will be used to reduce the size of data portions of
the transfer.</p>
<blockquote>
<pre><code>rsync -avz foo:src/bar/ /data/tmp
</code></pre>
</blockquote>
<p>A trailing slash on the source changes this behavior to avoid creating an
additional directory level at the destination. You can think of a trailing /
on a source as meaning "copy the contents of this directory" as opposed to
"copy the directory by name", but in both cases the attributes of the
containing directory are transferred to the containing directory on the
destination. In other words, each of the following commands copies the files
in the same way, including their setting of the attributes of /dest/foo:</p>
<blockquote>
<pre><code>rsync -av /src/foo /dest
rsync -av /src/foo/ /dest/foo
</code></pre>
</blockquote>
<p>Note also that host and module references don't require a trailing slash to
copy the contents of the default directory. For example, both of these copy
the remote directory's contents into "/dest":</p>
<blockquote>
<pre><code>rsync -av host: /dest
rsync -av host::module /dest
</code></pre>
</blockquote>
<p>You can also use rsync in local-only mode, where both the source and
destination don't have a ':' in the name. In this case it behaves like an
improved copy command.</p>
<p>Finally, you can list all the (listable) modules available from a particular
rsync daemon by leaving off the module name:</p>
<blockquote>
<pre><code>rsync somehost.mydomain.com::
</code></pre>
</blockquote>
<h2 id="COPYING_TO_A_DIFFERENT_NAME">COPYING TO A DIFFERENT NAME<a href="#COPYING_TO_A_DIFFERENT_NAME" class="tgt"></a></h2>
<p>When you want to copy a directory to a different name, use a trailing slash on
the source directory to put the contents of the directory into any destination
directory you like:</p>
<blockquote>
<pre><code>rsync -ai foo/ bar/
</code></pre>
</blockquote>
<p>Rsync also has the ability to customize a destination file's name when copying
a single item. The rules for this are:</p>
<ul>
<li>The transfer list must consist of a single item (either a file or an empty
directory)</li>
<li>The final element of the destination path must not exist as a directory</li>
<li>The destination path must not have been specified with a trailing slash</li>
</ul>
<p>Under those circumstances, rsync will set the name of the destination's single
item to the last element of the destination path. Keep in mind that it is best
to only use this idiom when copying a file and use the above trailing-slash
idiom when copying a directory.</p>
<p>The following example copies the <code>foo.c</code> file as <code>bar.c</code> in the <code>save</code> dir
(assuming that <code>bar.c</code> isn't a directory):</p>
<blockquote>
<pre><code>rsync -ai src/foo.c save/bar.c
</code></pre>
</blockquote>
<p>The single-item copy rule might accidentally bite you if you unknowingly copy a
single item and specify a destination dir that doesn't exist (without using a
trailing slash). For example, if <code>src/*.c</code> matches one file and <code>save/dir</code>
doesn't exist, this will confuse you by naming the destination file <code>save/dir</code>:</p>
<blockquote>
<pre><code>rsync -ai src/*.c save/dir
</code></pre>
</blockquote>
<p>To prevent such an accident, either make sure the destination dir exists or
specify the destination path with a trailing slash:</p>
<blockquote>
<pre><code>rsync -ai src/*.c save/dir/
</code></pre>
</blockquote>
<h2 id="SORTED_TRANSFER_ORDER">SORTED TRANSFER ORDER<a href="#SORTED_TRANSFER_ORDER" class="tgt"></a></h2>
<p>Rsync always sorts the specified filenames into its internal transfer list.
This handles the merging together of the contents of identically named
directories, makes it easy to remove duplicate filenames. It can, however,
confuse someone when the files are transferred in a different order than what
was given on the command-line.</p>
<p>If you need a particular file to be transferred prior to another, either
separate the files into different rsync calls, or consider using
<a href="#opt--delay-updates"><code>--delay-updates</code></a> (which doesn't affect the sorted transfer order, but
does make the final file-updating phase happen much more rapidly).</p>
<h2 id="MULTI-HOST_SECURITY">MULTI-HOST SECURITY<a href="#MULTI-HOST_SECURITY" class="tgt"></a></h2>
<p>Rsync takes steps to ensure that the file requests that are shared in a
transfer are protected against various security issues. Most of the potential
problems arise on the receiving side where rsync takes steps to ensure that the
list of files being transferred remains within the bounds of what was
requested.</p>
<p>Toward this end, rsync 3.1.2 and later have aborted when a file list contains
an absolute or relative path that tries to escape out of the top of the
transfer. Also, beginning with version 3.2.5, rsync does two more safety
checks of the file list to (1) ensure that no extra source arguments were added
into the transfer other than those that the client requested and (2) ensure
that the file list obeys the exclude rules that were sent to the sender.</p>
<p>For those that don't yet have a 3.2.5 client rsync (or those that want to be
extra careful), it is safest to do a copy into a dedicated destination
directory for the remote files when you don't trust the remote host. For
example, instead of doing an rsync copy into your home directory:</p>
<blockquote>
<pre><code>rsync -aiv host1:dir1 ~
</code></pre>
</blockquote>
<p>Dedicate a "host1-files" dir to the remote content:</p>
<blockquote>
<pre><code>rsync -aiv host1:dir1 ~/host1-files
</code></pre>
</blockquote>
<p>See the <a href="#opt--trust-sender"><code>--trust-sender</code></a> option for additional details.</p>
<p>CAUTION: it is not particularly safe to use rsync to copy files from a
case-preserving filesystem to a case-ignoring filesystem. If you must perform
such a copy, you should either disable symlinks via <code>--no-links</code> or enable the
munging of symlinks via <a href="#opt--munge-links"><code>--munge-links</code></a> (and make sure you use the
right local or remote option). This will prevent rsync from doing potentially
dangerous things if a symlink name overlaps with a file or directory. It does
not, however, ensure that you get a full copy of all the files (since that may
not be possible when the names overlap). A potentially better solution is to
list all the source files and create a safe list of filenames that you pass to
the <a href="#opt--files-from"><code>--files-from</code></a> option. Any files that conflict in name would need
to be copied to different destination directories using more than one copy.</p>
<p>While a copy of a case-ignoring filesystem to a case-ignoring filesystem can
work out fairly well, if no <code>--delete-during</code> or <code>--delete-before</code> option is
active, rsync can potentially update an existing file on the receiving side
without noticing that the upper-/lower-case of the filename should be changed
to match the sender.</p>
<h2 id="ADVANCED_USAGE">ADVANCED USAGE<a href="#ADVANCED_USAGE" class="tgt"></a></h2>
<p>The syntax for requesting multiple files from a remote host is done by
specifying additional remote-host args in the same style as the first, or with
the hostname omitted. For instance, all these work:</p>
<blockquote>
<pre><code>rsync -aiv host:file1 :file2 host:file{3,4} /dest/
rsync -aiv host::modname/file{1,2} host::modname/extra /dest/
rsync -aiv host::modname/first ::extra-file{1,2} /dest/
</code></pre>
</blockquote>
<p>Note that a daemon connection only supports accessing one module per copy
command, so if the start of a follow-up path doesn't begin with the
modname of the first path, it is assumed to be a path in the module (such as
the extra-file1 & extra-file2 that are grabbed above).</p>
<p>Really old versions of rsync (2.6.9 and before) only allowed specifying one
remote-source arg, so some people have instead relied on the remote-shell
performing space splitting to break up an arg into multiple paths. Such
unintuitive behavior is no longer supported by default (though you can request
it, as described below).</p>
<p>Starting in 3.2.4, filenames are passed to a remote shell in such a way as to
preserve the characters you give it. Thus, if you ask for a file with spaces
in the name, that's what the remote rsync looks for:</p>
<blockquote>
<pre><code>rsync -aiv host:'a simple file.pdf' /dest/
</code></pre>
</blockquote>
<p>If you use scripts that have been written to manually apply extra quoting to
the remote rsync args (or to require remote arg splitting), you can ask rsync
to let your script handle the extra escaping. This is done by either adding
the <a href="#opt--old-args"><code>--old-args</code></a> option to the rsync runs in the script (which requires
a new rsync) or exporting <a href="#RSYNC_OLD_ARGS">RSYNC_OLD_ARGS</a>=1 and <a href="#RSYNC_PROTECT_ARGS">RSYNC_PROTECT_ARGS</a>=0
(which works with old or new rsync versions).</p>
<h2 id="CONNECTING_TO_AN_RSYNC_DAEMON">CONNECTING TO AN RSYNC DAEMON<a href="#CONNECTING_TO_AN_RSYNC_DAEMON" class="tgt"></a></h2>
<p>It is also possible to use rsync without a remote shell as the transport. In
this case you will directly connect to a remote rsync daemon, typically using
TCP port 873. (This obviously requires the daemon to be running on the remote
system, so refer to the <a href="#STARTING_AN_RSYNC_DAEMON_TO_ACCEPT_CONNECTIONS">STARTING AN RSYNC DAEMON TO ACCEPT CONNECTIONS</a>
section below for information on that.)</p>
<p>Using rsync in this way is the same as using it with a remote shell except
that:</p>
<ul>
<li>Use either double-colon syntax or rsync:// URL syntax instead of the
single-colon (remote shell) syntax.</li>
<li>The first element of the "path" is actually a module name.</li>
<li>Additional remote source args can use an abbreviated syntax that omits the
hostname and/or the module name, as discussed in <a href="#ADVANCED_USAGE">ADVANCED USAGE</a>.</li>
<li>The remote daemon may print a "message of the day" when you connect.</li>
<li>If you specify only the host (with no module or path) then a list of
accessible modules on the daemon is output.</li>
<li>If you specify a remote source path but no destination, a listing of the
matching files on the remote daemon is output.</li>
<li>The <a href="#opt--rsh"><code>--rsh</code></a> (<code>-e</code>) option must be omitted to avoid changing the
connection style from using a socket connection to <a href="#USING_RSYNC-DAEMON_FEATURES_VIA_A_REMOTE-SHELL_CONNECTION">USING RSYNC-DAEMON
FEATURES VIA A REMOTE-SHELL CONNECTION</a>.</li>
</ul>
<p>An example that copies all the files in a remote module named "src":</p>
<blockquote>
<pre><code>rsync -av host::src /dest
</code></pre>
</blockquote>
<p>Some modules on the remote daemon may require authentication. If so, you will
receive a password prompt when you connect. You can avoid the password prompt
by setting the environment variable <a href="#RSYNC_PASSWORD"><code>RSYNC_PASSWORD</code></a> to the password you
want to use or using the <a href="#opt--password-file"><code>--password-file</code></a> option. This may be useful
when scripting rsync.</p>
<p>WARNING: On some systems environment variables are visible to all users. On
those systems using <a href="#opt--password-file"><code>--password-file</code></a> is recommended.</p>
<p>You may establish the connection via a web proxy by setting the environment
variable <a href="#RSYNC_PROXY"><code>RSYNC_PROXY</code></a> to a hostname:port pair pointing to your web proxy.
Note that your web proxy's configuration must support proxy connections to port
873.</p>
<p>You may also establish a daemon connection using a program as a proxy by
setting the environment variable <a href="#RSYNC_CONNECT_PROG"><code>RSYNC_CONNECT_PROG</code></a> to the commands you
wish to run in place of making a direct socket connection. The string may
contain the escape "%H" to represent the hostname specified in the rsync
command (so use "%%" if you need a single "%" in your string). For example:</p>
<blockquote>
<pre><code>export RSYNC_CONNECT_PROG='ssh proxyhost nc %H 873'
rsync -av targethost1::module/src/ /dest/
rsync -av rsync://targethost2/module/src/ /dest/
</code></pre>
</blockquote>
<p>The command specified above uses ssh to run nc (netcat) on a proxyhost, which
forwards all data to port 873 (the rsync daemon) on the targethost (%H).</p>
<p>Note also that if the <a href="#RSYNC_SHELL"><code>RSYNC_SHELL</code></a> environment variable is set, that
program will be used to run the <code>RSYNC_CONNECT_PROG</code> command instead of using
the default shell of the <strong>system()</strong> call.</p>
<h2 id="USING_RSYNC-DAEMON_FEATURES_VIA_A_REMOTE-SHELL_CONNECTION">USING RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION<a href="#USING_RSYNC-DAEMON_FEATURES_VIA_A_REMOTE-SHELL_CONNECTION" class="tgt"></a></h2>
<p>It is sometimes useful to use various features of an rsync daemon (such as
named modules) without actually allowing any new socket connections into a
system (other than what is already required to allow remote-shell access).
Rsync supports connecting to a host using a remote shell and then spawning a
single-use "daemon" server that expects to read its config file in the home dir
of the remote user. This can be useful if you want to encrypt a daemon-style
transfer's data, but since the daemon is started up fresh by the remote user,
you may not be able to use features such as chroot or change the uid used by
the daemon. (For another way to encrypt a daemon transfer, consider using ssh
to tunnel a local port to a remote machine and configure a normal rsync daemon
on that remote host to only allow connections from "localhost".)</p>
<p>From the user's perspective, a daemon transfer via a remote-shell connection
uses nearly the same command-line syntax as a normal rsync-daemon transfer,
with the only exception being that you must explicitly set the remote shell
program on the command-line with the <a href="#opt--rsh"><code>--rsh=COMMAND</code></a> option. (Setting the
RSYNC_RSH in the environment will not turn on this functionality.) For example:</p>
<blockquote>
<pre><code>rsync -av --rsh=ssh host::module /dest
</code></pre>
</blockquote>
<p>If you need to specify a different remote-shell user, keep in mind that the
user@ prefix in front of the host is specifying the rsync-user value (for a
module that requires user-based authentication). This means that you must give
the '-⁠l user' option to ssh when specifying the remote-shell, as in this
example that uses the short version of the <a href="#opt--rsh"><code>--rsh</code></a> option:</p>
<blockquote>
<pre><code>rsync -av -e "ssh -l ssh-user" rsync-user@host::module /dest
</code></pre>
</blockquote>
<p>The "ssh-user" will be used at the ssh level; the "rsync-user" will be used to
log-in to the "module".</p>
<p>In this setup, the daemon is started by the ssh command that is accessing the
system (which can be forced via the <code>~/.ssh/authorized_keys</code> file, if desired).
However, when accessing a daemon directly, it needs to be started beforehand.</p>
<h2 id="STARTING_AN_RSYNC_DAEMON_TO_ACCEPT_CONNECTIONS">STARTING AN RSYNC DAEMON TO ACCEPT CONNECTIONS<a href="#STARTING_AN_RSYNC_DAEMON_TO_ACCEPT_CONNECTIONS" class="tgt"></a></h2>
<p>In order to connect to an rsync daemon, the remote system needs to have a
daemon already running (or it needs to have configured something like inetd to
spawn an rsync daemon for incoming connections on a particular port). For full
information on how to start a daemon that will handling incoming socket
connections, see the <a href="rsyncd.conf.5"><strong>rsyncd.conf</strong>(5)</a> manpage -⁠-⁠ that is
the config file for the daemon, and it contains the full details for how to run
the daemon (including stand-alone and inetd configurations).</p>
<p>If you're using one of the remote-shell transports for the transfer, there is
no need to manually start an rsync daemon.</p>
<h2 id="EXAMPLES">EXAMPLES<a href="#EXAMPLES" class="tgt"></a></h2>
<p>Here are some examples of how rsync can be used.</p>
<p>To backup a home directory, which consists of large MS Word files and mail
folders, a per-user cron job can be used that runs this each day:</p>
<blockquote>
<pre><code>rsync -aiz . bkhost:backup/joe/
</code></pre>
</blockquote>
<p>To move some files from a remote host to the local host, you could run:</p>
<blockquote>
<pre><code>rsync -aiv --remove-source-files rhost:/tmp/{file1,file2}.c ~/src/
</code></pre>
</blockquote>
<h2 id="OPTION_SUMMARY">OPTION SUMMARY<a href="#OPTION_SUMMARY" class="tgt"></a></h2>
<p>Here is a short summary of the options available in rsync. Each option also
has its own detailed description later in this manpage.</p>
<pre><code>--verbose, -v increase verbosity
--info=FLAGS fine-grained informational verbosity
--debug=FLAGS fine-grained debug verbosity
--stderr=e|a|c change stderr output mode (default: errors)
--quiet, -q suppress non-error messages
--no-motd suppress daemon-mode MOTD
--checksum, -c skip based on checksum, not mod-time & size
--archive, -a archive mode is -rlptgoD (no -A,-X,-U,-N,-H)
--no-OPTION turn off an implied OPTION (e.g. --no-D)
--recursive, -r recurse into directories
--relative, -R use relative path names
--no-implied-dirs don't send implied dirs with --relative
--backup, -b make backups (see --suffix & --backup-dir)
--backup-dir=DIR make backups into hierarchy based in DIR
--suffix=SUFFIX backup suffix (default ~ w/o --backup-dir)
--update, -u skip files that are newer on the receiver
--inplace update destination files in-place
--append append data onto shorter files
--append-verify --append w/old data in file checksum
--dirs, -d transfer directories without recursing
--old-dirs, --old-d works like --dirs when talking to old rsync
--mkpath create destination's missing path components
--links, -l copy symlinks as symlinks
--copy-links, -L transform symlink into referent file/dir
--copy-unsafe-links only "unsafe" symlinks are transformed
--safe-links ignore symlinks that point outside the tree
--munge-links munge symlinks to make them safe & unusable
--copy-dirlinks, -k transform symlink to dir into referent dir
--keep-dirlinks, -K treat symlinked dir on receiver as dir
--hard-links, -H preserve hard links
--perms, -p preserve permissions
--executability, -E preserve executability
--chmod=CHMOD affect file and/or directory permissions
--acls, -A preserve ACLs (implies --perms)
--xattrs, -X preserve extended attributes
--owner, -o preserve owner (super-user only)
--group, -g preserve group
--devices preserve device files (super-user only)
--copy-devices copy device contents as a regular file
--write-devices write to devices as files (implies --inplace)
--specials preserve special files
-D same as --devices --specials
--times, -t preserve modification times
--atimes, -U preserve access (use) times
--open-noatime avoid changing the atime on opened files
--crtimes, -N preserve create times (newness)
--omit-dir-times, -O omit directories from --times
--omit-link-times, -J omit symlinks from --times
--super receiver attempts super-user activities
--fake-super store/recover privileged attrs using xattrs
--sparse, -S turn sequences of nulls into sparse blocks
--preallocate allocate dest files before writing them
--dry-run, -n perform a trial run with no changes made
--whole-file, -W copy files whole (w/o delta-xfer algorithm)
--checksum-choice=STR choose the checksum algorithm (aka --cc)
--one-file-system, -x don't cross filesystem boundaries
--block-size=SIZE, -B force a fixed checksum block-size
--rsh=COMMAND, -e specify the remote shell to use
--rsync-path=PROGRAM specify the rsync to run on remote machine
--existing skip creating new files on receiver
--ignore-existing skip updating files that exist on receiver
--remove-source-files sender removes synchronized files (non-dir)
--del an alias for --delete-during
--delete delete extraneous files from dest dirs
--delete-before receiver deletes before xfer, not during
--delete-during receiver deletes during the transfer
--delete-delay find deletions during, delete after
--delete-after receiver deletes after transfer, not during
--delete-excluded also delete excluded files from dest dirs
--ignore-missing-args ignore missing source args without error
--delete-missing-args delete missing source args from destination
--ignore-errors delete even if there are I/O errors
--force force deletion of dirs even if not empty
--max-delete=NUM don't delete more than NUM files
--max-size=SIZE don't transfer any file larger than SIZE
--min-size=SIZE don't transfer any file smaller than SIZE
--max-alloc=SIZE change a limit relating to memory alloc
--partial keep partially transferred files
--partial-dir=DIR put a partially transferred file into DIR
--delay-updates put all updated files into place at end
--prune-empty-dirs, -m prune empty directory chains from file-list
--numeric-ids don't map uid/gid values by user/group name
--usermap=STRING custom username mapping
--groupmap=STRING custom groupname mapping
--chown=USER:GROUP simple username/groupname mapping
--timeout=SECONDS set I/O timeout in seconds
--contimeout=SECONDS set daemon connection timeout in seconds
--ignore-times, -I don't skip files that match size and time
--size-only skip files that match in size
--modify-window=NUM, -@ set the accuracy for mod-time comparisons
--temp-dir=DIR, -T create temporary files in directory DIR
--fuzzy, -y find similar file for basis if no dest file
--compare-dest=DIR also compare destination files relative to DIR
--copy-dest=DIR ... and include copies of unchanged files
--link-dest=DIR hardlink to files in DIR when unchanged
--compress, -z compress file data during the transfer
--compress-choice=STR choose the compression algorithm (aka --zc)
--compress-level=NUM explicitly set compression level (aka --zl)
--skip-compress=LIST skip compressing files with suffix in LIST
--cvs-exclude, -C auto-ignore files in the same way CVS does
--filter=RULE, -f add a file-filtering RULE
-F same as --filter='dir-merge /.rsync-filter'
repeated: --filter='- .rsync-filter'
--exclude=PATTERN exclude files matching PATTERN
--exclude-from=FILE read exclude patterns from FILE
--include=PATTERN don't exclude files matching PATTERN
--include-from=FILE read include patterns from FILE
--files-from=FILE read list of source-file names from FILE
--from0, -0 all *-from/filter files are delimited by 0s
--old-args disable the modern arg-protection idiom
--secluded-args, -s use the protocol to safely send the args
--trust-sender trust the remote sender's file list
--copy-as=USER[:GROUP] specify user & optional group for the copy
--address=ADDRESS bind address for outgoing socket to daemon
--port=PORT specify double-colon alternate port number
--sockopts=OPTIONS specify custom TCP options
--blocking-io use blocking I/O for the remote shell
--outbuf=N|L|B set out buffering to None, Line, or Block
--stats give some file-transfer stats
--8-bit-output, -8 leave high-bit chars unescaped in output
--human-readable, -h output numbers in a human-readable format
--progress show progress during transfer
-P same as --partial --progress
--itemize-changes, -i output a change-summary for all updates
--remote-option=OPT, -M send OPTION to the remote side only
--out-format=FORMAT output updates using the specified FORMAT
--log-file=FILE log what we're doing to the specified FILE
--log-file-format=FMT log updates using the specified FMT
--password-file=FILE read daemon-access password from FILE
--early-input=FILE use FILE for daemon's early exec input
--list-only list the files instead of copying them
--bwlimit=RATE limit socket I/O bandwidth
--stop-after=MINS Stop rsync after MINS minutes have elapsed
--stop-at=y-m-dTh:m Stop rsync at the specified point in time
--fsync fsync every written file
--write-batch=FILE write a batched update to FILE
--only-write-batch=FILE like --write-batch but w/o updating dest
--read-batch=FILE read a batched update from FILE
--protocol=NUM force an older protocol version to be used
--iconv=CONVERT_SPEC request charset conversion of filenames
--checksum-seed=NUM set block/file checksum seed (advanced)
--ipv4, -4 prefer IPv4
--ipv6, -6 prefer IPv6
--version, -V print the version + other info and exit
--help, -h (*) show this help (* -h is help only on its own)
</code></pre>
<p>Rsync can also be run as a daemon, in which case the following options are
accepted:</p>
<pre><code>--daemon run as an rsync daemon
--address=ADDRESS bind to the specified address
--bwlimit=RATE limit socket I/O bandwidth
--config=FILE specify alternate rsyncd.conf file
--dparam=OVERRIDE, -M override global daemon config parameter
--no-detach do not detach from the parent
--port=PORT listen on alternate port number
--log-file=FILE override the "log file" setting
--log-file-format=FMT override the "log format" setting
--sockopts=OPTIONS specify custom TCP options
--verbose, -v increase verbosity
--ipv4, -4 prefer IPv4
--ipv6, -6 prefer IPv6
--help, -h show this help (when used with --daemon)
</code></pre>
<h2 id="OPTIONS">OPTIONS<a href="#OPTIONS" class="tgt"></a></h2>
<p>Rsync accepts both long (double-dash + word) and short (single-dash + letter)
options. The full list of the available options are described below. If an
option can be specified in more than one way, the choices are comma-separated.
Some options only have a long variant, not a short.</p>
<p>If the option takes a parameter, the parameter is only listed after the long
variant, even though it must also be specified for the short. When specifying
a parameter, you can either use the form <code>--option=param</code>, <code>--option param</code>,
<code>-o=param</code>, <code>-o param</code>, or <code>-oparam</code> (the latter choices assume that your
option has a short variant).</p>
<p>The parameter may need to be quoted in some manner for it to survive the
shell's command-line parsing. Also keep in mind that a leading tilde (<code>~</code>) in
a pathname is substituted by your shell, so make sure that you separate the
option name from the pathname using a space if you want the local shell to
expand it.</p>
<dl>
<dt id="opt--help"><code>--help</code><a href="#opt--help" class="tgt"></a></dt><dd>
<p>Print a short help page describing the options available in rsync and exit.
You can also use <code>-h</code> for <code>--help</code> when it is used without any other
options (since it normally means <a href="#opt--human-readable"><code>--human-readable</code></a>).</p>
</dd>
<span id="opt-V"></span><dt id="opt--version"><code>--version</code>, <code>-V</code><a href="#opt--version" class="tgt"></a></dt><dd>
<p>Print the rsync version plus other info and exit. When repeated, the
information is output is a JSON format that is still fairly readable
(client side only).</p>
<p>The output includes a list of compiled-in capabilities, a list of
optimizations, the default list of checksum algorithms, the default list of
compression algorithms, the default list of daemon auth digests, a link to
the rsync web site, and a few other items.</p>
</dd>
<span id="opt-v"></span><dt id="opt--verbose"><code>--verbose</code>, <code>-v</code><a href="#opt--verbose" class="tgt"></a></dt><dd>
<p>This option increases the amount of information you are given during the
transfer. By default, rsync works silently. A single <code>-v</code> will give you
information about what files are being transferred and a brief summary at
the end. Two <code>-v</code> options will give you information on what files are
being skipped and slightly more information at the end. More than two <code>-v</code>
options should only be used if you are debugging rsync.</p>
<p>The end-of-run summary tells you the number of bytes sent to the remote
rsync (which is the receiving side on a local copy), the number of bytes
received from the remote host, and the average bytes per second of the
transferred data computed over the entire length of the rsync run. The
second line shows the total size (in bytes), which is the sum of all the
file sizes that rsync considered transferring. It also shows a "speedup"
value, which is a ratio of the total file size divided by the sum of the
sent and received bytes (which is really just a feel-good bigger-is-better
number). Note that these byte values can be made more (or less)
human-readable by using the <a href="#opt--human-readable"><code>--human-readable</code></a> (or
<code>--no-human-readable</code>) options.</p>
<p>In a modern rsync, the <code>-v</code> option is equivalent to the setting of groups
of <a href="#opt--info"><code>--info</code></a> and <a href="#opt--debug"><code>--debug</code></a> options. You can choose to use
these newer options in addition to, or in place of using <code>--verbose</code>, as
any fine-grained settings override the implied settings of <code>-v</code>. Both
<a href="#opt--info"><code>--info</code></a> and <a href="#opt--debug"><code>--debug</code></a> have a way to ask for help that
tells you exactly what flags are set for each increase in verbosity.</p>
<p>However, do keep in mind that a daemon's "<code>max verbosity</code>" setting will limit
how high of a level the various individual flags can be set on the daemon
side. For instance, if the max is 2, then any info and/or debug flag that
is set to a higher value than what would be set by <code>-vv</code> will be downgraded
to the <code>-vv</code> level in the daemon's logging.</p>
</dd>
<dt id="opt--info"><code>--info=FLAGS</code><a href="#opt--info" class="tgt"></a></dt><dd>
<p>This option lets you have fine-grained control over the information output
you want to see. An individual flag name may be followed by a level
number, with 0 meaning to silence that output, 1 being the default output
level, and higher numbers increasing the output of that flag (for those
that support higher levels). Use <code>--info=help</code> to see all the available
flag names, what they output, and what flag names are added for each
increase in the verbose level. Some examples:</p>
<blockquote>
<pre><code>rsync -a --info=progress2 src/ dest/
rsync -avv --info=stats2,misc1,flist0 src/ dest/
</code></pre>
</blockquote>
<p>Note that <code>--info=name</code>'s output is affected by the <a href="#opt--out-format"><code>--out-format</code></a>
and <a href="#opt--itemize-changes"><code>--itemize-changes</code></a> (<code>-i</code>) options. See those options for more
information on what is output and when.</p>
<p>This option was added to 3.1.0, so an older rsync on the server side might
reject your attempts at fine-grained control (if one or more flags needed
to be send to the server and the server was too old to understand them).
See also the "<code>max verbosity</code>" caveat above when dealing with a daemon.</p>
</dd>
<dt id="opt--debug"><code>--debug=FLAGS</code><a href="#opt--debug" class="tgt"></a></dt><dd>
<p>This option lets you have fine-grained control over the debug output you
want to see. An individual flag name may be followed by a level number,
with 0 meaning to silence that output, 1 being the default output level,
and higher numbers increasing the output of that flag (for those that
support higher levels). Use <code>--debug=help</code> to see all the available flag
names, what they output, and what flag names are added for each increase in
the verbose level. Some examples:</p>
<blockquote>
<pre><code>rsync -avvv --debug=none src/ dest/
rsync -avA --del --debug=del2,acl src/ dest/
</code></pre>
</blockquote>
<p>Note that some debug messages will only be output when the <a href="#opt--stderr"><code>--stderr=all</code></a>
option is specified, especially those pertaining to I/O and buffer debugging.</p>
<p>Beginning in 3.2.0, this option is no longer auto-forwarded to the server
side in order to allow you to specify different debug values for each side
of the transfer, as well as to specify a new debug option that is only
present in one of the rsync versions. If you want to duplicate the same
option on both sides, using brace expansion is an easy way to save you some
typing. This works in zsh and bash:</p>
<blockquote>
<pre><code>rsync -aiv {-M,}--debug=del2 src/ dest/
</code></pre>
</blockquote>
</dd>
<dt id="opt--stderr"><code>--stderr=errors|all|client</code><a href="#opt--stderr" class="tgt"></a></dt><dd>
<p>This option controls which processes output to stderr and if info messages
are also changed to stderr. The mode strings can be abbreviated, so feel
free to use a single letter value. The 3 possible choices are:</p>
<ul>
<li>
<p><code>errors</code> -⁠ (the default) causes all the rsync processes to send an
error directly to stderr, even if the process is on the remote side of
the transfer. Info messages are sent to the client side via the protocol
stream. If stderr is not available (i.e. when directly connecting with a
daemon via a socket) errors fall back to being sent via the protocol
stream.</p>
</li>
<li>
<p><code>all</code> -⁠ causes all rsync messages (info and error) to get written
directly to stderr from all (possible) processes. This causes stderr to
become line-buffered (instead of raw) and eliminates the ability to
divide up the info and error messages by file handle. For those doing
debugging or using several levels of verbosity, this option can help to
avoid clogging up the transfer stream (which should prevent any chance of
a deadlock bug hanging things up). It also allows <a href="#opt--debug"><code>--debug</code></a> to
enable some extra I/O related messages.</p>
</li>
<li>
<p><code>client</code> -⁠ causes all rsync messages to be sent to the client side
via the protocol stream. One client process outputs all messages, with
errors on stderr and info messages on stdout. This <strong>was</strong> the default
in older rsync versions, but can cause error delays when a lot of
transfer data is ahead of the messages. If you're pushing files to an
older rsync, you may want to use <code>--stderr=all</code> since that idiom has
been around for several releases.</p>
</li>
</ul>
<p>This option was added in rsync 3.2.3. This version also began the
forwarding of a non-default setting to the remote side, though rsync uses
the backward-compatible options <code>--msgs2stderr</code> and <code>--no-msgs2stderr</code> to
represent the <code>all</code> and <code>client</code> settings, respectively. A newer rsync
will continue to accept these older option names to maintain compatibility.</p>
</dd>
<span id="opt-q"></span><dt id="opt--quiet"><code>--quiet</code>, <code>-q</code><a href="#opt--quiet" class="tgt"></a></dt><dd>
<p>This option decreases the amount of information you are given during the
transfer, notably suppressing information messages from the remote server.
This option is useful when invoking rsync from cron.</p>
</dd>
<dt id="opt--no-motd"><code>--no-motd</code><a href="#opt--no-motd" class="tgt"></a></dt><dd>
<p>This option affects the information that is output by the client at the
start of a daemon transfer. This suppresses the message-of-the-day (MOTD)
text, but it also affects the list of modules that the daemon sends in
response to the "rsync host::" request (due to a limitation in the rsync
protocol), so omit this option if you want to request the list of modules
from the daemon.</p>
</dd>
<span id="opt-I"></span><dt id="opt--ignore-times"><code>--ignore-times</code>, <code>-I</code><a href="#opt--ignore-times" class="tgt"></a></dt><dd>
<p>Normally rsync will skip any files that are already the same size and have
the same modification timestamp. This option turns off this "quick check"
behavior, causing all files to be updated.</p>
<p>This option can be confusing compared to <a href="#opt--ignore-existing"><code>--ignore-existing</code></a> and
<a href="#opt--ignore-non-existing"><code>--ignore-non-existing</code></a> in that that they cause rsync to transfer
fewer files, while this option causes rsync to transfer more files.</p>
</dd>
<dt id="opt--size-only"><code>--size-only</code><a href="#opt--size-only" class="tgt"></a></dt><dd>
<p>This modifies rsync's "quick check" algorithm for finding files that need
to be transferred, changing it from the default of transferring files with
either a changed size or a changed last-modified time to just looking for
files that have changed in size. This is useful when starting to use rsync
after using another mirroring system which may not preserve timestamps
exactly.</p>
</dd>
<span id="opt-_"></span><dt id="opt--modify-window"><code>--modify-window=NUM</code>, <code>-@</code><a href="#opt--modify-window" class="tgt"></a></dt><dd>
<p>When comparing two timestamps, rsync treats the timestamps as being equal
if they differ by no more than the modify-window value. The default is 0,
which matches just integer seconds. If you specify a negative value (and
the receiver is at least version 3.1.3) then nanoseconds will also be taken
into account. Specifying 1 is useful for copies to/from MS Windows FAT
filesystems, because FAT represents times with a 2-second resolution
(allowing times to differ from the original by up to 1 second).</p>
<p>If you want all your transfers to default to comparing nanoseconds, you can
create a <code>~/.popt</code> file and put these lines in it:</p>
<blockquote>
<pre><code>rsync alias -a -a@-1
rsync alias -t -t@-1
</code></pre>
</blockquote>
<p>With that as the default, you'd need to specify <code>--modify-window=0</code> (aka
<code>-@0</code>) to override it and ignore nanoseconds, e.g. if you're copying
between ext3 and ext4, or if the receiving rsync is older than 3.1.3.</p>
</dd>
<span id="opt-c"></span><dt id="opt--checksum"><code>--checksum</code>, <code>-c</code><a href="#opt--checksum" class="tgt"></a></dt><dd>
<p>This changes the way rsync checks if the files have been changed and are in
need of a transfer. Without this option, rsync uses a "quick check" that
(by default) checks if each file's size and time of last modification match
between the sender and receiver. This option changes this to compare a
128-bit checksum for each file that has a matching size. Generating the
checksums means that both sides will expend a lot of disk I/O reading all
the data in the files in the transfer, so this can slow things down
significantly (and this is prior to any reading that will be done to
transfer changed files)</p>
<p>The sending side generates its checksums while it is doing the file-system
scan that builds the list of the available files. The receiver generates
its checksums when it is scanning for changed files, and will checksum any
file that has the same size as the corresponding sender's file: files with
either a changed size or a changed checksum are selected for transfer.</p>
<p>Note that rsync always verifies that each <u>transferred</u> file was correctly
reconstructed on the receiving side by checking a whole-file checksum that
is generated as the file is transferred, but that automatic
after-the-transfer verification has nothing to do with this option's
before-the-transfer "Does this file need to be updated?" check.</p>
<p>The checksum used is auto-negotiated between the client and the server, but
can be overridden using either the <a href="#opt--checksum-choice"><code>--checksum-choice</code></a> (<code>--cc</code>)
option or an environment variable that is discussed in that option's
section.</p>
</dd>
<span id="opt-a"></span><dt id="opt--archive"><code>--archive</code>, <code>-a</code><a href="#opt--archive" class="tgt"></a></dt><dd>
<p>This is equivalent to <code>-rlptgoD</code>. It is a quick way of saying you want
recursion and want to preserve almost everything. Be aware that it does
<strong>not</strong> include preserving ACLs (<code>-A</code>), xattrs (<code>-X</code>), atimes (<code>-U</code>),
crtimes (<code>-N</code>), nor the finding and preserving of hardlinks (<code>-H</code>).</p>
<p>The only exception to the above equivalence is when <a href="#opt--files-from"><code>--files-from</code></a>
is specified, in which case <a href="#opt-r"><code>-r</code></a> is not implied.</p>
</dd>
<dt id="opt--no-OPTION"><code>--no-OPTION</code><a href="#opt--no-OPTION" class="tgt"></a></dt><dd>
<p>You may turn off one or more implied options by prefixing the option name
with "no-". Not all positive options have a negated opposite, but a lot
do, including those that can be used to disable an implied option (e.g.
<code>--no-D</code>, <code>--no-perms</code>) or have different defaults in various circumstances
(e.g. <a href="#opt--no-whole-file"><code>--no-whole-file</code></a>, <code>--no-blocking-io</code>, <code>--no-dirs</code>). Every
valid negated option accepts both the short and the long option name after
the "no-" prefix (e.g. <code>--no-R</code> is the same as <code>--no-relative</code>).</p>
<p>As an example, if you want to use <a href="#opt--archive"><code>--archive</code></a> (<code>-a</code>) but don't want
<a href="#opt--owner"><code>--owner</code></a> (<code>-o</code>), instead of converting <code>-a</code> into <code>-rlptgD</code>, you
can specify <code>-a --no-o</code> (aka <code>--archive --no-owner</code>).</p>
<p>The order of the options is important: if you specify <code>--no-r -a</code>, the <code>-r</code>
option would end up being turned on, the opposite of <code>-a --no-r</code>. Note
also that the side-effects of the <a href="#opt--files-from"><code>--files-from</code></a> option are NOT
positional, as it affects the default state of several options and slightly
changes the meaning of <a href="#opt-a"><code>-a</code></a> (see the <a href="#opt--files-from"><code>--files-from</code></a> option
for more details).</p>
</dd>
<span id="opt-r"></span><dt id="opt--recursive"><code>--recursive</code>, <code>-r</code><a href="#opt--recursive" class="tgt"></a></dt><dd>
<p>This tells rsync to copy directories recursively. See also
<a href="#opt--dirs"><code>--dirs</code></a> (<code>-d</code>) for an option that allows the scanning of a single
directory.</p>
<p>See the <a href="#opt--inc-recursive"><code>--inc-recursive</code></a> option for a discussion of the
incremental recursion for creating the list of files to transfer.</p>
</dd>
<span id="opt--i-r"></span><dt id="opt--inc-recursive"><code>--inc-recursive</code>, <code>--i-r</code><a href="#opt--inc-recursive" class="tgt"></a></dt><dd>
<p>This option explicitly enables on incremental recursion when scanning for
files, which is enabled by default when using the <a href="#opt--recursive"><code>--recursive</code></a>
option and both sides of the transfer are running rsync 3.0.0 or newer.</p>
<p>Incremental recursion uses much less memory than non-incremental, while
also beginning the transfer more quickly (since it doesn't need to scan the
entire transfer hierarchy before it starts transferring files). If no
recursion is enabled in the source files, this option has no effect.</p>
<p>Some options require rsync to know the full file list, so these options
disable the incremental recursion mode. These include:</p>
<ul>
<li><a href="#opt--delete-before"><code>--delete-before</code></a> (the old default of <a href="#opt--delete"><code>--delete</code></a>)</li>
<li><a href="#opt--delete-after"><code>--delete-after</code></a></li>
<li><a href="#opt--prune-empty-dirs"><code>--prune-empty-dirs</code></a></li>
<li><a href="#opt--delay-updates"><code>--delay-updates</code></a></li>
</ul>
<p>In order to make <a href="#opt--delete"><code>--delete</code></a> compatible with incremental recursion,
rsync 3.0.0 made <a href="#opt--delete-during"><code>--delete-during</code></a> the default delete mode (which
was first added in 2.6.4).</p>
<p>One side-effect of incremental recursion is that any missing
sub-directories inside a recursively-scanned directory are (by default)
created prior to recursing into the sub-dirs. This earlier creation point
(compared to a non-incremental recursion) allows rsync to then set the
modify time of the finished directory right away (without having to delay
that until a bunch of recursive copying has finished). However, these
early directories don't yet have their completed mode, mtime, or ownership
set -⁠-⁠ they have more restrictive rights until the subdirectory's copying
actually begins. This early-creation idiom can be avoided by using the
<a href="#opt--omit-dir-times"><code>--omit-dir-times</code></a> option.</p>
<p>Incremental recursion can be disabled using the
<a href="#opt--no-inc-recursive"><code>--no-inc-recursive</code></a> (<code>--no-i-r</code>) option.</p>
</dd>
<span id="opt--no-i-r"></span><dt id="opt--no-inc-recursive"><code>--no-inc-recursive</code>, <code>--no-i-r</code><a href="#opt--no-inc-recursive" class="tgt"></a></dt><dd>
<p>Disables the new incremental recursion algorithm of the
<a href="#opt--recursive"><code>--recursive</code></a> option. This makes rsync scan the full file list
before it begins to transfer files. See <a href="#opt--inc-recursive"><code>--inc-recursive</code></a> for more
info.</p>
</dd>
<span id="opt-R"></span><dt id="opt--relative"><code>--relative</code>, <code>-R</code><a href="#opt--relative" class="tgt"></a></dt><dd>
<p>Use relative paths. This means that the full path names specified on the
command line are sent to the server rather than just the last parts of the
filenames. This is particularly useful when you want to send several
different directories at the same time. For example, if you used this
command:</p>
<blockquote>
<pre><code>rsync -av /foo/bar/baz.c remote:/tmp/
</code></pre>
</blockquote>
<p>would create a file named baz.c in /tmp/ on the remote machine. If instead
you used</p>
<blockquote>
<pre><code>rsync -avR /foo/bar/baz.c remote:/tmp/
</code></pre>
</blockquote>
<p>then a file named /tmp/foo/bar/baz.c would be created on the remote
machine, preserving its full path. These extra path elements are called
"implied directories" (i.e. the "foo" and the "foo/bar" directories in the
above example).</p>
<p>Beginning with rsync 3.0.0, rsync always sends these implied directories as
real directories in the file list, even if a path element is really a
symlink on the sending side. This prevents some really unexpected behaviors
when copying the full path of a file that you didn't realize had a symlink
in its path. If you want to duplicate a server-side symlink, include both
the symlink via its path, and referent directory via its real path. If
you're dealing with an older rsync on the sending side, you may need to use
the <a href="#opt--no-implied-dirs"><code>--no-implied-dirs</code></a> option.</p>
<p>It is also possible to limit the amount of path information that is sent as
implied directories for each path you specify. With a modern rsync on the
sending side (beginning with 2.6.7), you can insert a dot and a slash into
the source path, like this:</p>
<blockquote>
<pre><code>rsync -avR /foo/./bar/baz.c remote:/tmp/
</code></pre>
</blockquote>
<p>That would create /tmp/bar/baz.c on the remote machine. (Note that the dot
must be followed by a slash, so "/foo/." would not be abbreviated.) For
older rsync versions, you would need to use a chdir to limit the source
path. For example, when pushing files:</p>
<blockquote>
<pre><code>(cd /foo; rsync -avR bar/baz.c remote:/tmp/)
</code></pre>
</blockquote>
<p>(Note that the parens put the two commands into a sub-shell, so that the
"cd" command doesn't remain in effect for future commands.) If you're
pulling files from an older rsync, use this idiom (but only for a
non-daemon transfer):</p>
<blockquote>
<pre><code>rsync -avR --rsync-path="cd /foo; rsync" \
remote:bar/baz.c /tmp/
</code></pre>
</blockquote>
</dd>
<dt id="opt--no-implied-dirs"><code>--no-implied-dirs</code><a href="#opt--no-implied-dirs" class="tgt"></a></dt><dd>
<p>This option affects the default behavior of the <a href="#opt--relative"><code>--relative</code></a> option. When
it is specified, the attributes of the implied directories from the source
names are not included in the transfer. This means that the corresponding
path elements on the destination system are left unchanged if they exist,
and any missing implied directories are created with default attributes.
This even allows these implied path elements to have big differences, such
as being a symlink to a directory on the receiving side.</p>
<p>For instance, if a command-line arg or a files-from entry told rsync to
transfer the file "path/foo/file", the directories "path" and "path/foo"
are implied when <a href="#opt--relative"><code>--relative</code></a> is used. If "path/foo" is a symlink to "bar"
on the destination system, the receiving rsync would ordinarily delete
"path/foo", recreate it as a directory, and receive the file into the new
directory. With <code>--no-implied-dirs</code>, the receiving rsync updates
"path/foo/file" using the existing path elements, which means that the file
ends up being created in "path/bar". Another way to accomplish this link
preservation is to use the <a href="#opt--keep-dirlinks"><code>--keep-dirlinks</code></a> option (which will also affect
symlinks to directories in the rest of the transfer).</p>
<p>When pulling files from an rsync older than 3.0.0, you may need to use this
option if the sending side has a symlink in the path you request and you
wish the implied directories to be transferred as normal directories.</p>
</dd>
<span id="opt-b"></span><dt id="opt--backup"><code>--backup</code>, <code>-b</code><a href="#opt--backup" class="tgt"></a></dt><dd>
<p>With this option, preexisting destination files are renamed as each file is
transferred or deleted. You can control where the backup file goes and
what (if any) suffix gets appended using the <a href="#opt--backup-dir"><code>--backup-dir</code></a> and
<a href="#opt--suffix"><code>--suffix</code></a> options.</p>
<p>If you don't specify <a href="#opt--backup-dir"><code>--backup-dir</code></a>:</p>
<ol>
<li>the <a href="#opt--omit-dir-times"><code>--omit-dir-times</code></a> option will be forced on</li>
<li>the use of <a href="#opt--delete"><code>--delete</code></a> (without <a href="#opt--delete-excluded"><code>--delete-excluded</code></a>),
causes rsync to add a "protect" <a href="#FILTER_RULES">filter-rule</a> for the
backup suffix to the end of all your existing filters that looks like
this: <code>-f "P *~"</code>. This rule prevents previously backed-up files from
being deleted.</li>
</ol>
<p>Note that if you are supplying your own filter rules, you may need to
manually insert your own exclude/protect rule somewhere higher up in the
list so that it has a high enough priority to be effective (e.g. if your
rules specify a trailing inclusion/exclusion of <code>*</code>, the auto-added rule
would never be reached).</p>
</dd>
<dt id="opt--backup-dir"><code>--backup-dir=DIR</code><a href="#opt--backup-dir" class="tgt"></a></dt><dd>
<p>This implies the <a href="#opt--backup"><code>--backup</code></a> option, and tells rsync to store all
backups in the specified directory on the receiving side. This can be used
for incremental backups. You can additionally specify a backup suffix
using the <a href="#opt--suffix"><code>--suffix</code></a> option (otherwise the files backed up in the
specified directory will keep their original filenames).</p>
<p>Note that if you specify a relative path, the backup directory will be
relative to the destination directory, so you probably want to specify
either an absolute path or a path that starts with "../". If an rsync
daemon is the receiver, the backup dir cannot go outside the module's path
hierarchy, so take extra care not to delete it or copy into it.</p>
</dd>
<dt id="opt--suffix"><code>--suffix=SUFFIX</code><a href="#opt--suffix" class="tgt"></a></dt><dd>
<p>This option allows you to override the default backup suffix used with the
<a href="#opt--backup"><code>--backup</code></a> (<code>-b</code>) option. The default suffix is a <code>~</code> if no
<a href="#opt--backup-dir"><code>--backup-dir</code></a> was specified, otherwise it is an empty string.</p>
</dd>
<span id="opt-u"></span><dt id="opt--update"><code>--update</code>, <code>-u</code><a href="#opt--update" class="tgt"></a></dt><dd>
<p>This forces rsync to skip any files which exist on the destination and have