- Add link targets for all option choices, not just the first one.
- Tweak cross-link arg format.
- Add more links, including some in the latest NEWS.
- Split out a few numbered lists.
### BEHAVIOR CHANGES:
- A new form of arg protection was added that works similarly to the older
- `--protect-args` (`-s`) option but in a way that avoids breaking things like
- rrsync (the restricted rsync script): rsync now uses backslash escaping for
- sending "shell-active" characters to the remote shell. This includes spaces,
- so fetching a remote file via a simple quoted filename value now works by
- default without any extra quoting:
+ [`--protect-args`](rsync.1#opt) (`-s`) option but in a way that avoids
+ breaking things like rrsync (the restricted rsync script): rsync now uses
+ backslash escaping for sending "shell-active" characters to the remote
+ shell. This includes spaces, so fetching a remote file via a simple quoted
+ filename value now works by default without any extra quoting:
```shell
rsync -aiv host:'a simple file.pdf' .
```
Wildcards are not escaped in filename args, but they are escaped in options
- like the `--suffix` and `--usermap` values. If your rsync script depends on
- the old arg-splitting behavior, either run it with the `--old-args` option
- or `export RSYNC_OLD_ARGS=1` in the script's environment.
+ like the [`--suffix`](rsync.1#opt) and [`--usermap`](rsync.1#opt) values.
+ If your rsync script depends on the old arg-splitting behavior, either run
+ it with the [`--old-args`](rsync.1#opt) option or `export RSYNC_OLD_ARGS=1`
+ in the script's environment.
- A long-standing bug was preventing rsync from figuring out the current
locale's decimal point character, which made rsync always output numbers
### BUG FIXES:
- - Fixed a bug with `--inplace` + `--sparse` (and a lack of `--whole-file`)
- where the destination file could get reconstructed with bogus data. Since
- the bug can also be avoided by using (the seemingly redundant) `--no-W` on
- the receiving side, the latest rsync will now send `--no-W` to a remote
- receiver when this option combination occurs. If your client rsync is not
- new enough to do this for you (or if you're just paranoid), you can manually
- specify `--no-W -M--no-W` (when not using `--whole-file`) to make sure the
+ - Fixed a bug with [`--inplace`](rsync.1#opt) + [`--sparse`](rsync.1#opt) (and
+ a lack of [`--whole-file`](rsync.1#opt)) where the destination file could
+ get reconstructed with bogus data. Since the bug can also be avoided by
+ using (the seemingly redundant) [`--no-W`](rsync.1#opt) on the receiving
+ side, the latest rsync will now send `--no-W` to a remote receiver when this
+ option combination occurs. If your client rsync is not new enough to do
+ this for you (or if you're just paranoid), you can manually specify `--no-W
+ -M--no-W` (when not using [`--whole-file`](rsync.1#opt)) to make sure the
bug is avoided.
- - Fixed a bug with `--mkpath` if a single-file copy specifies an existing
- destination dir with a non-existing destination filename.
+ - Fixed a bug with [`--mkpath`](rsync.1#opt) if a single-file copy specifies
+ an existing destination dir with a non-existing destination filename.
- Fixed `--update -vv` to output "is uptodate" instead of "is newer" messages
- for files that are being skipped due to an identical modify time. (This
- was a new output quirk in 3.2.3.)
+ for files that are being skipped due to an identical modify time. (This was
+ a new output quirk in 3.2.3.)
- When doing an append transfer, the sending side's file must not get shorter
or it is skipped. Fixes a crash that could occur when the size changes to 0
in the middle of the send negotiations.
- - When dealing with special files (see `--specials`) in an alt-dest hierarchy,
- rsync now checks the non-permission mode bits to ensure that the 2 special
- files are really the same before hard-linking them together.
+ - When dealing with special files (see [`--specials`](rsync.1#opt)) in an
+ alt-dest hierarchy, rsync now checks the non-permission mode bits to ensure
+ that the 2 special files are really the same before hard-linking them
+ together.
- - Fixed a bug where `--delay-updates` with stale partial data could cause a
- file to fail to update.
+ - Fixed a bug where [`--delay-updates`](rsync.1#opt) with stale partial data
+ could cause a file to fail to update.
- - Fixed a few places that would output an INFO message with `--info=NAME` that
- should only have been output given `--verbose` or `--itemize-changes`.
+ - Fixed a few places that would output an INFO message with
+ [`--info=NAME`](rsync.1#opt) that should only have been output given
+ [`--verbose`](rsync.1#opt) or [`--itemize-changes`](rsync.1#opt).
- - Avoid a weird failure if you run a local copy with a (useless) `--rsh`
- option that contains a `V` in the command.
+ - Avoid a weird failure if you run a local copy with a (useless)
+ [`--rsh`](rsync.1#opt) option that contains a `V` in the command.
- Fixed a long-standing compression bug where the compression level of the
first file transferred affected the level for all future files. Also, the
per-file compression skipping has apparently never worked, so it is now
documented as being ineffective.
- - Improved how the `--stop-at`, `--stop-after`, and `--time-limit` options
- check to see if the allowed time is over, which should make rsync exit more
- consistently.
+ - Improved how the [`--stop-at`](rsync.1#opt), [`--stop-after`](rsync.1#opt),
+ and (the deprecated) [`--time-limit`](rsync.1#opt) options check to see if
+ the allowed time is over, which should make rsync exit more consistently.
- - Tweak --progress to display "??:??:??" when the time-remaining value is
- so large as to be meaningless.
+ - Tweak --progress to display "`??:??:??`" when the time-remaining value is so
+ large as to be meaningless.
### ENHANCEMENTS:
- Use openssl's `-verify_hostname` option in the rsync-ssl script.
- - Added extra info to the "FILENAME exists" output of `--ignore-existing` when
- `--info=skip2` is used. The skip message becomes "FILENAME exists (INFO)"
- where the INFO is one of "type change", "sum change" (requires `-c`), "file
- change" (based on the quick check), "attr change", or "uptodate". Prior
- versions only supported `--info=skip1`.
+ - Added extra info to the "FILENAME exists" output of
+ [`--ignore-existing`](rsync.1#opt) when [`--info=skip2`](rsync.1#opt) is
+ used. The skip message becomes "FILENAME exists (INFO)" where the INFO is
+ one of "type change", "sum change" (requires [`--checksum`](rsync.1#opt)),
+ "file change" (based on the quick check), "attr change", or "uptodate".
+ Prior versions only supported `--info=skip1`.
- - Added the `--fsync` option (promoted from the patches repo).
+ - Added the [`--fsync`](rsync.1#opt) option (promoted from the patches repo).
- Reduced memory usage for an incremental transfer that has a bunch of small
directories.
- The rsync daemon can now handle a client address with an implied "%scope"
suffix.
- - Added support for `--atimes` on macOS and fixed a bug where it wouldn't work
- without `--times`.
+ - Added support for [`--atimes`](rsync.1#opt) on macOS and fixed a bug where
+ it wouldn't work without [`--times`](rsync.1#opt).
- Rsync can now update the xattrs on a read-only file when your user can
temporarily add user-write permission to the file. (It always worked for a
root transfer.)
- - Rsync can now work around an `--inplace` update of a file that is being
- refused due to the Linux fs.protected_regular sysctl setting.
+ - Rsync can now work around an [`--inplace`](rsync.1#opt) update of a file
+ that is being refused due to the Linux fs.protected_regular sysctl setting.
- - When `--chown`, `--usermap`, or `--groupmap` is specified, rsync now makes
- sure that the appropriate `--owner` and/or `--group` option is enabled.
+ - When [`--chown`](rsync.1#opt), [`--usermap`](rsync.1#opt), or
+ [`--groupmap`](rsync.1#opt), is specified, rsync now makes sure that the
+ appropriate [`--owner`](rsync.1#opt) and/or [`--group`](rsync.1#opt) options
+ are enabled.
- - Added the `--info=NONREG` setting to control if rsync should warn about
- non-regular files in the transfer. This is enabled by default (keeping the
- behavior the same as before), so specifying `--info=nonreg0` can be used to
- turn the warnings off.
+ - Added the [`--info=NONREG`](rsync.1#opt) setting to control if rsync should
+ warn about non-regular files in the transfer. This is enabled by default
+ (keeping the behavior the same as before), so specifying `--info=nonreg0`
+ can be used to turn the warnings off.
- More ASM optimizations from Shark64.
- Transformed rrsync into a python script with improvements:
- Security has been beefed up.
- The known rsync options were updated to include recent additions.
- - Make rrsync reject `-L`, `-K`, & `-k` by default to make it harder to
+ - Make rrsync reject [`--copy-links`](rsync.1#opt) (`-L`),
+ [`--copy-dirlinks`](rsync.1#opt) (`-k`), &
+ [`--keep-dirlinks`](rsync.1#opt) (`-K`) by default to make it harder to
exploit any out-of-subdir symlinks.
- - A new rrsync option of `-munge` tells rrsync to always enable rsync's
- `--munge-links` option on the server side.
- - A new rrsync option of `-no-lock` disables a new single-use locking idiom
- that is the default when `-ro` is not used (useful with `-munge`).
- - A new rrsync option of `-no-del` disables all `--remove*` and `--delete*`
- options on the server side.
+ - A new rrsync option of [`-munge`](rrsync.1#opt) tells rrsync to always
+ enable rsync's [`--munge-links`](rsync.1#opt) option on the server side.
+ - A new rrsync option of [`-no-lock`](rrsync.1#opt) disables a new
+ single-use locking idiom that is the default when [`-ro`](rrsync.1#opt) is
+ not used (useful with [`-munge`](rrsync.1#opt)).
+ - A new rrsync option of [`-no-del`](rrsync.1#opt) disables all `--remove*`
+ and `--delete*` rsync options on the server side.
- The log format has been tweaked slightly to add seconds to the timestamp
and to output the command executed as a tuple (making the args clearer).
- An rrsync.1 man page was added (in the support dir with rrsync).
- Fixed a bug in the xattr code that was not leaving room for the "rsync."
prefix in some instances where it needed to be added.
- - Restored the ability to use `--bwlimit=0` to specify no bandwidth limit. (It
- was accidentally broken in 3.2.2.)
+ - Restored the ability to use [`--bwlimit=0`](rsync.1#opt) to specify no
+ bandwidth limit. (It was accidentally broken in 3.2.2.)
- - Fixed a bug when combining `--delete-missing-args` with `--no-implied-dirs` &
- `-R` where rsync might create the destination path of a missing arg. The
- code also avoids some superfluous warnings for nested paths of removed args.
+ - Fixed a bug when combining [`--delete-missing-args`](rsync.1#opt) with
+ [`--no-implied-dirs`](rsync.1#opt) & [`-R`](rsync.1#opt) where rsync might
+ create the destination path of a missing arg. The code also avoids some
+ superfluous warnings for nested paths of removed args.
- Fixed an issue where hard-linked devices could cause the rdev_major value to
get out of sync between the sender and the receiver, which could cause a
device to get created with the wrong major value in its major,minor pair.
- - Rsync now complains about a missing `--temp-dir` before starting any file
- transfers.
+ - Rsync now complains about a missing [`--temp-dir`](rsync.1#opt) before
+ starting any file transfers.
- A completely empty source arg is now a fatal error. This doesn't change
the handling of implied dot-dir args such as "localhost:" and such.
### ENHANCEMENTS:
- - Allow `--max-alloc=0` to specify no limit to the alloc sanity check.
+ - Allow [`--max-alloc=0`](rsync.1#opt) to specify no limit to the alloc sanity
+ check.
- - Allow `--block-size=SIZE` to specify the size using units (e.g. "100K").
+ - Allow [`--block-size=SIZE`](rsync.1#opt) to specify the size using units
+ (e.g. "100K").
- The name of the id-0 user & group are now sent to the receiver along with
the other user/group names in the transfer (instead of assuming that both
sides have the same id-0 names).
- - Added the `--stop-after=MINS` and `--stop-at=DATE_TIME` options (with the
- `--time-limit=MINS` option accepted as an alias for `--stop-after`). This
- is an enhanced version of the time-limit patch from the patches repo.
-
- - Added the `name converter` daemon parameter to make it easier to convert
- user & group names inside a chrooted daemon module. This is based on the
- nameconverter patch with some improvements, including a tweak to the request
- protocol (so if you used this patch in the past, be sure to update your
- converter script to use newlines instead of null chars).
-
- - Added `--crtimes` (`-N`) option for preserving the file's create time (I
- believe that this is macOS only at the moment).
-
- - Added `--mkpath` option to tell rsync that it should create a non-existing
- path component of the destination arg.
-
- - Added `--stderr=errors|all|client` to replace the `--msgs2stderr` and
- `--no-msgs2stderr` options (which are still accepted). The default use of
- stderr was changed to be `--stderr=errors` where all the processes that have
- stderr available output directly to stderr, which should help error messages
- get to the user more quickly, especially when doing a push (which includes
- local copying). This also allows rsync to exit quickly when a receiver
- failure occurs, since rsync doesn't need to try to keep the connection alive
- long enough for the fatal error to go from the receiver to the generator to
- the sender. The old default can be requested via `--stderr=client`. Also
- changed is that a non-default stderr mode is conveyed to the remote rsync
- (using the older option names) instead of requiring the user to use
- `--remote-option` (`-M`) to tell the remote rsync what to do.
-
- - Added the ability to specify "@netgroup" names to the `hosts allow` and
- `hosts deny` daemon parameters. This is a finalized version of the
- netgroup-auth patch from the patches repo.
+ - Added the [`--stop-after`](rsync.1#opt) and [`--stop-at`](rsync.1#opt)
+ options (with a [`--time-limit`](rsync.1#opt) alias for `--stop-after`).
+ This is an enhanced version of the time-limit patch from the patches repo.
+
+ - Added the [`name converter`](rsyncd.conf.5#opt) daemon parameter to make it
+ easier to convert user & group names inside a chrooted daemon module. This
+ is based on the nameconverter patch with some improvements, including a
+ tweak to the request protocol (so if you used this patch in the past, be
+ sure to update your converter script to use newlines instead of null chars).
+
+ - Added [`--crtimes`](rsync.1#opt) (`-N`) option for preserving the file's
+ create time (I believe that this is macOS only at the moment).
+
+ - Added [`--mkpath`](rsync.1#opt) option to tell rsync that it should create a
+ non-existing path component of the destination arg.
+
+ - Added [`--stderr=errors|all|client`](rsync.1#opt) to replace the
+ `--msgs2stderr` and `--no-msgs2stderr` options (which are still accepted).
+ The default use of stderr was changed to be `--stderr=errors` where all the
+ processes that have stderr available output directly to stderr, which should
+ help error messages get to the user more quickly, especially when doing a
+ push (which includes local copying). This also allows rsync to exit quickly
+ when a receiver failure occurs, since rsync doesn't need to try to keep the
+ connection alive long enough for the fatal error to go from the receiver to
+ the generator to the sender. The old default can be requested via
+ `--stderr=client`. Also changed is that a non-default stderr mode is
+ conveyed to the remote rsync (using the older option names) instead of
+ requiring the user to use [`--remote-option`](rsync.1#opt) (`-M`) to tell
+ the remote rsync what to do.
+
+ - Added the ability to specify "@netgroup" names to the [`hosts
+ allow`](rsyncd.conf.5#opt) and [`hosts deny`](rsyncd.conf.5#opt) daemon
+ parameters. This is a finalized version of the netgroup-auth patch from the
+ patches repo.
- Rsync can now hard-link symlinks on FreeBSD due to it making use of the
linkat() function when it is available.
import os, sys, re, argparse, subprocess, time
from html.parser import HTMLParser
+VALID_PAGES = 'README INSTALL COPYING rsync.1 rrsync.1 rsync-ssl.1 rsyncd.conf.5'.split()
+
CONSUMES_TXT = set('h1 h2 h3 p li pre'.split())
HTML_START = """\
SPACE_DOUBLE_DASH_RE = re.compile(r'\s--(\s)')
NON_SPACE_SINGLE_DASH_RE = re.compile(r'(^|\W)-')
WHITESPACE_RE = re.compile(r'\s')
-CODE_BLOCK_RE = re.compile(r'[%s](.+?)[=%s].*' % (BOLD_FONT[0], NORM_FONT[0]))
+CODE_BLOCK_RE = re.compile(r'[%s]([^=%s]+)[=%s]' % (BOLD_FONT[0], NORM_FONT[0], NORM_FONT[0]))
NBR_DASH_RE = re.compile(r'[%s]' % NBR_DASH[0])
INVALID_TARGET_CHARS_RE = re.compile(r'[^-A-Za-z0-9._]')
INVALID_START_CHAR_RE = re.compile(r'^([^A-Za-z0-9])')
if fi.want_manpage:
fi.title = fi.prog + '(' + fi.sect + ') man page'
else:
- fi.title = fi.prog
+ fi.title = fi.prog + ' for rsync'
if fi.want_manpage:
if not env_subs:
derived_hashtags = set(),
referenced_hashtags = set(),
bad_hashtags = set(),
- prior_target = None,
+ latest_targets = [ ],
opt_prefix = 'opt',
a_txt_start = None,
target_suf = '',
fi.man_out = ''.join(st.man_out)
st.man_out = None
- for href, txt in st.derived_hashtags:
- derived = txt2target(txt, href[1:])
+ for tgt, txt in st.derived_hashtags:
+ derived = txt2target(txt, tgt)
if derived not in st.created_hashtags:
txt = BIN_CHARS_RE.sub('', txt.replace(NBR_DASH[0], '-').replace(NBR_SPACE[0], ' '))
- warn('Unknown derived hashtag link in', self.fn, 'based on:', (href, txt))
+ warn('Unknown derived hashtag link in', self.fn, 'based on:', (tgt, txt))
for bad in st.bad_hashtags:
if bad in st.created_hashtags:
st.a_href = None
for var, val in attrs_list:
if var == 'href':
- if val in ('#', '#opt', '#daemon-opt'):
- st.a_href = val
- elif val.startswith('#'):
- st.referenced_hashtags.add(val[1:])
- if val[1:] == st.prior_target:
- warn('Found link to the current section in', self.fn + ':', val)
- elif not val.startswith(('https://', 'http://', 'mailto:', 'ftp:', './')):
+ if val.startswith(('https://', 'http://', 'mailto:', 'ftp:')):
+ pass # nothing to check
+ elif '#' in val:
+ pg, tgt = val.split('#', 2)
+ if pg and pg not in VALID_PAGES or '#' in tgt:
+ st.bad_hashtags.add(val)
+ elif tgt in ('', 'opt', 'dopt'):
+ st.a_href = val
+ elif pg == '':
+ st.referenced_hashtags.add(tgt)
+ if tgt in st.latest_targets:
+ warn('Found link to the current section in', self.fn + ':', val)
+ elif val not in VALID_PAGES:
st.bad_hashtags.add(val)
st.a_txt_start = len(st.txt)
st.html_out.append('<' + tag + ''.join(' ' + var + '="' + htmlify(val) + '"' for var, val in attrs_list) + '>')
if m:
tgt = m.group(1)
st.target_suf = '-' + tgt
- self.add_target(tgt)
+ self.add_targets(tgt)
elif tag == 'h2':
st.man_out.append(st.p_macro + '.SH "' + manify(txt) + '"\n')
- self.add_target(txt, st.target_suf)
- st.opt_prefix = 'daemon-opt' if txt == 'DAEMON OPTIONS' else 'opt'
+ self.add_targets(txt, st.target_suf)
+ st.opt_prefix = 'dopt' if txt == 'DAEMON OPTIONS' else 'opt'
elif tag == 'h3':
st.man_out.append(st.p_macro + '.SS "' + manify(txt) + '"\n')
- self.add_target(txt, st.target_suf)
+ self.add_targets(txt, st.target_suf)
elif tag == 'p':
if st.dt_from == 'p':
tag = 'dt'
st.man_out.append('.IP "' + manify(txt) + '"\n')
if txt.startswith(BOLD_FONT[0]):
- self.add_target(txt)
+ self.add_targets(txt)
st.dt_from = None
elif txt != '':
st.man_out.append(manify(txt) + "\n")
find = 'href="' + st.a_href + '"'
for j in range(len(st.html_out)-1, 0, -1):
if find in st.html_out[j]:
- derived = txt2target(atxt, st.a_href[1:])
- if derived == st.prior_target:
- warn('Found link to the current section in', self.fn + ':', derived)
- st.derived_hashtags.add((st.a_href, atxt))
- st.html_out[j] = st.html_out[j].replace(find, 'href="#' + derived + '"')
+ pg, tgt = st.a_href.split('#', 2)
+ derived = txt2target(atxt, tgt)
+ if pg == '':
+ if derived in st.latest_targets:
+ warn('Found link to the current section in', self.fn + ':', st.a_href)
+ st.derived_hashtags.add((tgt, atxt))
+ st.html_out[j] = st.html_out[j].replace(find, 'href="' + pg + '#' + derived + '"')
break
else:
die('INTERNAL ERROR: failed to find href in html data:', find)
st.txt += txt
- def add_target(self, txt, suf=None):
+ def add_targets(self, txt, suf=None):
st = self.state
- txt = txt2target(txt, st.opt_prefix)
- if txt:
+ targets = CODE_BLOCK_RE.findall(txt)
+ if not targets:
+ targets = [ txt ]
+ first_one = True
+ for txt in targets:
+ txt = txt2target(txt, st.opt_prefix)
+ if not txt:
+ continue
if suf:
txt += suf
if txt in st.created_hashtags:
print('Made link target unique:', chk)
txt = chk
break
- st.html_out.append('<a id="' + txt + '" href="#' + txt + '" class="tgt"></a>')
+ if first_one:
+ st.html_out.append('<a id="' + txt + '" href="#' + txt + '" class="tgt"></a>')
+ first_one = False
+ else:
+ st.html_out.append('<span id="' + txt + '"></span>')
st.created_hashtags.add(txt)
- st.prior_target = txt
+ st.latest_targets = targets
def output_debug(self, event, extra):
def txt2target(txt, opt_prefix):
- txt = CODE_BLOCK_RE.sub(r'\1', txt.strip().rstrip(':'))
+ txt = txt.strip().rstrip(':')
+ m = CODE_BLOCK_RE.search(txt)
+ if m:
+ txt = m.group(1)
txt = NBR_DASH_RE.sub('-', txt)
txt = BIN_CHARS_RE.sub('', txt)
txt = INVALID_TARGET_CHARS_RE.sub('_', txt)
## SEE ALSO
-[**rsync**(1)](./rsync.1), [**rsyncd.conf**(5)](./rsyncd.conf.5)
+[**rsync**(1)](rsync.1), [**rsyncd.conf**(5)](rsyncd.conf.5)
## CAVEATS
## CREDITS
Rsync is distributed under the GNU General Public License. See the file
-[COPYING](./COPYING) for details.
+[COPYING](COPYING) for details.
A web site is available at <https://rsync.samba.org/>. The site includes an
FAQ-O-Matic which may cover questions unanswered by this manual page.
communications, but it may have been configured to use a different remote shell
by default, such as rsh or remsh.
-You can also specify any remote shell you like, either by using the [`-e`](#opt--rsh)
+You can also specify any remote shell you like, either by using the [`-e`](#opt)
command line option, or by setting the RSYNC_RSH environment variable.
Note that rsync must be installed on both the source and destination machines.
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 [**rsyncd.conf**(5)](./rsyncd.conf.5) man page -- that is
+connections, see the [**rsyncd.conf**(5)](rsyncd.conf.5) man page -- 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).
[comment]: # (An OL starting at 0 is converted into a DL by the parser.)
-0. `--help`, `-h` `(*)`
+0. `--help`
Print a short help page describing the options available in rsync and exit.
- (*) The `-h` short option will only invoke `--help` when used without other
- options since it normally means [`--human-readable`](#opt).
+ You can also use `-h` for `--help` when it is used without any other
+ options (since it normally means [`--human-readable`](#opt)).
0. `--version`, `-V`
crtimes (`-N`), nor the finding and preserving of hardlinks (`-H`).
The only exception to the above equivalence is when [`--files-from`](#opt)
- is specified, in which case [`-r`](#opt--recursive) is not implied.
+ is specified, in which case [`-r`](#opt) is not implied.
0. `--no-OPTION`
You may turn off one or more implied options by prefixing the option name
- with "no-". Not all options may be prefixed with a "no-": only options that
- are implied by other options (e.g. `--no-D`, `--no-perms`) or have
- different defaults in various circumstances (e.g. `--no-whole-file`,
- `--no-blocking-io`, `--no-dirs`). You may specify either the short or the
- long option name after the "no-" prefix (e.g. `--no-R` is the same as
- `--no-relative`).
-
- For example: if you want to use [`--archive`](#opt) (`-a`) but don't want
+ 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.
+ `--no-D`, `--no-perms`) or have different defaults in various circumstances
+ (e.g. [`--no-whole-file`](#opt), `--no-blocking-io`, `--no-dirs`). Every
+ valid negated option accepts both the short and the long option name after
+ the "no-" prefix (e.g. `--no-R` is the same as `--no-relative`).
+
+ As an example, if you want to use [`--archive`](#opt) (`-a`) but don't want
[`--owner`](#opt) (`-o`), instead of converting `-a` into `-rlptgD`, you
- could specify `-a --no-o` (or `-a --no-owner`).
+ can specify `-a --no-o` (aka `--archive --no-owner`).
The order of the options is important: if you specify `--no-r -a`, the `-r`
option would end up being turned on, the opposite of `-a --no-r`. Note
also that the side-effects of the [`--files-from`](#opt) option are NOT
positional, as it affects the default state of several options and slightly
- changes the meaning of [`-a`](#opt--archive) (see the
- [`--files-from`](#opt) option for more details).
+ changes the meaning of [`-a`](#opt) (see the [`--files-from`](#opt) option
+ for more details).
0. `--recursive`, `-r`
what (if any) suffix gets appended using the [`--backup-dir`](#opt) and
[`--suffix`](#opt) options.
- Note that if you don't specify [`--backup-dir`](#opt), (1) the
- [`--omit-dir-times`](#opt) option will be forced on, and (2) if
- [`--delete`](#opt) is also in effect (without [`--delete-excluded`](#opt)),
- rsync will add a "protect" filter-rule for the backup suffix to the end of
- all your existing excludes (e.g. `-f "P *~"`). This will prevent
- previously backed-up files from being deleted. 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 `*`, the auto-added rule would never be reached).
+ If you don't specify [`--backup-dir`](#opt):
+
+ 1. the [`--omit-dir-times`](#opt) option will be forced on
+ 2. the use of [`--delete`](#opt) (without [`--delete-excluded`](#opt)),
+ causes rsync to add a "protect" [filter-rule](#FILTER_RULES) for the
+ backup suffix to the end of all your existing filters that looks like
+ this: `-f "P *~"`. This rule prevents previously backed-up files from
+ being deleted.
+
+ 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 `*`, the auto-added rule
+ would never be reached).
0. `--backup-dir=DIR`
This tells rsync to transfer modification times along with the files and
update them on the remote system. Note that if this option is not used,
the optimization that excludes files that have not been modified cannot be
- effective; in other words, a missing `-t` (or [`-a`](#opt--archive)) will
- cause the next transfer to behave as if it used [`--ignore-times`](#opt)
- (`-I`), causing all files to be updated (though rsync's delta-transfer
- algorithm will make the update fairly efficient if the files haven't
- actually changed, you're much better off using `-t`).
+ effective; in other words, a missing `-t` (or [`-a`](#opt)) will cause the
+ next transfer to behave as if it used [`--ignore-times`](#opt) (`-I`),
+ causing all files to be updated (though rsync's delta-transfer algorithm
+ will make the update fairly efficient if the files haven't actually
+ changed, you're much better off using `-t`).
0. `--atimes`, `-U`
This option is overridden by both [`--super`](#opt) and `--no-super`.
- See also the [`fake super`](./rsyncd.conf.5#fake_super) setting in the
+ See also the [`fake super`](rsyncd.conf.5#fake_super) setting in the
daemon's rsyncd.conf file.
0. `--sparse`, `-S`
source and destination are specified as local paths, but only if no
batch-writing option is in effect.
+0. `--no-whole-file`, `--no-W`
+
+ Disable whole-file updating when it is enaled by default for a local
+ transfer. This usually slows rsync down, but it can be useful if you are
+ trying to minimize the writes to the destination file (if combined with
+ [`--inplace`](#opt)) or for testing the checksum-based update algorithm.
+
+ See also the [`--whole-file`](#opt) option.
+
0. `--checksum-choice=STR`, `--cc=STR`
This option overrides the checksum algorithms. If one algorithm name is
When [`--info=skip2`](#opt) is used rsync will output "FILENAME exists
(INFO)" messages where the INFO indicates one of "type change", "sum
- change" (requires [`-c`](#opt--checksum)), "file change" (based on the
- quick check), "attr change", or "uptodate". Using [`--info=skip1`](#opt)
- (which is also implied by 2 [`-v`](#opt--verbose) options) outputs the
- exists message without the INFO suffix.
+ change" (requires [`-c`](#opt)), "file change" (based on the quick check),
+ "attr change", or "uptodate". Using [`--info=skip1`](#opt) (which is also
+ implied by 2 [`-v`](#opt) options) outputs the exists message without the
+ INFO suffix.
0. `--remove-source-files`
[`--recursive`](#opt) (`-r`), so specify it explicitly, if you want it.
- These side-effects change the default state of rsync, so the position of
the `--files-from` option on the command-line has no bearing on how other
- options are parsed (e.g. [`-a`](#opt--archive) works the same before or
- after `--files-from`, as does `--no-R` and all other options).
+ options are parsed (e.g. [`-a`](#opt) works the same before or after
+ `--files-from`, as does `--no-R` and all other options).
The filenames that are read from the FILE are all relative to the source
dir -- any leading slashes are removed and no ".." references are allowed
contains "bin/" (note the trailing slash), the immediate contents of the
directory would also be sent (without needing to be explicitly mentioned in
the file -- this began in version 2.6.4). In both cases, if the
- [`-r`](#opt--recursive) option was enabled, that dir's entire hierarchy
- would also be transferred (keep in mind that [`-r`](#opt--recursive) needs
- to be specified explicitly with `--files-from`, since it is not implied by
- [`-a`](#opt--archive). Also note that the effect of the (enabled by
- default) [`-r`](#opt--relative) option is to duplicate only the path info
- that is read from the file -- it does not force the duplication of the
- source-spec path (/usr in this case).
+ [`-r`](#opt) option was enabled, that dir's entire hierarchy would also be
+ transferred (keep in mind that [`-r`](#opt) needs to be specified
+ explicitly with `--files-from`, since it is not implied by [`-a`](#opt).
+ Also note that the effect of the (enabled by default) [`-r`](#opt) option
+ is to duplicate only the path info that is read from the file -- it does
+ not force the duplication of the source-spec path (/usr in this case).
In addition, the `--files-from` file can be read from the remote host
instead of the local host if you specify a "host:" in front of the file
If a user or group has no name on the source system or it has no match on
the destination system, then the numeric ID from the source system is used
- instead. See also the [`use chroot`](./rsyncd.conf.5#use_chroot) setting
+ instead. See also the [`use chroot`](rsyncd.conf.5#use_chroot) setting
in the rsyncd.conf manpage for some comments on how the chroot setting
affects rsync's ability to look up the names of the users and groups and
what you can do about it.
0. `--chown=USER:GROUP`
This option forces all files to be owned by USER with group GROUP. This is
- a simpler interface than using [`--usermap` & `--groupmap`](#opt--usermap)
+ a simpler interface than using [`--usermap`](#opt) & [`--groupmap`](#opt)
directly, but it is implemented using those options internally so they
cannot be mixed. If either the USER or GROUP is empty, no mapping for the
omitted user/group will occur. If GROUP is empty, the trailing colon may
rsync daemon. The `--address` option allows you to specify a specific IP
address (or hostname) to bind to.
- See also [the daemon version of the `--address`
- option](#daemon-opt--address).
+ See also [the daemon version of the `--address` option](#dopt--address).
0. `--port=PORT`
to connect with an rsync daemon (since the URL syntax has a way to specify
the port as a part of the URL).
- See also [the daemon version of the `--port` option](#daemon-opt--port).
+ See also [the daemon version of the `--port` option](#dopt--port).
0. `--sockopts=OPTIONS`
able to set. By default no special socket options are set. This only
affects direct socket connections to a remote rsync daemon.
- See also [the daemon version of the `--sockopts`
- option](#daemon-opt--sockopts).
+ See also [the daemon version of the `--sockopts` option](#dopt--sockopts).
0. `--blocking-io`
user on a per-update basis. The format is a text string containing
embedded single-character escape sequences prefixed with a percent (%)
character. A default format of "%n%L" is assumed if either
- [`--info=name`](#opt) or [`-v`](#opt--verbose) is specified (this tells you
- just the name of the file and, if the item is a link, where it points).
- For a full list of the possible escape characters, see the
- [`log format`](./rsyncd.conf.5#log_format) setting in the rsyncd.conf
- manpage.
+ [`--info=name`](#opt) or [`-v`](#opt) is specified (this tells you just the
+ name of the file and, if the item is a link, where it points). For a full
+ list of the possible escape characters, see the [`log
+ format`](rsyncd.conf.5#log_format) setting in the rsyncd.conf manpage.
Specifying the `--out-format` option implies the [`--info=name`](#opt)
option, which will mention each file, dir, etc. that gets updated in a
This is very useful if you need to debug why a connection is closing
unexpectedly.
- See also [the daemon version of the `--log-file`
- option](#daemon-opt--log-file).
+ See also [the daemon version of the `--log-file` option](#dopt--log-file).
0. `--log-file-format=FORMAT`
file specified by the [`--log-file`](#opt) option (which must also be
specified for this option to have any effect). If you specify an empty
string, updated files will not be mentioned in the log file. For a list of
- the possible escape characters, see the [`log format`](./rsyncd.conf.5#log_format)
+ the possible escape characters, see the [`log format`](rsyncd.conf.5#log_format)
setting in the rsyncd.conf manpage.
The default FORMAT used if [`--log-file`](#opt) is specified and this
option is not is '%i %n%L'.
See also [the daemon version of the `--log-file-format`
- option](#daemon-opt--log-file-format).
+ option](#dopt--log-file-format).
0. `--stats`
This tells rsync to print a verbose set of statistics on the file transfer,
allowing you to tell how effective rsync's delta-transfer algorithm is for
your data. This option is equivalent to [`--info=stats2`](#opt) if
- combined with 0 or 1 [`-v`](#opt--verbose) options, or
- [`--info=stats3`](#opt) if combined with 2 or more [`-v`](#opt--verbose)
- options.
+ combined with 0 or 1 [`-v`](#opt) options, or [`--info=stats3`](#opt) if
+ combined with 2 or more [`-v`](#opt) options.
The current statistics are as follows:
0. `--human-readable`, `-h`
- Output numbers in a more human-readable format. There are 3 possible
- levels: (1) output numbers with a separator between each set of 3 digits
- (either a comma or a period, depending on if the decimal point is
- represented by a period or a comma); (2) output numbers in units of 1000
- (with a character suffix for larger units -- see below); (3) output
- numbers in units of 1024.
+ Output numbers in a more human-readable format. There are 3 possible levels:
+
+ 1. output numbers with a separator between each set of 3 digits (either a
+ comma or a period, depending on if the decimal point is represented by a
+ period or a comma).
+ 2. output numbers in units of 1000 (with a character suffix for larger
+ units -- see below).
+ 3. output numbers in units of 1024.
The default is human-readable level 1. Each `-h` option increases the
level by one. You can take the level down to 0 (to output numbers as pure
rules.
If you are supplying your own exclude rules, you may need to add your own
- exclude/hide/protect rule for the partial-dir because (1) the auto-added
- rule may be ineffective at the end of your other rules, or (2) you may wish
- to override rsync's exclude choice. For instance, if you want to make
- rsync clean-up any left-over partial-dirs that may be lying around, you
- should specify [`--delete-after`](#opt) and add a "risk" filter rule, e.g.
- `-f 'R .rsync-partial/'`. (Avoid using [`--delete-before`](#opt) or
- [`--delete-during`](#opt) unless you don't need rsync to use any of the
- left-over partial-dir data during the current run.)
+ exclude/hide/protect rule for the partial-dir because:
+
+ 1. the auto-added rule may be ineffective at the end of your other rules, or
+ 2. you may wish to override rsync's exclude choice.
+
+ For instance, if you want to make rsync clean-up any left-over partial-dirs
+ that may be lying around, you should specify [`--delete-after`](#opt) and
+ add a "risk" filter rule, e.g. `-f 'R .rsync-partial/'`. Avoid using
+ [`--delete-before`](#opt) or [`--delete-during`](#opt) unless you don't
+ need rsync to use any of the left-over partial-dir data during the current
+ run.
IMPORTANT: the `--partial-dir` should not be writable by other users or it
is a security risk. E.g. AVOID "/tmp".
set RSYNC_PARTIAL_DIR=.rsync-tmp in your environment and then just use the
[`-P`](#opt) option to turn on the use of the .rsync-tmp dir for partial
transfers. The only times that the [`--partial`](#opt) option does not
- look for this environment value are (1) when [`--inplace`](#opt) was
- specified (since [`--inplace`](#opt) conflicts with `--partial-dir`), and
- (2) when [`--delay-updates`](#opt) was specified (see below).
+ look for this environment value are:
+
+ 1. when [`--inplace`](#opt) was specified (since [`--inplace`](#opt)
+ conflicts with `--partial-dir`), and
+ 2. when [`--delay-updates`](#opt) was specified (see below).
When a modern rsync resumes the transfer of a file in the partial-dir, that
partial file is now updated in-place instead of creating yet another
This option uses more memory on the receiving side (one bit per file
transferred) and also requires enough free disk space on the receiving side
to hold an additional copy of all the updated files. Note also that you
- should not use an absolute path to [`--partial-dir`](#opt) unless (1) there
- is no chance of any of the files in the transfer having the same name
- (since all the updated files will be put into a single directory if the
- path is absolute) and (2) there are no mount points in the hierarchy (since
- the delayed updates will fail if they can't be renamed into place).
+ should not use an absolute path to [`--partial-dir`](#opt) unless:
+
+ 1. there is no chance of any of the files in the transfer having the same
+ name (since all the updated files will be put into a single directory if
+ the path is absolute), and
+ 2. there are no mount points in the hierarchy (since the delayed updates
+ will fail if they can't be renamed into place).
See also the "atomic-rsync" python script in the "support" subdir for an
update algorithm that is even more atomic (it uses [`--link-dest`](#opt)
This option will cause the source files to be listed instead of
transferred. This option is inferred if there is a single source arg and
- no destination specified, so its main uses are: (1) to turn a copy command
- that includes a destination arg into a file-listing command, or (2) to be
- able to specify more than one source arg (note: be sure to include the
- destination). Caution: keep in mind that a source arg with a wild-card is
- expanded by the shell into multiple args, so it is never safe to try to
- list such an arg without using this option. For example:
+ no destination specified, so its main uses are:
+
+ 1. to turn a copy command that includes a destination arg into a
+ file-listing command, or
+ 2. to be able to specify more than one source arg. Note: be sure to
+ include the destination.
+
+ CAUTION: keep in mind that a source arg with a wild-card is expanded by the
+ shell into multiple args, so it is never safe to try to list such an arg
+ without using this option. For example:
> rsync -av --list-only foo* dest/
quickly buffered, while other can show up as very slow when the flushing of
the output buffer occurs. This may be fixed in a future version.
- See also [the daemon version of the `--bwlimit`
- option](#daemon-opt--bwlimit).
+ See also [the daemon version of the `--bwlimit` option](#dopt--bwlimit).
-0. `--stop-after=MINS`
+0. `--stop-after=MINS`, (`--time-limit=MINS`)
This option tells rsync to stop copying when the specified number of
minutes has elapsed.
- Rsync also accepts an earlier version of this option: `--time-limit=MINS`.
-
For maximal flexibility, rsync does not communicate this option to the
remote rsync since it is usually enough that one side of the connection
quits as specified. This allows the option's use even when only one side
of the connection supports it. You can tell the remote side about the time
limit using [`--remote-option`](#opt) (`-M`), should the need arise.
+ The `--time-limit` version of this option is deprecated.
+
0. `--stop-at=y-m-dTh:m`
This option tells rsync to stop copying when the specified point in time
the "`--rsh SHELL -4`" option directly (or whatever ipv4/ipv6 hint options
it uses).
- See also [the daemon version of these options](#daemon-opt--ipv4).
+ See also [the daemon version of these options](#dopt--ipv4).
If rsync was compiled without support for IPv6, the `--ipv6` option will
have no effect. The `rsync --version` output will contain "`no IPv6`" if
background daemon. The daemon will read the config file (rsyncd.conf) on
each connect made by a client and respond to requests accordingly.
- See the [**rsyncd.conf**(5)](./rsyncd.conf.5) man page for more details.
+ See the [**rsyncd.conf**(5)](rsyncd.conf.5) man page for more details.
0. `--address=ADDRESS`
specific IP address (or hostname) to bind to. This makes virtual hosting
possible in conjunction with the `--config` option.
- See also the [address](./rsyncd.conf.5#address) global option in the
+ See also the [address](rsyncd.conf.5#address) global option in the
rsyncd.conf manpage and the [client version of the `--address`
option](#opt--address).
0. `--config=FILE`
This specifies an alternate config file than the default. This is only
- relevant when [`--daemon`](#daemon-opt) is specified. The default is
+ relevant when [`--daemon`](#dopt) is specified. The default is
/etc/rsyncd.conf unless the daemon is running over a remote shell program
and the remote user is not the super-user; in that case the default is
rsyncd.conf in the current directory (typically $HOME).
rather than the default of 873.
See also [the client version of the `--port` option](#opt--port) and the
- [port](./rsyncd.conf.5#port) global setting in the rsyncd.conf manpage.
+ [port](rsyncd.conf.5#port) global setting in the rsyncd.conf manpage.
0. `--log-file=FILE`
0. `--sockopts`
- This overrides the [`socket options`](./rsyncd.conf.5#socket_options)
+ This overrides the [`socket options`](rsyncd.conf.5#socket_options)
setting in the rsyncd.conf file and has the same syntax.
See also [the client version of the `--sockopts` option](#opt--sockopts).
had been specified). This behavior was added in version 2.6.7.
Note that, when using the [`--recursive`](#opt) (`-r`) option (which is implied
-by [`-a`](#opt--archive)), every subdir component of every path is visited left
-to right, with each directory having a chance for exclusion before its content.
+by [`-a`](#opt)), every subdir component of every path is visited left to
+right, with each directory having a chance for exclusion before its content.
In this way include/exclude patterns are applied recursively to the pathname of
each node in the filesystem's tree (those inside the transfer). The exclude
patterns short-circuit the directory traversal stage as rsync finds the files
verify, the update discarded with an error. This means that it should be safe
to re-run a read-batch operation if the command got interrupted. If you wish
to force the batched-update to always be attempted regardless of the file's
-size and date, use the [`-I`](#opt--ignore-times) option (when reading the
-batch). If an error occurs, the destination tree will probably be in a
-partially updated state. In that case, rsync can be used in its regular
-(non-batch) mode of operation to fix up the destination tree.
+size and date, use the [`-I`](#opt) option (when reading the batch). If an
+error occurs, the destination tree will probably be in a partially updated
+state. In that case, rsync can be used in its regular (non-batch) mode of
+operation to fix up the destination tree.
The rsync version used on all destinations must be at least as new as the one
used to generate the batch file. Rsync will die with an error if the protocol
## SEE ALSO
-[**rsync-ssl**(1)](./rsync-ssl.1), [**rsyncd.conf**(5)](./rsyncd.conf.5), [**rrsync**(1)](./rrsync.1)
+[**rsync-ssl**(1)](rsync-ssl.1), [**rsyncd.conf**(5)](rsyncd.conf.5), [**rrsync**(1)](rrsync.1)
## BUGS
## CREDITS
Rsync is distributed under the GNU General Public License. See the file
-[COPYING](./COPYING) for details.
+[COPYING](COPYING) for details.
An rsync web site is available at <https://rsync.samba.org/>. The site
includes an FAQ-O-Matic which may cover questions unanswered by this manual
## SEE ALSO
-[**rsync**(1)](./rsync.1), [**rsync-ssl**(1)](./rsync-ssl.1)
+[**rsync**(1)](rsync.1), [**rsync-ssl**(1)](rsync-ssl.1)
## BUGS
## CREDITS
Rsync is distributed under the GNU General Public License. See the file
-[COPYING](./COPYING) for details.
+[COPYING](COPYING) for details.
An rsync web site is available at <https://rsync.samba.org/> and its github
project is <https://github.com/WayneD/rsync>.
rrsync [-ro|-rw] [-munge] [-no-del] [-no-lock] DIR
```
+The single non-option argument specifies the restricted _DIR_ to use. It can be
+relative to the user's home directory or an absolute path.
+
The online version of this man page (that includes cross-linking of topics)
is available at <https://download.samba.org/pub/rsync/rrsync.1>.
Then, ensure that the rrsync script has your desired option restrictions. You
may want to copy the script to a local bin dir with a unique name if you want
to have multiple configurations. One or more rrsync options can be specified
-prior to the `DIR` if you want to further restrict the transfer.
+prior to the _DIR_ if you want to further restrict the transfer.
To use an rsync daemon setup, edit the user's `~/.ssh/authorized_keys` file and
add a prefix like one of the following (followed by a space) in front of each
Then, ensure that the rsyncd.conf file is created with one or more module names
with the appropriate path and option restrictions. If rsync's
-[`--config`](./rsync.1#daemon-opt--config) option is omitted, it defaults to
-`~/rsyncd.conf`. See the `rsyncd.conf` man page for details of how to
-configure an rsync daemon.
+[`--config`](rsync.1#dopt) option is omitted, it defaults to `~/rsyncd.conf`.
+See the `rsyncd.conf` man page for details of how to configure an rsync daemon.
When using rrsync, there can be just one restricted dir per authorized key. A
daemon setup, on the other hand, allows multiple module names inside the config
The remainder of this man page is dedicated to using the rrsync script.
-## OPTION SUMMARY
+## OPTIONS
-```
--ro Allow only reading from the DIR. Implies -no-del and -no-lock.
--wo Allow only writing to the DIR.
--munge Enable rsync's --munge-links on the server side.
--no-del Disable rsync's --delete* and --remove* options.
--no-lock Avoid the single-run (per-user) lock check.
--help, -h Output this help message and exit.
-```
+0. `-ro`
-A single non-option argument specifies the restricted DIR to use. It can be
-relative to the user's home directory or an absolute path.
+ Allow only reading from the DIR. Implies [`-no-del`](#opt) and
+ [`-no-lock`](#opt).
+
+0. `-wo`
+
+ Allow only writing to the DIR.
+
+0. `-munge`
+
+ Enable rsync's [`--munge-links`](rsync.1#opt) on the server side.
+
+0. `-no-del`
+
+ Disable rsync's `--delete*` and `--remove*` options.
+
+0. `-no-lock`
+
+ Avoid the single-run (per-user) lock check. Useful with [`-munge`](#opt).
+
+0. `-help`, `-h`
+
+ Output this help message and exit.
## SECURITY RESTRICTIONS
The rrsync script validates the path arguments it is sent to try to restrict
them to staying within the specified DIR.
-The rrsync script rejects rsync's [`--copy-links`](./rsync.1#opt--copy-links)
-option (by default) so that a copy cannot dereference a symlink within the DIR
-to get to a file outside the DIR.
+The rrsync script rejects rsync's [`--copy-links`](rsync.1#opt) option (by
+default) so that a copy cannot dereference a symlink within the DIR to get to a
+file outside the DIR.
-The rrsync script rejects rsync's
-[`--protect-args`](./rsync.1#opt--protect-args) (`-s`) option because it would
-allow options to be sent to the server-side that the script cannot check. If
-you want to support `--protect-args`, use a daemon-over-ssh setup.
+The rrsync script rejects rsync's [`--protect-args`](rsync.1#opt) (`-s`) option
+because it would allow options to be sent to the server-side that the script
+cannot check. If you want to support `--protect-args`, use a daemon-over-ssh
+setup.
The rrsync script accepts just a subset of rsync's options that the real rsync
uses when running the server command. A few extra convenience options are also
## SEE ALSO
-[**rsync**(1)](./rsync.1)
+[**rsync**(1)](rsync.1)
## VERSION
## CREDITS
rsync is distributed under the GNU General Public License. See the file
-[COPYING](./COPYING) for details.
+[COPYING](COPYING) for details.
An rsync web site is available at <https://rsync.samba.org/> and its github
project is <https://github.com/WayneD/rsync>.
git.samba.org / rsync.git / commitdiff