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