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