« back to all changes in this revision
Viewing changes to rsync.1
- browse files at revision 34
- compare with another revision
- download diff
- download tarball
- view history from revision 34
- Committer: Package Import Robot
- Author(s): Paul Slootman
- Date: 2013-10-27 12:01:10 UTC
- mfrom: (1.1.13) (2.1.11 sid)
- Revision ID: package-import@ubuntu.com-20131027120110-mpr03n5scqmf40mi
Tags: 3.1.0-2
fix build failure if zlib1g-dev package is not installed;
solved by building without the included zlib source and adding a
build-depends on zlib1g-dev >= 1:1.2.8
closes:32379
solved by building without the included zlib source and adding a
build-depends on zlib1g-dev >= 1:1.2.8
closes:32379
- files added:
- delete.c
- files removed:
- debian/patches/cast--1-size_t.diff
- files modified:
- .gitignore
- config.guess *
- config.sub *
added
removed
rsync.1
1
.TH "rsync" "1" "23 Sep 2011" "" ""
1
.TH "rsync" "1" "28 Sep 2013" "" ""
2
2
.SH "NAME"
3
3
rsync \- a fast, versatile, remote (and local) file\-copying tool
4
4
.SH "SYNOPSIS"
407
407
.nf
408
408
409
409
\-v, \-\-verbose increase verbosity
410
\-\-info=FLAGS fine\-grained informational verbosity
411
\-\-debug=FLAGS fine\-grained debug verbosity
412
\-\-msgs2stderr special output handling for debugging
410
413
\-q, \-\-quiet suppress non\-error messages
411
414
\-\-no\-motd suppress daemon\-mode MOTD (see caveat)
412
415
\-c, \-\-checksum skip based on checksum, not mod\-time & size
427
430
\-L, \-\-copy\-links transform symlink into referent file/dir
428
431
\-\-copy\-unsafe\-links only \(dq\&unsafe\(dq\& symlinks are transformed
429
432
\-\-safe\-links ignore symlinks that point outside the tree
433
\-\-munge\-links munge symlinks to make them safer
430
434
\-k, \-\-copy\-dirlinks transform symlink to dir into referent dir
431
435
\-K, \-\-keep\-dirlinks treat symlinked dir on receiver as dir
432
436
\-H, \-\-hard\-links preserve hard links
442
446
\-D same as \-\-devices \-\-specials
443
447
\-t, \-\-times preserve modification times
444
448
\-O, \-\-omit\-dir\-times omit directories from \-\-times
449
\-J, \-\-omit\-link\-times omit symlinks from \-\-times
445
450
\-\-super receiver attempts super\-user activities
446
451
\-\-fake\-super store/recover privileged attrs using xattrs
447
452
\-S, \-\-sparse handle sparse files efficiently
453
\-\-preallocate allocate dest files before writing
448
454
\-n, \-\-dry\-run perform a trial run with no changes made
449
455
\-W, \-\-whole\-file copy files whole (w/o delta\-xfer algorithm)
450
456
\-x, \-\-one\-file\-system don'\&t cross filesystem boundaries
461
467
\-\-delete\-delay find deletions during, delete after
462
468
\-\-delete\-after receiver deletes after transfer, not during
463
469
\-\-delete\-excluded also delete excluded files from dest dirs
470
\-\-ignore\-missing\-args ignore missing source args without error
471
\-\-delete\-missing\-args delete missing source args from destination
464
472
\-\-ignore\-errors delete even if there are I/O errors
465
473
\-\-force force deletion of dirs even if not empty
466
474
\-\-max\-delete=NUM don'\&t delete more than NUM files
471
479
\-\-delay\-updates put all updated files into place at end
472
480
\-m, \-\-prune\-empty\-dirs prune empty directory chains from file\-list
473
481
\-\-numeric\-ids don'\&t map uid/gid values by user/group name
482
\-\-usermap=STRING custom username mapping
483
\-\-groupmap=STRING custom groupname mapping
484
\-\-chown=USER:GROUP simple username/groupname mapping
474
485
\-\-timeout=SECONDS set I/O timeout in seconds
475
486
\-\-contimeout=SECONDS set daemon connection timeout in seconds
476
487
\-I, \-\-ignore\-times don'\&t skip files that match size and time
499
510
\-\-port=PORT specify double\-colon alternate port number
500
511
\-\-sockopts=OPTIONS specify custom TCP options
501
512
\-\-blocking\-io use blocking I/O for the remote shell
513
\-\-outbuf=N|L|B set out buffering to None, Line, or Block
502
514
\-\-stats give some file\-transfer stats
503
515
\-8, \-\-8\-bit\-output leave high\-bit chars unescaped in output
504
516
\-h, \-\-human\-readable output numbers in a human\-readable format
505
517
\-\-progress show progress during transfer
506
518
\-P same as \-\-partial \-\-progress
507
519
\-i, \-\-itemize\-changes output a change\-summary for all updates
520
\-M, \-\-remote\-option=OPTION send OPTION to the remote side only
508
521
\-\-out\-format=FORMAT output updates using the specified FORMAT
509
522
\-\-log\-file=FILE log what we'\&re doing to the specified FILE
510
523
\-\-log\-file\-format=FMT log updates using the specified FMT
511
524
\-\-password\-file=FILE read daemon\-access password from FILE
512
525
\-\-list\-only list the files instead of copying them
513
\-\-bwlimit=KBPS limit I/O bandwidth; KBytes per second
526
\-\-bwlimit=RATE limit socket I/O bandwidth
514
527
\-\-write\-batch=FILE write a batched update to FILE
515
528
\-\-only\-write\-batch=FILE like \-\-write\-batch but w/o updating dest
516
529
\-\-read\-batch=FILE read a batched update from FILE
530
543
531
544
\-\-daemon run as an rsync daemon
532
545
\-\-address=ADDRESS bind to the specified address
533
\-\-bwlimit=KBPS limit I/O bandwidth; KBytes per second
546
\-\-bwlimit=RATE limit socket I/O bandwidth
534
547
\-\-config=FILE specify alternate rsyncd.conf file
548
\-M, \-\-dparam=OVERRIDE override global daemon config parameter
535
549
\-\-no\-detach do not detach from the parent
536
550
\-\-port=PORT listen on alternate port number
537
551
\-\-log\-file=FILE override the \(dq\&log file\(dq\& setting
577
591
information at the end. More than two \fB\-v\fP options should only be used if
578
592
you are debugging rsync.
579
593
.IP
580
Note that the names of the transferred files that are output are done using
581
a default \fB\-\-out\-format\fP of \(dq\&%n%L\(dq\&, which tells you just the name of the
582
file and, if the item is a link, where it points. At the single \fB\-v\fP
583
level of verbosity, this does not mention when a file gets its attributes
584
changed. If you ask for an itemized list of changed attributes (either
585
\fB\-\-itemize\-changes\fP or adding \(dq\&%i\(dq\& to the \fB\-\-out\-format\fP setting), the
586
output (on the client) increases to mention all items that are changed in
587
any way. See the \fB\-\-out\-format\fP option for more details.
594
In a modern rsync, the \fB\-v\fP option is equivalent to the setting of groups
595
of \fB\-\-info\fP and \fB\-\-debug\fP options. You can choose to use these newer
596
options in addition to, or in place of using \fB\-\-verbose\fP, as any
597
fine\-grained settings override the implied settings of \fB\-v\fP. Both
598
\fB\-\-info\fP and \fB\-\-debug\fP have a way to ask for help that tells you
599
exactly what flags are set for each increase in verbosity.
600
.IP
601
.IP "\fB\-\-info=FLAGS\fP"
602
This option lets you have fine\-grained control over the
603
information
604
output you want to see. An individual flag name may be followed by a level
605
number, with 0 meaning to silence that output, 1 being the default output
606
level, and higher numbers increasing the output of that flag (for those
607
that support higher levels). Use
608
\fB\-\-info=help\fP
609
to see all the available flag names, what they output, and what flag names
610
are added for each increase in the verbose level. Some examples:
611
.IP
612
.nf
613
rsync \-a \-\-info=progress2 src/ dest/
614
rsync \-avv \-\-info=stats2,misc1,flist0 src/ dest/
615
.fi
616
617
.IP
618
Note that \fB\-\-info=name\fP\(cq\&s output is affected by the \fB\-\-out\-format\fP and
619
\fB\-\-itemize\-changes\fP (\fB\-i\fP) options. See those options for more
620
information on what is output and when.
621
.IP
622
This option was added to 3.1.0, so an older rsync on the server side might
623
reject your attempts at fine\-grained control (if one or more flags needed
624
to be send to the server and the server was too old to understand them).
625
.IP
626
.IP "\fB\-\-debug=FLAGS\fP"
627
This option lets you have fine\-grained control over the debug
628
output you want to see. An individual flag name may be followed by a level
629
number, with 0 meaning to silence that output, 1 being the default output
630
level, and higher numbers increasing the output of that flag (for those
631
that support higher levels). Use
632
\fB\-\-debug=help\fP
633
to see all the available flag names, what they output, and what flag names
634
are added for each increase in the verbose level. Some examples:
635
.IP
636
.nf
637
rsync \-avvv \-\-debug=none src/ dest/
638
rsync \-avA \-\-del \-\-debug=del2,acl src/ dest/
639
.fi
640
641
.IP
642
Note that some debug messages will only be output when \fB\-\-msgs2stderr\fP is
643
specified, especially those pertaining to I/O and buffer debugging.
644
.IP
645
This option was added to 3.1.0, so an older rsync on the server side might
646
reject your attempts at fine\-grained control (if one or more flags needed
647
to be send to the server and the server was too old to understand them).
648
.IP
649
.IP "\fB\-\-msgs2stderr\fP"
650
This option changes rsync to send all its output
651
directly to stderr rather than to send messages to the client side via the
652
protocol (which normally outputs info messages via stdout). This is mainly
653
intended for debugging in order to avoid changing the data sent via the
654
protocol, since the extra protocol data can change what is being tested.
655
Keep in mind that a daemon connection does not have a stderr channel to send
656
messages back to the client side, so if you are doing any daemon\-transfer
657
debugging using this option, you should start up a daemon using \fB\-\-no\-detach\fP
658
so that you can see the stderr output on the daemon side.
659
.IP
660
This option has the side\-effect of making stderr output get line\-buffered so
661
that the merging of the output of 3 programs happens in a more readable manner.
588
662
.IP
589
663
.IP "\fB\-q, \-\-quiet\fP"
590
664
This option decreases the amount of information you
966
1040
also ignored. Using this option in conjunction with \fB\-\-relative\fP may
967
1041
give unexpected results.
968
1042
.IP
1043
.IP "\fB\-\-munge\-links\fP"
1044
This option tells rsync to (1) modify all symlinks on
1045
the receiving side in a way that makes them unusable but recoverable (see
1046
below), or (2) to unmunge symlinks on the sending side that had been stored in
1047
a munged state. This is useful if you don\(cq\&t quite trust the source of the data
1048
to not try to slip in a symlink to a unexpected place.
1049
.IP
1050
The way rsync disables the use of symlinks is to prefix each one with the
1051
string \(dq\&/rsyncd\-munged/\(dq\&. This prevents the links from being used as long as
1052
that directory does not exist. When this option is enabled, rsync will refuse
1053
to run if that path is a directory or a symlink to a directory.
1054
.IP
1055
The option only affects the client side of the transfer, so if you need it to
1056
affect the server, specify it via \fB\-\-remote\-option\fP. (Note that in a local
1057
transfer, the client side is the sender.)
1058
.IP
1059
This option has no affect on a daemon, since the daemon configures whether it
1060
wants munged symlinks via its \(dq\&munge symlinks\(dq\& parameter. See also the
1061
\(dq\&munge\-symlinks\(dq\& perl script in the support directory of the source code.
1062
.IP
969
1063
.IP "\fB\-k, \-\-copy\-dirlinks\fP"
970
1064
This option causes the sending side to treat
971
1065
a symlink to a directory as though it were a real directory. This is
1182
1276
.RE
1183
1277
1184
1278
.IP
1279
Using octal mode numbers is also allowed:
1280
.IP
1281
.RS
1282
\-\-chmod=D2775,F664
1283
.RE
1284
1285
.IP
1185
1286
It is also legal to specify multiple \fB\-\-chmod\fP options, as each
1186
1287
additional option is just appended to the list of changes to make.
1187
1288
.IP
1241
1342
the directories on the receiving side, it is a good idea to use \fB\-O\fP.
1242
1343
This option is inferred if you use \fB\-\-backup\fP without \fB\-\-backup\-dir\fP.
1243
1344
.IP
1345
.IP "\fB\-J, \-\-omit\-link\-times\fP"
1346
This tells rsync to omit symlinks when
1347
it is preserving modification times (see \fB\-\-times\fP).
1348
.IP
1244
1349
.IP "\fB\-\-super\fP"
1245
1350
This tells the receiving side to attempt super\-user
1246
1351
activities even if the receiving rsync wasn\(cq\&t run by the super\-user. These
1269
1374
ACLs from incompatible systems.
1270
1375
.IP
1271
1376
The \fB\-\-fake\-super\fP option only affects the side where the option is used.
1272
To affect the remote side of a remote\-shell connection, specify an rsync
1273
path:
1377
To affect the remote side of a remote\-shell connection, use the
1378
\fB\-\-remote\-option\fP (\fB\-M\fP) option:
1274
1379
.IP
1275
1380
.RS
1276
\f(CW rsync \-av \-\-rsync\-path=\(dq\&rsync \-\-fake\-super\(dq\& /src/ host:/dest/\fP
1381
\f(CW rsync \-av \-M\-\-fake\-super /src/ host:/dest/\fP
1277
1382
.RE
1278
1383
1279
1384
.IP
1280
Since there is only one \(dq\&side\(dq\& in a local copy, this option affects both
1281
the sending and receiving of files. You\(cq\&ll need to specify a copy using
1282
\(dq\&localhost\(dq\& if you need to avoid this, possibly using the \(dq\&lsh\(dq\& shell
1283
script (from the support directory) as a substitute for an actual remote
1284
shell (see \fB\-\-rsh\fP).
1385
For a local copy, this option affects both the source and the destination.
1386
If you wish a local copy to enable this option just for the destination
1387
files, specify \fB\-M\-\-fake\-super\fP. If you wish a local copy to enable
1388
this option just for the source files, combine \fB\-\-fake\-super\fP with
1389
\fB\-M\-\-super\fP.
1285
1390
.IP
1286
1391
This option is overridden by both \fB\-\-super\fP and \fB\-\-no\-super\fP.
1287
1392
.IP
1292
1397
up less space on the destination. Conflicts with \fB\-\-inplace\fP because it\(cq\&s
1293
1398
not possible to overwrite data in a sparse fashion.
1294
1399
.IP
1400
.IP "\fB\-\-preallocate\fP"
1401
This tells the receiver to allocate each destination
1402
file to its eventual size before writing data to the file. Rsync will only use
1403
the real filesystem\-level preallocation support provided by Linux\(cq\&s
1404
\fBfallocate\fP(2) system call or Cygwin\(cq\&s \fBposix_fallocate\fP(3), not the slow
1405
glibc implementation that writes a zero byte into each block.
1406
.IP
1407
Without this option, larger files may not be entirely contiguous on the
1408
filesystem, but with this option rsync will probably copy more slowly. If the
1409
destination is not an extent\-supporting filesystem (such as ext4, xfs, NTFS,
1410
etc.), this option may have no positive effect at all.
1411
.IP
1295
1412
.IP "\fB\-n, \-\-dry\-run\fP"
1296
1413
This makes rsync perform a trial run that doesn\(cq\&t
1297
1414
make any changes (and produces mostly the same output as a real run). It
1379
1496
it is written, rename it to \(dq\&foo\(dq\& when it is done, and then use the option
1380
1497
\fB\-\-exclude='\&*.new'\&\fP for the rsync transfer).
1381
1498
.IP
1499
Starting with 3.1.0, rsync will skip the sender\-side removal (and output an
1500
error) if the file\(cq\&s size or modify time has not stayed unchanged.
1501
.IP
1382
1502
.IP "\fB\-\-delete\fP"
1383
1503
This tells rsync to delete extraneous files from the
1384
1504
receiving side (ones that aren\(cq\&t on the sending side), but only for the
1468
1588
\fB\-\-delete\-excluded\fP.
1469
1589
See \fB\-\-delete\fP (which is implied) for more details on file\-deletion.
1470
1590
.IP
1591
.IP "\fB\-\-ignore\-missing\-args\fP"
1592
When rsync is first processing the explicitly
1593
requested source files (e.g. command\-line arguments or \fB\-\-files\-from\fP
1594
entries), it is normally an error if the file cannot be found. This option
1595
suppresses that error, and does not try to transfer the file. This does not
1596
affect subsequent vanished\-file errors if a file was initially found to be
1597
present and later is no longer there.
1598
.IP
1599
.IP "\fB\-\-delete\-missing\-args\fP"
1600
This option takes the behavior of (the implied)
1601
\fB\-\-ignore\-missing\-args\fP option a step farther: each missing arg will become
1602
a deletion request of the corresponding destination file on the receiving side
1603
(should it exist). If the destination file is a non\-empty directory, it will
1604
only be successfully deleted if \-\-force or \-\-delete are in effect. Other than
1605
that, this option is independent of any other type of delete processing.
1606
.IP
1607
The missing source files are represented by special file\-list entries which
1608
display as a \(dq\&*missing\(dq\& entry in the \fB\-\-list\-only\fP output.
1609
.IP
1471
1610
.IP "\fB\-\-ignore\-errors\fP"
1472
1611
Tells \fB\-\-delete\fP to go ahead and delete files
1473
1612
even when there are I/O errors.
1483
1622
.IP
1484
1623
.IP "\fB\-\-max\-delete=NUM\fP"
1485
1624
This tells rsync not to delete more than NUM
1486
files or directories. If that limit is exceeded, a warning is output
1487
and rsync exits with an error code of 25 (new for 3.0.0).
1625
files or directories. If that limit is exceeded, all further deletions are
1626
skipped through the end of the transfer. At the end, rsync outputs a warning
1627
(including a count of the skipped deletions) and exits with an error code
1628
of 25 (unless some more important error condition also occurred).
1488
1629
.IP
1489
Also new for version 3.0.0, you may specify \fB\-\-max\-delete=0\fP to be warned
1630
Beginning with version 3.0.0, you may specify \fB\-\-max\-delete=0\fP to be warned
1490
1631
about any extraneous files in the destination without removing any of them.
1491
1632
Older clients interpreted this as \(dq\&unlimited\(dq\&, so if you don\(cq\&t know what
1492
1633
version the client is, you can use the less obvious \fB\-\-max\-delete=\-1\fP as
1493
1634
a backward\-compatible way to specify that no deletions be allowed (though
1494
older versions didn\(cq\&t warn when the limit was exceeded).
1635
really old versions didn\(cq\&t warn when the limit was exceeded).
1495
1636
.IP
1496
1637
.IP "\fB\-\-max\-size=SIZE\fP"
1497
1638
This tells rsync to avoid transferring any
1514
1655
Examples: \-\-max\-size=1.5mb\-1 is 1499999 bytes, and \-\-max\-size=2g+1 is
1515
1656
2147483649 bytes.
1516
1657
.IP
1658
Note that rsync versions prior to 3.1.0 did not allow \fB\-\-max\-size=0\fP.
1659
.IP
1517
1660
.IP "\fB\-\-min\-size=SIZE\fP"
1518
1661
This tells rsync to avoid transferring any
1519
1662
file that is smaller than the specified SIZE, which can help in not
1520
1663
transferring small, junk files.
1521
1664
See the \fB\-\-max\-size\fP option for a description of SIZE and other information.
1522
1665
.IP
1666
Note that rsync versions prior to 3.1.0 did not allow \fB\-\-min\-size=0\fP.
1667
.IP
1523
1668
.IP "\fB\-B, \-\-block\-size=BLOCKSIZE\fP"
1524
1669
This forces the block size used in
1525
1670
rsync\(cq\&s delta\-transfer algorithm to a fixed value. It is normally selected based on
1580
1725
.RE
1581
1726
1582
1727
.IP
1728
.IP "\fB\-M, \-\-remote\-option=OPTION\fP"
1729
This option is used for more advanced
1730
situations where you want certain effects to be limited to one side of the
1731
transfer only. For instance, if you want to pass \fB\-\-log\-file=FILE\fP and
1732
\fB\-\-fake\-super\fP to the remote system, specify it like this:
1733
.IP
1734
.RS
1735
\f(CW rsync \-av \-M \-\-log\-file=foo \-M\-\-fake\-super src/ dest/\fP
1736
.RE
1737
1738
.IP
1739
If you want to have an option affect only the local side of a transfer when
1740
it normally affects both sides, send its negation to the remote side. Like
1741
this:
1742
.IP
1743
.RS
1744
\f(CW rsync \-av \-x \-M\-\-no\-x src/ dest/\fP
1745
.RE
1746
1747
.IP
1748
Be cautious using this, as it is possible to toggle an option that will cause
1749
rsync to have a different idea about what data to expect next over the socket,
1750
and that will make it fail in a cryptic fashion.
1751
.IP
1752
Note that it is best to use a separate \fB\-\-remote\-option\fP for each option you
1753
want to pass. This makes your useage compatible with the \fB\-\-protect\-args\fP
1754
option. If that option is off, any spaces in your remote options will be split
1755
by the remote shell unless you take steps to protect them.
1756
.IP
1757
When performing a local transfer, the \(dq\&local\(dq\& side is the sender and the
1758
\(dq\&remote\(dq\& side is the receiver.
1759
.IP
1760
Note some versions of the popt option\-parsing library have a bug in them that
1761
prevents you from using an adjacent arg with an equal in it next to a short
1762
option letter (e.g. \f(CW\-M\-\-log\-file=/tmp/foo\fP. If this bug affects your
1763
version of popt, you can use the version of popt that is included with rsync.
1764
.IP
1583
1765
.IP "\fB\-C, \-\-cvs\-exclude\fP"
1584
1766
This is a useful shorthand for excluding a
1585
1767
broad range of files that you often don\(cq\&t want to transfer between
1776
1958
from the local to the remote character\-set. The translation happens before
1777
1959
wild\-cards are expanded. See also the \fB\-\-files\-from\fP option.
1778
1960
.IP
1961
You may also control this option via the RSYNC_PROTECT_ARGS environment
1962
variable. If this variable has a non\-zero value, this option will be enabled
1963
by default, otherwise it will be disabled by default. Either state is
1964
overridden by a manually specified positive or negative version of this option
1965
(note that \fB\-\-no\-s\fP and \fB\-\-no\-protect\-args\fP are the negative versions).
1966
Since this option was first introduced in 3.0.0, you\(cq\&ll need to make sure it\(cq\&s
1967
disabled if you ever need to interact with a remote rsync that is older than
1968
that.
1969
.IP
1970
Rsync can also be configured (at build time) to have this option enabled by
1971
default (with is overridden by both the environment and the command\-line).
1972
This option will eventually become a new default setting at some
1973
as\-yet\-undetermined point in the future.
1974
.IP
1779
1975
.IP "\fB\-T, \-\-temp\-dir=DIR\fP"
1780
1976
This option instructs rsync to use DIR as a
1781
1977
scratch directory when creating temporary copies of the files transferred
1816
2012
has an identical size and modified\-time, or a similarly\-named file. If
1817
2013
found, rsync uses the fuzzy basis file to try to speed up the transfer.
1818
2014
.IP
2015
If the option is repeated, the fuzzy scan will also be done in any matching
2016
alternate destination directories that are specified via \fB\-\-compare\-dest\fP,
2017
\fB\-\-copy\-dest\fP, or \fB\-\-link\-dest\fP.
2018
.IP
1819
2019
Note that the use of the \fB\-\-delete\fP option might get rid of any potential
1820
2020
fuzzy\-match files, so either use \fB\-\-delete\-after\fP or specify some
1821
2021
filename exclusions if you need to prevent this.
1828
2028
sender\(cq\&s file, the file will NOT be transferred to the destination
1829
2029
directory. This is useful for creating a sparse backup of just files that
1830
2030
have changed from an earlier backup.
2031
This option is typically used to copy into an empty (or newly created)
2032
directory.
1831
2033
.IP
1832
2034
Beginning in version 2.6.4, multiple \fB\-\-compare\-dest\fP directories may be
1833
2035
provided, which will cause rsync to search the list in the order specified
1840
2042
If \fIDIR\fP is a relative path, it is relative to the destination directory.
1841
2043
See also \fB\-\-copy\-dest\fP and \fB\-\-link\-dest\fP.
1842
2044
.IP
2045
NOTE: beginning with version 3.1.0, rsync will remove a file from a non\-empty
2046
destination hierarchy if an exact match is found in one of the compare\-dest
2047
hierarchies (making the end result more closely match a fresh copy).
2048
.IP
1843
2049
.IP "\fB\-\-copy\-dest=DIR\fP"
1844
2050
This option behaves like \fB\-\-compare\-dest\fP, but
1845
2051
rsync will also copy unchanged files found in \fIDIR\fP to the destination
1882
2088
selected to try to speed up the transfer.
1883
2089
.IP
1884
2090
This option works best when copying into an empty destination hierarchy, as
1885
rsync treats existing files as definitive (so it never looks in the link\-dest
1886
dirs when a destination file already exists), and as malleable (so it might
1887
change the attributes of a destination file, which affects all the hard\-linked
1888
versions).
2091
existing files may get their attributes tweaked, and that can affect alternate
2092
destination files via hard\-links. Also, itemizing of changes can get a bit
2093
muddled. Note that prior to version 3.1.0, an alternate\-directory exact match
2094
would never be found (nor linked into the destination) when a destination file
2095
already exists.
1889
2096
.IP
1890
2097
Note that if you combine this option with \fB\-\-ignore\-times\fP, rsync will not
1891
2098
link any files together because it only links identical files together as a
1943
2150
version of rsync):
1944
2151
.IP
1945
2152
\fB7z\fP
2153
\fBace\fP
1946
2154
\fBavi\fP
1947
2155
\fBbz2\fP
1948
2156
\fBdeb\fP
2157
\fBgpg\fP
1949
2158
\fBgz\fP
1950
2159
\fBiso\fP
1951
2160
\fBjpeg\fP
1952
2161
\fBjpg\fP
2162
\fBlz\fP
2163
\fBlzma\fP
2164
\fBlzo\fP
1953
2165
\fBmov\fP
1954
2166
\fBmp3\fP
1955
2167
\fBmp4\fP
1956
2168
\fBogg\fP
2169
\fBpng\fP
2170
\fBrar\fP
1957
2171
\fBrpm\fP
2172
\fBrzip\fP
1958
2173
\fBtbz\fP
1959
2174
\fBtgz\fP
2175
\fBtlz\fP
2176
\fBtxz\fP
2177
\fBxz\fP
1960
2178
\fBz\fP
1961
2179
\fBzip\fP
1962
2180
.IP
1982
2200
the chroot setting affects rsync\(cq\&s ability to look up the names of the
1983
2201
users and groups and what you can do about it.
1984
2202
.IP
2203
.IP "\fB\-\-usermap=STRING, \-\-groupmap=STRING\fP"
2204
These options allow you to
2205
specify users and groups that should be mapped to other values by the
2206
receiving side. The \fBSTRING\fP is one or more \fBFROM\fP:\fBTO\fP pairs of
2207
values separated by commas. Any matching \fBFROM\fP value from the sender is
2208
replaced with a \fBTO\fP value from the receiver. You may specify usernames
2209
or user IDs for the \fBFROM\fP and \fBTO\fP values, and the \fBFROM\fP value may
2210
also be a wild\-card string, which will be matched against the sender\(cq\&s
2211
names (wild\-cards do NOT match against ID numbers, though see below for
2212
why a \(cq\&*\(cq\& matches everything). You may instead specify a range of ID
2213
numbers via an inclusive range: LOW\-HIGH. For example:
2214
.IP
2215
.nf
2216
\-\-usermap=0\-99:nobody,wayne:admin,*:normal \-\-groupmap=usr:1,1:usr
2217
.fi
2218
2219
.IP
2220
The first match in the list is the one that is used. You should specify
2221
all your user mappings using a single \fB\-\-usermap\fP option, and/or all
2222
your group mappings using a single \fB\-\-groupmap\fP option.
2223
.IP
2224
Note that the sender\(cq\&s name for the 0 user and group are not transmitted
2225
to the receiver, so you should either match these values using a 0, or use
2226
the names in effect on the receiving side (typically \(dq\&root\(dq\&). All other
2227
\fBFROM\fP names match those in use on the sending side. All \fBTO\fP names
2228
match those in use on the receiving side.
2229
.IP
2230
Any IDs that do not have a name on the sending side are treated as having an
2231
empty name for the purpose of matching. This allows them to be matched via
2232
a \(dq\&*\(dq\& or using an empty name. For instance:
2233
.IP
2234
.nf
2235
\-\-usermap=:nobody \-\-groupmap=*:nobody
2236
.fi
2237
2238
.IP
2239
When the \fB\-\-numeric\-ids\fP option is used, the sender does not send any
2240
names, so all the IDs are treated as having an empty name. This means that
2241
you will need to specify numeric \fBFROM\fP values if you want to map these
2242
nameless IDs to different values.
2243
.IP
2244
For the \fB\-\-usermap\fP option to have any effect, the \fB\-o\fP (\fB\-\-owner\fP)
2245
option must be used (or implied), and the receiver will need to be running
2246
as a super\-user (see also the \fB\-\-fake\-super\fP option). For the \fB\-\-groupmap\fP
2247
option to have any effect, the \fB\-g\fP (\fB\-\-groups\fP) option must be used
2248
(or implied), and the receiver will need to have permissions to set that
2249
group.
2250
.IP
2251
.IP "\fB\-\-chown=USER:GROUP\fP"
2252
This option forces all files to be owned by USER
2253
with group GROUP. This is a simpler interface than using \fB\-\-usermap\fP and
2254
\fB\-\-groupmap\fP directly, but it is implemented using those options internally,
2255
so you cannot mix them. If either the USER or GROUP is empty, no mapping for
2256
the omitted user/group will occur. If GROUP is empty, the trailing colon may
2257
be omitted, but if USER is empty, a leading colon must be supplied.
2258
.IP
2259
If you specify \(dq\&\-\-chown=foo:bar, this is exactly the same as specifying
2260
\(dq\&\-\-usermap=*:foo \-\-groupmap=*:bar\(dq\&, only easier.
2261
.IP
1985
2262
.IP "\fB\-\-timeout=TIMEOUT\fP"
1986
2263
This option allows you to set a maximum I/O
1987
2264
timeout in seconds. If no data is transferred for the specified time
2024
2301
blocking I/O, otherwise it defaults to using non\-blocking I/O. (Note that
2025
2302
ssh prefers non\-blocking I/O.)
2026
2303
.IP
2304
.IP "\fB\-\-outbuf=MODE\fP"
2305
This sets the output buffering mode. The mode can be
2306
None (aka Unbuffered), Line, or Block (aka Full). You may specify as little
2307
as a single letter for the mode, and use upper or lower case.
2308
.IP
2309
The main use of this option is to change Full buffering to Line buffering
2310
when rsync\(cq\&s output is going to a file or pipe.
2311
.IP
2027
2312
.IP "\fB\-i, \-\-itemize\-changes\fP"
2028
2313
Requests a simple itemized list of the
2029
2314
changes that are being made to each file, including attribute changes.
2122
2407
rsync client outputs to the user on a per\-update basis. The format is a
2123
2408
text string containing embedded single\-character escape sequences prefixed
2124
2409
with a percent (%) character. A default format of \(dq\&%n%L\(dq\& is assumed if
2125
\fB\-v\fP is specified (which reports the name
2410
either \fB\-\-info=name\fP or \fB\-v\fP is specified (this tells you just the name
2126
2411
of the file and, if the item is a link, where it points). For a full list
2127
2412
of the possible escape characters, see the \(dq\&log format\(dq\& setting in the
2128
2413
rsyncd.conf manpage.
2129
2414
.IP
2130
Specifying the \fB\-\-out\-format\fP option
2131
will mention each file, dir, etc. that gets updated in a significant
2415
Specifying the \fB\-\-out\-format\fP option implies the \fB\-\-info=name\fP option,
2416
which will mention each file, dir, etc. that gets updated in a significant
2132
2417
way (a transferred file, a recreated symlink/device, or a touched
2133
2418
directory). In addition, if the itemize\-changes escape (%i) is included in
2134
2419
the string (e.g. if the \fB\-\-itemize\-changes\fP option was used), the logging
2155
2440
happening:
2156
2441
.IP
2157
2442
.nf
2158
rsync \-av \-\-rsync\-path=\(dq\&rsync \-\-log\-file=/tmp/rlog\(dq\& src/ dest/
2443
rsync \-av \-\-remote\-option=\-\-log\-file=/tmp/rlog src/ dest/
2159
2444
.fi
2160
2445
2161
2446
.IP
2176
2461
.IP "\fB\-\-stats\fP"
2177
2462
This tells rsync to print a verbose set of statistics
2178
2463
on the file transfer, allowing you to tell how effective rsync\(cq\&s delta\-transfer
2179
algorithm is for your data.
2464
algorithm is for your data. This option is equivalent to \fB\-\-info=stats2\fP
2465
if combined with 0 or 1 \fB\-v\fP options, or \fB\-\-info=stats3\fP if combined
2466
with 2 or more \fB\-v\fP options.
2180
2467
.IP
2181
2468
The current statistics are as follows:
2182
2469
.RS
2183
2470
.IP o
2184
2471
\fBNumber of files\fP is the count of all \(dq\&files\(dq\& (in the generic
2185
sense), which includes directories, symlinks, etc.
2186
.IP o
2187
\fBNumber of files transferred\fP is the count of normal files that
2188
were updated via rsync\(cq\&s delta\-transfer algorithm, which does not include created
2189
dirs, symlinks, etc.
2472
sense), which includes directories, symlinks, etc. The total count will
2473
be followed by a list of counts by filetype (if the total is non\-zero).
2474
For example: \(dq\&(reg: 5, dir: 3, link: 2, dev: 1, special: 1)\(dq\& lists the
2475
totals for regular files, directories, symlinks, devices, and special
2476
files. If any of value is 0, it is completely omitted from the list.
2477
.IP o
2478
\fBNumber of created files\fP is the count of how many \(dq\&files\(dq\& (generic
2479
sense) were created (as opposed to updated). The total count will be
2480
followed by a list of counts by filetype (if the total is non\-zero).
2481
.IP o
2482
\fBNumber of deleted files\fP is the count of how many \(dq\&files\(dq\& (generic
2483
sense) were created (as opposed to updated). The total count will be
2484
followed by a list of counts by filetype (if the total is non\-zero).
2485
Note that this line is only output if deletions are in effect, and only
2486
if protocol 31 is being used (the default for rsync 3.1.x).
2487
.IP o
2488
\fBNumber of regular files transferred\fP is the count of normal files
2489
that were updated via rsync\(cq\&s delta\-transfer algorithm, which does not
2490
include dirs, symlinks, etc. Note that rsync 3.1.0 added the word
2491
\(dq\®ular\(dq\& into this heading.
2190
2492
.IP o
2191
2493
\fBTotal file size\fP is the total sum of all file sizes in the transfer.
2192
2494
This does not count any size for directories or special files, but does
2237
2539
.IP
2238
2540
.IP "\fB\-h, \-\-human\-readable\fP"
2239
2541
Output numbers in a more human\-readable format.
2240
This makes big numbers output using larger units, with a K, M, or G suffix. If
2241
this option was specified once, these units are K (1000), M (1000*1000), and
2242
G (1000*1000*1000); if the option is repeated, the units are powers of 1024
2243
instead of 1000.
2542
There are 3 possible levels: (1) output numbers with a separator between each
2543
set of 3 digits (either a comma or a period, depending on if the decimal point
2544
is represented by a period or a comma); (2) output numbers in units of 1000
2545
(with a character suffix for larger units \-\- see below); (3) output numbers in
2546
units of 1024.
2547
.IP
2548
The default is human\-readable level 1. Each \fB\-h\fP option increases the level
2549
by one. You can take the level down to 0 (to output numbers as pure digits) by
2550
specifing the \fB\-\-no\-human\-readable\fP (\fB\-\-no\-h\fP) option.
2551
.IP
2552
The unit letters that are appended in levels 2 and 3 are: K (kilo), M (mega),
2553
G (giga), or T (tera). For example, a 1234567\-byte file would output as 1.23M
2554
in level\-2 (assuming that a period is your local decimal point).
2555
.IP
2556
Backward compatibility note: versions of rsync prior to 3.1.0 do not support
2557
human\-readable level 1, and they default to level 0. Thus, specifying one or
2558
two \fB\-h\fP options will behave in a comparable manner in old and new versions
2559
as long as you didn\(cq\&t specify a \fB\-\-no\-h\fP option prior to one or more \fB\-h\fP
2560
options. See the \fB\-\-list\-only\fP option for one difference.
2244
2561
.IP
2245
2562
.IP "\fB\-\-partial\fP"
2246
2563
By default, rsync will delete any partially
2380
2697
This option tells rsync to print information
2381
2698
showing the progress of the transfer. This gives a bored user
2382
2699
something to watch.
2383
Implies \fB\-\-verbose\fP if it wasn\(cq\&t already specified.
2700
With a modern rsync this is the same as specifying
2701
\fB\-\-info=flist2,name,progress\fP, but any user\-supplied settings for those
2702
info flags takes precedence (e.g. \(dq\&\-\-info=flist0 \-\-progress\(dq\&).
2384
2703
.IP
2385
2704
While rsync is transferring a regular file, it updates a progress line that
2386
2705
looks like this:
2406
2725
summary line that looks like this:
2407
2726
.IP
2408
2727
.nf
2409
1238099 100% 146.38kB/s 0:00:08 (xfer#5, to\-check=169/396)
2728
1,238,099 100% 146.38kB/s 0:00:08 (xfr#5, to\-chk=169/396)
2410
2729
.fi
2411
2730
2412
2731
.IP
2413
In this example, the file was 1238099 bytes long in total, the average rate
2732
In this example, the file was 1,238,099 bytes long in total, the average rate
2414
2733
of transfer for the whole file was 146.38 kilobytes per second over the 8
2415
2734
seconds that it took to complete, it was the 5th transfer of a regular file
2416
2735
during the current rsync session, and there are 169 more files for the
2417
2736
receiver to check (to see if they are up\-to\-date or not) remaining out of
2418
2737
the 396 total files in the file\-list.
2419
2738
.IP
2739
In an incremental recursion scan, rsync won\(cq\&t know the total number of files
2740
in the file\-list until it reaches the ends of the scan, but since it starts to
2741
transfer files during the scan, it will display a line with the text \(dq\&ir\-chk\(dq\&
2742
(for incremental recursion check) instead of \(dq\&to\-chk\(dq\& until the point that it
2743
knows the full size of the list, at which point it will switch to using
2744
\(dq\&to\-chk\(dq\&. Thus, seeing \(dq\&ir\-chk\(dq\& lets you know that the total count of files
2745
in the file list is still going to increase (and each time it does, the count
2746
of files left to check will increase by the number of the files added to the
2747
list).
2748
.IP
2420
2749
.IP "\fB\-P\fP"
2421
2750
The \fB\-P\fP option is equivalent to \fB\-\-partial\fP \fB\-\-progress\fP. Its
2422
2751
purpose is to make it much easier to specify these two options for a long
2423
2752
transfer that may be interrupted.
2424
2753
.IP
2425
.IP "\fB\-\-password\-file\fP"
2426
This option allows you to provide a password in a
2427
file for accessing an rsync daemon. The file must not be world readable.
2428
It should contain just the password as the first line of the file (all
2429
other lines are ignored).
2754
There is also a \fB\-\-info=progress2\fP option that outputs statistics based
2755
on the whole transfer, rather than individual files. Use this flag without
2756
outputting a filename (e.g. avoid \fB\-v\fP or specify \fB\-\-info=name0\fP if you
2757
want to see how the transfer is doing without scrolling the screen with a
2758
lot of names. (You don\(cq\&t need to specify the \fB\-\-progress\fP option in
2759
order to use \fB\-\-info=progress2\fP.)
2760
.IP
2761
.IP "\fB\-\-password\-file=FILE\fP"
2762
This option allows you to provide a password for
2763
accessing an rsync daemon via a file or via standard input if \fBFILE\fP is
2764
\fB\-\fP. The file should contain just the password on the first line (all other
2765
lines are ignored). Rsync will exit with an error if \fBFILE\fP is world
2766
readable or if a root\-run rsync command finds a non\-root\-owned file.
2430
2767
.IP
2431
2768
This option does not supply a password to a remote shell transport such as
2432
2769
ssh; to learn how to do that, consult the remote shell\(cq\&s documentation.
2451
2788
.fi
2452
2789
2453
2790
.IP
2791
Starting with rsync 3.1.0, the sizes output by \fB\-\-list\-only\fP are affected
2792
by the \fB\-\-human\-readable\fP option. By default they will contain digit
2793
separators, but higher levels of readability will output the sizes with
2794
unit suffixes. Note also that the column width for the size output has
2795
increased from 11 to 14 characters for all human\-readable levels. Use
2796
\fB\-\-no\-h\fP if you want just digits in the sizes, and the old column width
2797
of 11 characters.
2798
.IP
2454
2799
Compatibility note: when requesting a remote listing of files from an rsync
2455
2800
that is version 2.6.3 or older, you may encounter an error if you ask for a
2456
2801
non\-recursive listing. This is because a file listing implies the \fB\-\-dirs\fP
2459
2804
need to expand a directory\(cq\&s content), or turn on recursion and exclude
2460
2805
the content of subdirectories: \fB\-r \-\-exclude='\&/*/*'\&\fP.
2461
2806
.IP
2462
.IP "\fB\-\-bwlimit=KBPS\fP"
2463
This option allows you to specify a maximum
2464
transfer rate in kilobytes per second. This option is most effective when
2465
using rsync with large files (several megabytes and up). Due to the nature
2466
of rsync transfers, blocks of data are sent, then if rsync determines the
2467
transfer was too fast, it will wait before sending the next data block. The
2468
result is an average transfer rate equaling the specified limit. A value
2469
of zero specifies no limit.
2807
.IP "\fB\-\-bwlimit=RATE\fP"
2808
This option allows you to specify the maximum transfer
2809
rate for the data sent over the socket, specified in units per second. The
2810
RATE value can be suffixed with a string to indicate a size multiplier, and may
2811
be a fractional value (e.g. \(dq\&\fB\-\-bwlimit=1.5m\fP\(dq\&). If no suffix is specified,
2812
the value will be assumed to be in units of 1024 bytes (as if \(dq\&K\(dq\& or \(dq\&KiB\(dq\& had
2813
been appended). See the \fB\-\-max\-size\fP option for a description of all the
2814
available suffixes. A value of zero specifies no limit.
2815
.IP
2816
For backward\-compatibility reasons, the rate limit will be rounded to the
2817
nearest KiB unit, so no rate smaller than 1024 bytes per second is possible.
2818
.IP
2819
Rsync writes data over the socket in blocks, and this option both limits the
2820
size of the blocks that rsync writes, and tries to keep the average transfer
2821
rate at the requested limit. Some \(dq\&burstiness\(dq\& may be seen where rsync writes
2822
out a block of data and then sleeps to bring the average rate into compliance.
2823
.IP
2824
Due to the internal buffering of data, the \fB\-\-progress\fP option may not be an
2825
accurate reflection on how fast the data is being sent. This is because some
2826
files can show up as being rapidly sent when the data is quickly buffered,
2827
while other can show up as very slow when the flushing of the output buffer
2828
occurs. This may be fixed in a future version.
2470
2829
.IP
2471
2830
.IP "\fB\-\-write\-batch=FILE\fP"
2472
2831
Record a file that can later be applied to
2548
2907
is the case.
2549
2908
.IP
2550
2909
.IP "\fB\-\-checksum\-seed=NUM\fP"
2551
Set the checksum seed to the integer
2552
NUM. This 4 byte checksum seed is included in each block and file
2553
checksum calculation. By default the checksum seed is generated
2554
by the server and defaults to the current
2910
Set the checksum seed to the integer NUM. This 4
2911
byte checksum seed is included in each block and MD4 file checksum calculation
2912
(the more modern MD5 file checksums don\(cq\&t use a seed). By default the checksum
2913
seed is generated by the server and defaults to the current
2555
2914
\f(CWtime()\fP
2556
\&. This option
2557
is used to set a specific checksum seed, which is useful for
2558
applications that want repeatable block and file checksums, or
2559
in the case where the user wants a more random checksum seed.
2560
Setting NUM to 0 causes rsync to use the default of
2915
\&. This
2916
option is used to set a specific checksum seed, which is useful for
2917
applications that want repeatable block checksums, or in the case where the
2918
user wants a more random checksum seed. Setting NUM to 0 causes rsync to use
2919
the default of
2561
2920
\f(CWtime()\fP
2562
2921
for checksum seed.
2563
2564
.PP
2922
.IP
2565
2923
.SH "DAEMON OPTIONS"
2566
2924
2567
2925
.PP
2586
2944
makes virtual hosting possible in conjunction with the \fB\-\-config\fP option.
2587
2945
See also the \(dq\&address\(dq\& global option in the rsyncd.conf manpage.
2588
2946
.IP
2589
.IP "\fB\-\-bwlimit=KBPS\fP"
2590
This option allows you to specify a maximum
2591
transfer rate in kilobytes per second for the data the daemon sends.
2592
The client can still specify a smaller \fB\-\-bwlimit\fP value, but their
2593
requested value will be rounded down if they try to exceed it. See the
2594
client version of this option (above) for some extra details.
2947
.IP "\fB\-\-bwlimit=RATE\fP"
2948
This option allows you to specify the maximum transfer
2949
rate for the data the daemon sends over the socket. The client can still
2950
specify a smaller \fB\-\-bwlimit\fP value, but no larger value will be allowed.
2951
See the client version of this option (above) for some extra details.
2595
2952
.IP
2596
2953
.IP "\fB\-\-config=FILE\fP"
2597
2954
This specifies an alternate config file than
2600
2957
a remote shell program and the remote user is not the super\-user; in that case
2601
2958
the default is rsyncd.conf in the current directory (typically $HOME).
2602
2959
.IP
2960
.IP "\fB\-M, \-\-dparam=OVERRIDE\fP"
2961
This option can be used to set a daemon\-config
2962
parameter when starting up rsync in daemon mode. It is equivalent to adding
2963
the parameter at the end of the global settings prior to the first module\(cq\&s
2964
definition. The parameter names can be specified without spaces, if you so
2965
desire. For instance:
2966
.IP
2967
.nf
2968
rsync \-\-daemon \-M pidfile=/path/rsync.pid
2969
.fi
2970
2971
.IP
2603
2972
.IP "\fB\-\-no\-detach\fP"
2604
2973
When running as a daemon, this option instructs
2605
2974
rsync to not detach itself and become a background process. This
3478
3847
.IP "\fBRSYNC_ICONV\fP"
3479
3848
Specify a default \fB\-\-iconv\fP setting using this
3480
3849
environment variable. (First supported in 3.0.0.)
3850
.IP "\fBRSYNC_PROTECT_ARGS\fP"
3851
Specify a non\-zero numeric value if you want the
3852
\fB\-\-protect\-args\fP option to be enabled by default, or a zero value to make
3853
sure that it is disabled by default. (First supported in 3.1.0.)
3481
3854
.IP "\fBRSYNC_RSH\fP"
3482
3855
The RSYNC_RSH environment variable allows you to
3483
3856
override the default shell used as the transport for rsync. Command line
3531
3904
.SH "VERSION"
3532
3905
3533
3906
.PP
3534
This man page is current for version 3.0.9 of rsync.
3907
This man page is current for version 3.1.0 of rsync.
3535
3908
.PP
3536
3909
.SH "INTERNAL OPTIONS"
3537
3910
3547
3920
.SH "CREDITS"
3548
3921
3549
3922
.PP
3550
rsync is distributed under the GNU public license. See the file
3923
rsync is distributed under the GNU General Public License. See the file
3551
3924
COPYING for details.
3552
3925
.PP
3553
3926
A WEB site is available at
Loggerhead is a web-based interface for Breezy
Version: 2.0.1