Man page suggestion: organize options into sections

Matt McCutchen hashproduct+rsync at gmail.com
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.

Matt
-------------- next part --------------
General:
  --help
  --version

Remote & communication:
  --protocol
  SSH:
    Single-colon
    --rsh
    --rsync-path
  Accessing a daemon:
    Double-colon
    rsync://
    --password-file
    --address
    --port
    --sockopts
    --ipv4
    --ipv6
    Getting a module list
    Single-use daemon over SSH
  --blocking-io
  --bwlimit
  --timeout
  Running a daemon:
    --daemon, etc.
  Internal options (--server, --sender)

What to do:
  --dry-run
  --list-only
  --super

Output:
  --verbose
  --quiet
  --no-motd
  --log-file
  --log-file-format
  --out-format
  --itemize-changes
  --progress
  -P [not the perfect place but likely the best]
  --stats
  --8-bit-output
  --human-readable

File-list building:
  Trailing slash on source directories
  --dirs
  --recursive
  Incremental recursion
  --one-file-system
  --relative
  --no-implied-dirs
  --prune-empty-dirs
  --files-from

Attributes:
  --times
  --omit-dir-times
  Permissions:
    Default behavior (source AND destination-default)
    --executability
    --perms
    --chmod
    Why you might want --chmod=ugo=rwX
  --owner
  --group
  --numeric-ids
  --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]

Deletion:
  --delete
  --delete-before
  --delete-during
  --delete-delay
  --delete-after
  --force
  --max-delete

Non-regular files:
  Symbolic links:
    Existing discussion
    Default behavior (skip noisily, don't follow on destination)
    --links
    --copy-links
    --copy-dirlinks
    --safe-links
    --copy-unsafe-links
    --keep-dirlinks
  --devices
  --specials
  -D

Up-to-date criterion ("quick check"):
  Default behavior (size and mtime)
  --modify-window
  --checksum
  --ignore-times
  --size-only

File transfer mechanics:
  --whole-file
  --block-size
  --checksum-seed
  --inplace
  --sparse
  --append
  --delay-updates
  --partial
  --partial-dir
  --temp-dir
  --remove-source-files
  --compress
  --compress-level

Basis dirs:
  --compare-dest
  --copy-dest
  --link-dest
  You can only use one kind!
  --fuzzy

Name-based exclusion:
  Detailed syntax of rules and merge files
  --filter
  -F
  --{include,exclude}{,-from}
  --from0 [not the perfect place but likely the best]
  --cvs-exclude
  --delete-excluded

Other exclusion:
  --update
  --ignore-{,non-}existing
  --{min,max}-size

Backup:
  --backup
  --suffix
  --backup-dir

Batch mode:
  Existing discussion
  --read-batch
  --write-batch
  --only-write-batch


More information about the rsync mailing list