[Bug 14214] New: --report-special=OPS option to return error code if no data was copied

[samba-bugs at samba.org]

https://bugzilla.samba.org/show_bug.cgi?id=14214

            Bug ID: 14214
           Summary: --report-special=OPS option to return error code if no
                    data was copied
           Product: rsync
           Version: 3.1.3
          Hardware: All
                OS: All
            Status: NEW
          Severity: enhancement
          Priority: P5
         Component: core
          Assignee: wayne at opencoder.net
          Reporter: samba at haravikk.com
        QA Contact: rsync-qa at samba.org

I'm unsure of the best name for the option, but it would take the form:

    --report-special=OPS

Where OPS specifies one or more comma-separated special conditions that will
cause rsync to return a reserved non-zero status indicating that one or more of
these occurred. These do not actually indicate errors, and will not interrupt
rsync (indeed, they require it to finish the transfer first), but may be useful
when scripting around rsync to know whether other code should continue or not,
or whether your operation was successful or not.

Options include:

* nodata: Indicates that although rsync ran successfully, no file data was
transferred (this does not mean that no files or directories were created,
metadata modified etc.)
* nonew: Indicates that although rsync ran successfully, no new files were
created/linked (i.e- if any transfer occurred, it was for existing files only)
* nodelete: Indicates that although rsync ran successfully, no files were
removed
* nometa: Indicates that although rsync ran successfully, no metadata changed
(timestamps, permissions, ownership, extended attributes etc.)
* nochange: Shorthand for nodata,nonew,nodelete,nometa effectively indicating
that although rsync ran successfully, no changes occurred at all


There may be others that might be worth adding, but these are the two main ones
IMO. I'm uncertain whether rsync should give each a unique status code, or if
there should just be one status code for any special condition being met.

The idea here is to give us new options when scripting, and avoid the need to
parse rsync's output/log to get this information.

For example, let's say I'm using rsync to copy data onto a file-system that
supports snapshots, I could use the following command:

    rsync --report-special=nochange /path/to/source /path/to/target

If I get the reserved status code back it means that no changes were found
between /path/to/source and /path/to/target, in which case there is no need for
me to create a new snapshot, as there would be nothing new to rollback to (or
backup further).


Currently the alternative is to either grab the output of --stats and parse it
for created/deleted files and literal data transferred, or use
--itemize-changes and test the number of lines of output (none means no
change), depending upon what else you may need the output for (logs, printing
to terminal etc.). Neither of these is ideal, and even if they were I think it
would still be nice to have an authoritative response from rsync itself, based
upon what the user/script needs to know.

This information should already be available as it's the same basic data
reported by --stats (though --stats does not appear to report metadata/xattr
only changes, unless they show up as data).

-- 
You are receiving this mail because:
You are the QA Contact for the bug.