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