Man page suggestion: organize options into sections

Matt McCutchen hashproduct+rsync at
Sat Feb 3 21:22:01 GMT 2007

Dear rsync people (particularly Wayne),

I think it would be helpful for the options in the man page to be
divided into sections based on which aspect of rsync's behavior they
affect.  Each section could also document rsync's default behavior
when none of the options are given.  Collecting all the possibilities
for each aspect of rsync's behavior in one place would make it much
easier for users to compare the possibilities and identify which
option they want.  We're already seeing a little of this with the
"filter rules", "symbolic links", and "batch mode" sections.

The attached file is a draft of my proposed man page layout.  I like
the groupings, but I'm less certain about the order of either sections
or options within sections.

-------------- next part --------------

Remote & communication:
  Accessing a daemon:
    Getting a module list
    Single-use daemon over SSH
  Running a daemon:
    --daemon, etc.
  Internal options (--server, --sender)

What to do:

  -P [not the perfect place but likely the best]

File-list building:
  Trailing slash on source directories
  Incremental recursion

    Default behavior (source AND destination-default)
    Why you might want --chmod=ugo=rwX
  --archive [not the perfect place but likely the best]
  --hard-links [not the perfect place but likely the best]
  --acls [ACL branch]
  --xattrs [xattr branch]


Non-regular files:
  Symbolic links:
    Existing discussion
    Default behavior (skip noisily, don't follow on destination)

Up-to-date criterion ("quick check"):
  Default behavior (size and mtime)

File transfer mechanics:

Basis dirs:
  You can only use one kind!

Name-based exclusion:
  Detailed syntax of rules and merge files
  --from0 [not the perfect place but likely the best]

Other exclusion:


Batch mode:
  Existing discussion

More information about the rsync mailing list