Annotation of src/usr.bin/rsync/rsync.1, Revision 1.10
1.10 ! jmc 1: .\" $OpenBSD: rsync.1,v 1.9 2019/02/17 18:11:50 deraadt Exp $
1.1 benno 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: .\"
1.9 deraadt 17: .Dd $Mdocdate: February 17 2019 $
1.1 benno 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
1.10 ! jmc 25: .Op Fl aDglnoprtv
! 26: .Op Fl e Ar program
! 27: .Op Fl -archive
1.1 benno 28: .Op Fl -delete
1.10 ! jmc 29: .Op Fl -devices
! 30: .Op Fl -group
! 31: .Op Fl -links
! 32: .Op Fl -dry-run
! 33: .Op Fl -owner
! 34: .Op Fl -perms
! 35: .Op Fl -port Ns = Ns Ar portnumber
! 36: .Op Fl -recursive
! 37: .Op Fl -rsh Ns = Ns Ar program
! 38: .Op Fl -rsync-path Ns = Ns Ar program
! 39: .Op Fl -specials
! 40: .Op Fl -times
! 41: .Op Fl -verbose
! 42: .Op Fl -version
1.1 benno 43: .Ar source ...
44: .Ar directory
45: .Sh DESCRIPTION
46: The
47: .Nm
48: utility synchronises files in the destination
49: .Ar directory
50: with one or more
51: .Ar source
52: files.
53: Either the
54: .Ar source
55: or the destination
56: .Ar directory
57: may be remote,
58: but not both.
59: The arguments are as follows:
60: .Bl -tag -width Ds
1.6 florian 61: .It Fl a , Fl -archive
62: Archive mode.
63: Shorthand for
1.10 ! jmc 64: .Fl Dgloprt .
1.6 florian 65: .It Fl D
66: Transfer device and special files.
67: Shorthand for
1.10 ! jmc 68: .Fl -devices -specials
! 69: .It Fl -delete
! 70: Delete files in
! 71: .Ar directory
! 72: not found in
! 73: .Ar source
! 74: directories.
! 75: Only applicable with
! 76: .Fl r .
1.6 florian 77: .It Fl -devices
78: Transfer device files.
1.10 ! jmc 79: .It Fl e Ar program , Fl -rsh Ns = Ns Ar program
1.8 deraadt 80: Specify alternative program, defaults to
81: .Xr ssh 1 .
1.7 deraadt 82: .It Fl g , Fl -group
1.3 benno 83: Set group identifier to match the source.
84: Groups are matched by name: group
85: .Qq kristaps
86: with id 1000 on a remote server will be properly assigned group
87: .Qq kristaps
88: on the local machine with id 2000.
89: If the sender's group is unknown on the local machine, it is used
90: verbatim.
1.7 deraadt 91: .It Fl l , Fl -links
1.1 benno 92: Transfer symbolic links.
93: The link is transferred as a standalone file: if the destination does
94: not exist, it will be broken.
1.7 deraadt 95: .It Fl n , Fl -dry-run
1.1 benno 96: Dry-run mode.
97: Does not actually modify the destination.
1.7 deraadt 98: .It Fl o , Fl -owner
1.4 florian 99: Set user identifier to match the source.
100: This behaves like
101: .Fl g
102: and only works if run as root.
1.7 deraadt 103: .It Fl p , Fl -perms
1.1 benno 104: Set destination file or directory permissions to match the source when
105: it is updated.
1.10 ! jmc 106: .It Fl -port Ns = Ns Ar portnumber
! 107: Specify alternative port number.
1.7 deraadt 108: .It Fl r , Fl -recursive
1.1 benno 109: If
110: .Ar source
111: designates a directory, synchronise the directory and the entire subtree
112: connected at that point.
113: If
114: .Ar source
115: ends with a slash, only the subtree is synchronised, not the root
116: directory.
117: If
118: .Ar source
119: is a file, this has no effect.
1.10 ! jmc 120: .It Fl -rsync-path Ns = Ns Ar program
! 121: Run
! 122: .Ar prog
! 123: on the remote host instead of the default
! 124: .Ar rsync .
1.6 florian 125: .It Fl -specials
126: Transfer fifo and unix domain socket files.
1.7 deraadt 127: .It Fl t , Fl -times
1.1 benno 128: Set destination file and directory modification time to match the source
129: when it is updated or created.
1.7 deraadt 130: .It Fl v , Fl -verbose
1.1 benno 131: Increase verbosity.
132: Specify once for files being transferred, twice for specific status,
133: thrice for per-file transfer information, and four times for per-file
134: breakdowns.
1.5 deraadt 135: .It Fl -version
136: Print version and exit.
1.1 benno 137: .El
138: .Pp
139: A remote
140: .Ar source
141: or
142: .Ar directory
143: has syntax
144: .Ar host:path
145: for connecting via
146: .Xr ssh 1 ,
147: or
148: .Ar rsync://host/path
149: or
150: .Ar host::path
151: for connecting to a remote daemon.
152: Subsequent to the first remote
153: .Ar source ,
154: the host may be dropped to become just
155: .Ar :path
156: or
157: .Ar ::path .
158: .Pp
159: For connecting to a remote daemon with
160: .Ar rsync://host
161: or
162: .Ar host::path ,
163: the first path component is interpreted as a
164: .Qq module :
165: .Ar host::module/path .
166: This only applies to the first
167: .Ar source
168: invocation; subsequent to that, the module should not be specified.
169: .Pp
170: By default, new destination files and directories are given the current
171: time and the source file permissions.
172: Updated files retain their existing permissions.
173: It is an error if updated files have their file types change (e.g.,
174: updating a directory with a file).
175: .Pp
176: At this time,
177: .Ar source
178: may only consist of regular files, directories
179: .Pq only with Fl r ,
180: or symbolic links
181: .Pq only with Fl l .
182: The destination
183: .Ar directory
184: must be a directory and is created if not found.
185: .Pp
186: .Nm
187: is compatible with the GPL-licensed
1.10 ! jmc 188: rsync protocol version 27.
1.1 benno 189: .\" The following requests should be uncommented and used where appropriate.
190: .\" .Sh CONTEXT
191: .\" For section 9 functions only.
192: .\" .Sh RETURN VALUES
193: .\" For sections 2, 3, and 9 function return values only.
194: .\" .Sh ENVIRONMENT
195: .\" For sections 1, 6, 7, and 8 only.
196: .\" .Sh FILES
197: .\" .Sh EXIT STATUS
198: .\" For sections 1, 6, and 8 only.
199: .Sh EXAMPLES
200: All examples use
201: .Fl t
202: so that destination files inherit the source time.
203: If not changed, subsequent invocations of
204: .Nm
205: will then consider the file up to date and not transfer block hashes.
206: .Pp
207: To update the out-of-date remote files
208: .Pa host:dest/bar
209: and
210: .Pa host:dest/baz
211: with the local
212: .Pa ../src/bar
213: and
214: .Pa ../src/baz :
215: .Pp
216: .Dl % rsync -t ../src/bar ../src/baz host:dest
217: .Pp
218: To update the out-of-date local files
219: .Pa bar
220: and
221: .Pa baz
222: with the remote files
223: .Pa host:src/bar
224: and
225: .Pa host:src/baz :
226: .Pp
227: .Dl % rsync -t host:src/bar :src/baz \&.
228: .Pp
229: To update the out-of-date local files
230: .Pa ../dest/bar
231: and
232: .Pa ../dest/baz
233: with
234: .Pa bar
235: and
236: .Pa baz :
237: .Pp
238: .Dl % rsync -t bar baz ../dest
239: .Pp
240: To update the out-of-date remote files in
241: .Pa host:dest
242: on a remote host running
243: .Nm
244: with the local host running
1.10 ! jmc 245: .Nm :
1.1 benno 246: .Pp
247: .Dl % rsync --rsync-path rsync -t ../dest/* host:dest
248: .\" .Sh DIAGNOSTICS
249: .\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
250: .\" .Sh ERRORS
251: .\" For sections 2, 3, 4, and 9 errno settings only.
252: .Sh SEE ALSO
253: .Xr ssh 1 ,
254: .Xr rsync 5 ,
255: .Xr rsyncd 5
256: .\" .Sh STANDARDS
257: .\" .Sh HISTORY
258: .\" .Sh AUTHORS
259: .\" .Sh CAVEATS
260: .\" .Sh BUGS