On 4/19/07, C Sights <[EMAIL PROTECTED]> wrote:
After reading what you both have said, and throwing in some things from
previous knowledge, it seems as though what rsync does can be broken up into
a number pieces.
[...]
It might make the rsync manual more understandable if the long options were
broken up into sections corresponding to these pieces (or other more fitting
pieces). In each section rsync's default behavior is explained, followed by
the switches that change the default behavior.
I proposed essentially the same thing here:
http://lists.samba.org/archive/rsync/2007-February/017221.html
Let's work on an improved man page together!
To make it easier to explain how rsync works and easier to write the sections
I have diverged from rsync's actual behavior. Mostly, the conscious changes
were made to the "how files updated" section (which is what started this
conversation). I've added an imaginary --tweak option. This option tweaks
metadata if that is the only thing that has changed and can be used with
any "detecting changed files" check.
I like letting the user choose whether to tweak or rewrite the file,
but IMNSHO, --tweak should remain the default behavior. The only
times you would want --no-tweak are (1) when you never want a process
to see an intermediate state of a file with some but not all tweaks
performed and (2) when you don't want to affect other hard links, in
which case you could use a milder option --no-tweak-hlinked that I
proposed here:
http://lists.samba.org/archive/rsync/2006-September/016207.html
Most users currently in situation (2) elect to receive into a new
destination dir specifying the old one as a --link-dest basis dir,
which would have the same semantics as receiving into the original
destination with --no-tweak.
The conscious changes to the "detecting changed files" part of the manual is
to add that all metadata specified to be transferred is also used when
detecting changed files. I believe this is how rsync behaves.
[...]
By default rsync checks that both the file's size, last modification time and
any selected metadata to be transferred match on the sender and receiver. If
the size, last modification time, or any metadata does not match, the file is
transferred.
(The standard term for "selecting metadata to be transferred" is
preserving that metadata.)
That is not rsync's current default behavior. It would be rsync's
default behavior if --no-tweak were made the default, except for one
technicality. Rewriting due to a preserved metadata difference would
be considered a local creation rather than a transfer and itemized
with first character "c" rather than "<" or ">", just as with
--link-dest.
I would explain it like this:
By default, rsync considers a file's data to be unchanged if its size
and last modification time match. If rsync considers the data
changed, it transfers the file. If rsync considers the data unchanged
but preserved metadata differs, rsync applies the new metadata to the
existing file ("tweaks" the file) unless directed not to do so by
--no-tweak or --no-tweak-hlinked. In this case, the receiver locally
copies the file, applies the new metadata to the copy, and moves the
copy over the original.
Options for changing what is transferred:
By default rsync transfers _____??_____.
...none of the below and allows the act of transferring (or, I
suppose, locally recreating) a file to set its last-modification time
to the current time.
-p, --perms
long description here
I think you still mean something different by "transfer" than the rest
of us (and the existing man page) do. "Transferring" refers only to a
regular file's *data*, not permissions, times, or anything like that.
(The "transfer" also sometimes refers to the entire file list or rsync
run, but Wayne has been moving away from this usage.) Please refer to
these options as options for changing what is "preserved".
Options for changing how files are updated on the receiver:
By default rsync creates a temporary file on the receiver, deletes the old
file, then moves the temporary file to the place of the old file.
Again, this assumes --no-tweak is made the default. IMNSHO, the
default should remain --tweak.
Options controlling how files are deleted on receiver:
By default rsync does not delete any files that exist on the receiver but not
the sender.
You could just say "By default rsync does not delete any files from
the destination".
--delete
delete extraneous files from dest dirs before new files are transferred.
--delete-before
same as --delete
Better to define --delete-before and say "--delete: same as
--delete-before", because I think Wayne is considering changing
--delete to mean --delete-during sometime in the future.
--delete-excluded
long description here
I think this option would go better in the section about exclude
filters since the effect of --delete-excluded is essentially to make
"-" mean "H" instead of "H" plus "P".
So, using the motivating example (two files have same contents, (same size,)
different modtimes):
[examples]
All of your examples were accurate assuming --no-tweak is made the
default, except that --no_t should be --no-t (hyphen).
Matt
--
To unsubscribe or change options: https://lists.samba.org/mailman/listinfo/rsync
Before posting, read: http://www.catb.org/~esr/faqs/smart-questions.html
