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