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