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