Hi,
here are serveral bugfixes and improvements for the rsync(1) manual.
OK?
Ingo
Bugfixes:
* For -D and -l: s/Transfer/Also transfer/.
* In the EXAMPLES, the renaming rsync -> openrsync caused a mess;
the worst aspect is the --rsync-path in the last example.
I don't have a good solution. I fear we will have to edit the
section again once we rename the program back to plain "rsync".
Missing information:
* Change the misleading argument placeholder "portnumber" to "service";
even the default ("rsync") isn't a number. In the description,
mention services(5), and also mention the default.
* Document the missing option --numeric-ids.
* Add the missing sections EXIT STATUS, HISTORY, AUTHORS.
Minor improvements:
* Drop the redundant phrases "Archive mode" and "Dry-run mode"
which are already clear form the long options right above: long
options cause enough verbosity already, so at least give them
the chance to convey some useful meaning.
* Add missing full stop for -D.
* Clarify which kind of program -e specifies; there are options
for specifying two different kinds of programs.
* Remove excessive verbosity from -g and -o, and improve precision:
- These options do *not* set the ID to match the source by default.
- The meaning of "verbatim" is unclear.
- Use the standard wording "user ID" and "group ID" like in
chgrp(1) find(1) ls(1) chown(2) stat(2) group(5) passwd(5) chown(8);
i can't see "group identifier" used anywhere else, and given
that the distinction between "group name" and "group ID" matters
here, let's avoid the unusual term.
* Recommend -v with -n, or people may either wonder what the point is
or incorrectly expect that -n might already imply -v.
* Describe -o in a self-contained way. It isn't so long that it
would justify giving readers the runaround.
* Do not call the source directory "the root directory";
the latter term generally refers to /.
* For --rsync-path, consistently use .Ar program, not .Ar prog, and
correct the markup of the default remote program name "rsync".
* Fix markup of argument syntax: host, module, and path have to be
replaced separately and the punctuation in between has to remain
exactly as shown in the manual, so do not mark up the punctuation
with .Ar. Also, "rsync" is a keyword in this context, to be given
verbatim, not a placeholder for something else.
* Move the compatibility statement into a STANDARDS section.
Even though the rsync protocal may not be a formal standard,
that's where such information fits best.
* Remove commented out sections that will never make sense in this page.
Index: main.c
===================================================================
RCS file: /cvs/src/usr.bin/rsync/main.c,v
retrieving revision 1.42
diff -u -r1.42 main.c
--- main.c 31 Mar 2019 13:17:44 -0000 1.42
+++ main.c 31 Mar 2019 16:24:03 -0000
@@ -505,8 +505,9 @@
exit(rc);
usage:
fprintf(stderr, "usage: %s"
- " [-aDglnoprtv] [-e program] [--del] [--port=portnumber]\n"
- "\t[--rsync-path=program] [--version] source ... directory\n",
+ " [-aDglnoprtv] [-e program] [--del] [--numeric-ids]\n"
+ "\t[--port=portnumber] [--rsync-path=program] [--version]\n"
+ "\tsource ... directory\n",
getprogname());
exit(1);
}
Index: rsync.1
===================================================================
RCS file: /cvs/src/usr.bin/rsync/rsync.1,v
retrieving revision 1.15
diff -u -r1.15 rsync.1
--- rsync.1 31 Mar 2019 13:17:44 -0000 1.15
+++ rsync.1 31 Mar 2019 16:24:04 -0000
@@ -25,7 +25,8 @@
.Op Fl aDglnoprtv
.Op Fl e Ar program
.Op Fl -del
-.Op Fl -port Ns = Ns Ar portnumber
+.Op Fl -numeric-ids
+.Op Fl -port Ns = Ns Ar service
.Op Fl -rsync-path Ns = Ns Ar program
.Op Fl -version
.Ar source ...
@@ -47,13 +48,12 @@
The arguments are as follows:
.Bl -tag -width Ds
.It Fl a , -archive
-Archive mode.
Shorthand for
.Fl Dgloprt .
.It Fl D
-Transfer device and special files.
+Also transfer device and special files.
Shorthand for
-.Fl -devices -specials
+.Fl -devices -specials .
.It Fl -del , -delete
Delete files in
.Ar directory
@@ -63,36 +63,50 @@
Only applicable with
.Fl r .
.It Fl -devices
-Transfer device files.
+Also transfer device files.
.It Fl e Ar program , Fl -rsh Ns = Ns Ar program
-Specify alternative program, defaults to
+Specify alternative communication program, defaults to
.Xr ssh 1 .
.It Fl g , -group
-Set group identifier to match the source.
-Groups are matched by name: group
-.Qq kristaps
-with id 1000 on a remote server will be properly assigned group
-.Qq kristaps
-on the local machine with id 2000.
-If the sender's group is unknown on the local machine, it is used
-verbatim.
+Set the group name to match the source.
+If
+.Fl -numeric-ids
+is also given or if the remote group name is unknown on the local machine,
+set the numeric group ID to match the source instead.
.It Fl l , -links
-Transfer symbolic links.
+Also transfer symbolic links.
The link is transferred as a standalone file: if the destination does
not exist, it will be broken.
.It Fl n , -dry-run
-Dry-run mode.
-Does not actually modify the destination.
-.It Fl o , -owner
-Set user identifier to match the source.
-This behaves like
+Do not actually modify the destination.
+Mainly useful in combination with
+.Fl v .
+.It Fl -numeric-ids
+Ignore user and group names, use numeric user and group IDs only.
+Has no effect unless
.Fl g
-and only works if run as root.
+or
+.Fl o
+is also given.
+.It Fl o , -owner
+Set the user name to match the source.
+If
+.Fl -numeric-ids
+is also given or if the remote user name is unknown on the local machine,
+set the numeric user ID to match the source instead.
+Only works if run as root.
.It Fl p , -perms
Set destination file or directory permissions to match the source when
it is updated.
-.It Fl -port Ns = Ns Ar portnumber
-Specify alternative port number.
+.It Fl -port Ns = Ns Ar service
+Specify an alternative TCP port number.
+The
+.Ar service
+can be given as a decimal integer or as a name to be looked up in the
+.Xr services 5
+database.
+The default is
+.Dq rsync .
.It Fl r , -recursive
If
.Ar source
@@ -100,18 +114,19 @@
connected at that point.
If
.Ar source
-ends with a slash, only the subtree is synchronised, not the root
-directory.
+ends with a slash, only the subtree is synchronised, not the
+.Ar source
+directory itself.
If
.Ar source
is a file, this has no effect.
.It Fl -rsync-path Ns = Ns Ar program
Run
-.Ar prog
+.Ar program
on the remote host instead of the default
-.Ar rsync .
+.Pa rsync .
.It Fl -specials
-Transfer fifo and unix domain socket files.
+Also transfer fifo and unix domain socket files.
.It Fl t , -times
Set destination file and directory modification time to match the source
when it is updated or created.
@@ -128,29 +143,29 @@
.Ar source
or
.Ar directory
-has syntax
-.Ar host:path
+has the syntax
+.Ar host : Ns Ar path
for connecting via
.Xr ssh 1 ,
or
-.Ar rsync://host/path
+.Cm rsync Ns :// Ns Ar host Ns / Ns Ar path
or
-.Ar host::path
+.Ar host Ns :: Ns Ar path
for connecting to a remote daemon.
Subsequent to the first remote
.Ar source ,
the host may be dropped to become just
-.Ar :path
+.Pf : Ar path
or
-.Ar ::path .
+.Pf :: Ar path .
.Pp
For connecting to a remote daemon with
-.Ar rsync://host
+.Cm rsync Ns :// Ns Ar host
or
-.Ar host::path ,
+.Ar host Ns :: Ns Ar path ,
the first path component is interpreted as a
.Qq module :
-.Ar host::module/path .
+.Ar host Ns :: Ns Ar module Ns / Ns Ar path .
This only applies to the first
.Ar source
invocation; subsequent to that, the module should not be specified.
@@ -170,20 +185,13 @@
The destination
.Ar directory
must be a directory and is created if not found.
-.Pp
-.Nm
-is compatible with the GPL-licensed
-rsync protocol version 27.
-.\" The following requests should be uncommented and used where appropriate.
-.\" .Sh CONTEXT
-.\" For section 9 functions only.
-.\" .Sh RETURN VALUES
-.\" For sections 2, 3, and 9 function return values only.
.\" .Sh ENVIRONMENT
-.\" For sections 1, 6, 7, and 8 only.
.\" .Sh FILES
-.\" .Sh EXIT STATUS
-.\" For sections 1, 6, and 8 only.
+.Sh EXIT STATUS
+The
+.Nm
+utility exits 0 on success, 1 if an error occurs, or 2 if the remote
+protocol version is older than the local protocol version.
.Sh EXAMPLES
All examples use
.Fl t
@@ -201,7 +209,7 @@
and
.Pa ../src/baz :
.Pp
-.Dl % rsync -t ../src/bar ../src/baz host:dest
+.Dl % openrsync -t ../src/bar ../src/baz host:dest
.Pp
To update the out-of-date local files
.Pa bar
@@ -212,7 +220,7 @@
and
.Pa host:src/baz :
.Pp
-.Dl % rsync -t host:src/bar :src/baz \&.
+.Dl % openrsync -t host:src/bar :src/baz \&.
.Pp
To update the out-of-date local files
.Pa ../dest/bar
@@ -223,7 +231,7 @@
and
.Pa baz :
.Pp
-.Dl % rsync -t bar baz ../dest
+.Dl % openrsync -t bar baz ../dest
.Pp
To update the out-of-date remote files in
.Pa host:dest
@@ -232,17 +240,24 @@
with the local host running
.Nm :
.Pp
-.Dl % rsync --rsync-path rsync -t ../dest/* host:dest
+.Dl % openrsync --rsync-path=openrsync -t ../dest/* host:dest
.\" .Sh DIAGNOSTICS
-.\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
-.\" .Sh ERRORS
-.\" For sections 2, 3, 4, and 9 errno settings only.
.Sh SEE ALSO
.Xr ssh 1 ,
.Xr rsync 5 ,
.Xr rsyncd 5
-.\" .Sh STANDARDS
-.\" .Sh HISTORY
-.\" .Sh AUTHORS
+.Sh STANDARDS
+.Nm
+is compatible with the GPL-licensed rsync protocol version 27.
+.Sh HISTORY
+The
+.Nm
+utility has been available since
+.Ox 6.5 .
+.Sh AUTHORS
+The
+.Nm
+utility was written by
+.An Kristaps Dzonsons Aq Mt krist...@bsd.lv .
.\" .Sh CAVEATS
.\" .Sh BUGS
