Annotation of src/usr.bin/rsync/rsync.1, Revision 1.1
1.1 ! benno 1: .\" $OpenBSD$
! 2: .\"
! 3: .\" Copyright (c) 2019 Kristaps Dzonsons <kristaps@bsd.lv>
! 4: .\"
! 5: .\" Permission to use, copy, modify, and distribute this software for any
! 6: .\" purpose with or without fee is hereby granted, provided that the above
! 7: .\" copyright notice and this permission notice appear in all copies.
! 8: .\"
! 9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
! 10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
! 11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
! 12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
! 13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
! 14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
! 15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
! 16: .\"
! 17: .Dd $Mdocdate$
! 18: .Dt RSYNC 1
! 19: .Os
! 20: .Sh NAME
! 21: .Nm rsync
! 22: .Nd synchronise local and remote files
! 23: .Sh SYNOPSIS
! 24: .Nm rsync
! 25: .Op Fl lnprtv
! 26: .Op Fl -delete
! 27: .Op Fl -rsync-path Ar prog
! 28: .Ar source ...
! 29: .Ar directory
! 30: .Sh DESCRIPTION
! 31: The
! 32: .Nm
! 33: utility synchronises files in the destination
! 34: .Ar directory
! 35: with one or more
! 36: .Ar source
! 37: files.
! 38: Either the
! 39: .Ar source
! 40: or the destination
! 41: .Ar directory
! 42: may be remote,
! 43: but not both.
! 44: The arguments are as follows:
! 45: .Bl -tag -width Ds
! 46: .It Fl l
! 47: Transfer symbolic links.
! 48: The link is transferred as a standalone file: if the destination does
! 49: not exist, it will be broken.
! 50: .It Fl n
! 51: Dry-run mode.
! 52: Does not actually modify the destination.
! 53: .It Fl p
! 54: Set destination file or directory permissions to match the source when
! 55: it is updated.
! 56: .It Fl r
! 57: If
! 58: .Ar source
! 59: designates a directory, synchronise the directory and the entire subtree
! 60: connected at that point.
! 61: If
! 62: .Ar source
! 63: ends with a slash, only the subtree is synchronised, not the root
! 64: directory.
! 65: If
! 66: .Ar source
! 67: is a file, this has no effect.
! 68: .It Fl t
! 69: Set destination file and directory modification time to match the source
! 70: when it is updated or created.
! 71: .It Fl v
! 72: Increase verbosity.
! 73: Specify once for files being transferred, twice for specific status,
! 74: thrice for per-file transfer information, and four times for per-file
! 75: breakdowns.
! 76: .It Fl -delete
! 77: Delete files in
! 78: .Ar directory
! 79: not found in
! 80: .Ar source
! 81: directories.
! 82: Only applicable with
! 83: .Fl r .
! 84: .It Fl -rsync-path Ar prog
! 85: Run
! 86: .Ar prog
! 87: on the remote host instead of the default
! 88: .Ar rsync .
! 89: .El
! 90: .Pp
! 91: A remote
! 92: .Ar source
! 93: or
! 94: .Ar directory
! 95: has syntax
! 96: .Ar host:path
! 97: for connecting via
! 98: .Xr ssh 1 ,
! 99: or
! 100: .Ar rsync://host/path
! 101: or
! 102: .Ar host::path
! 103: for connecting to a remote daemon.
! 104: Subsequent to the first remote
! 105: .Ar source ,
! 106: the host may be dropped to become just
! 107: .Ar :path
! 108: or
! 109: .Ar ::path .
! 110: .Pp
! 111: For connecting to a remote daemon with
! 112: .Ar rsync://host
! 113: or
! 114: .Ar host::path ,
! 115: the first path component is interpreted as a
! 116: .Qq module :
! 117: .Ar host::module/path .
! 118: This only applies to the first
! 119: .Ar source
! 120: invocation; subsequent to that, the module should not be specified.
! 121: .Pp
! 122: By default, new destination files and directories are given the current
! 123: time and the source file permissions.
! 124: Updated files retain their existing permissions.
! 125: It is an error if updated files have their file types change (e.g.,
! 126: updating a directory with a file).
! 127: .Pp
! 128: At this time,
! 129: .Ar source
! 130: may only consist of regular files, directories
! 131: .Pq only with Fl r ,
! 132: or symbolic links
! 133: .Pq only with Fl l .
! 134: The destination
! 135: .Ar directory
! 136: must be a directory and is created if not found.
! 137: .Pp
! 138: .Nm
! 139: is compatible with the GPL-licensed
! 140: .Xr rsync 1
! 141: protocol version 27.
! 142: .\" The following requests should be uncommented and used where appropriate.
! 143: .\" .Sh CONTEXT
! 144: .\" For section 9 functions only.
! 145: .\" .Sh RETURN VALUES
! 146: .\" For sections 2, 3, and 9 function return values only.
! 147: .\" .Sh ENVIRONMENT
! 148: .\" For sections 1, 6, 7, and 8 only.
! 149: .\" .Sh FILES
! 150: .\" .Sh EXIT STATUS
! 151: .\" For sections 1, 6, and 8 only.
! 152: .Sh EXAMPLES
! 153: All examples use
! 154: .Fl t
! 155: so that destination files inherit the source time.
! 156: If not changed, subsequent invocations of
! 157: .Nm
! 158: will then consider the file up to date and not transfer block hashes.
! 159: .Pp
! 160: To update the out-of-date remote files
! 161: .Pa host:dest/bar
! 162: and
! 163: .Pa host:dest/baz
! 164: with the local
! 165: .Pa ../src/bar
! 166: and
! 167: .Pa ../src/baz :
! 168: .Pp
! 169: .Dl % rsync -t ../src/bar ../src/baz host:dest
! 170: .Pp
! 171: To update the out-of-date local files
! 172: .Pa bar
! 173: and
! 174: .Pa baz
! 175: with the remote files
! 176: .Pa host:src/bar
! 177: and
! 178: .Pa host:src/baz :
! 179: .Pp
! 180: .Dl % rsync -t host:src/bar :src/baz \&.
! 181: .Pp
! 182: To update the out-of-date local files
! 183: .Pa ../dest/bar
! 184: and
! 185: .Pa ../dest/baz
! 186: with
! 187: .Pa bar
! 188: and
! 189: .Pa baz :
! 190: .Pp
! 191: .Dl % rsync -t bar baz ../dest
! 192: .Pp
! 193: To update the out-of-date remote files in
! 194: .Pa host:dest
! 195: on a remote host running
! 196: .Nm
! 197: with the local host running
! 198: .Xr rsync 1 :
! 199: .Pp
! 200: .Dl % rsync --rsync-path rsync -t ../dest/* host:dest
! 201: .\" .Sh DIAGNOSTICS
! 202: .\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
! 203: .\" .Sh ERRORS
! 204: .\" For sections 2, 3, 4, and 9 errno settings only.
! 205: .Sh SEE ALSO
! 206: .Xr ssh 1 ,
! 207: .Xr rsync 5 ,
! 208: .Xr rsyncd 5
! 209: .\" .Sh STANDARDS
! 210: .\" .Sh HISTORY
! 211: .\" .Sh AUTHORS
! 212: .\" .Sh CAVEATS
! 213: .\" .Sh BUGS