Bug 14214 - --report-special=OPS option to return error code if no data was copied
Summary: --report-special=OPS option to return error code if no data was copied
Status: NEW
Alias: None
Product: rsync
Classification: Unclassified
Component: core (show other bugs)
Version: 3.1.3
Hardware: All All
: P5 enhancement (vote)
Target Milestone: ---
Assignee: Wayne Davison
QA Contact: Rsync QA Contact
Depends on:
Reported: 2019-12-10 20:44 UTC by Haravikk
Modified: 2019-12-10 20:44 UTC (History)
0 users

See Also:


Note You need to log in before you can comment on or make changes to this bug.
Description Haravikk 2019-12-10 20:44:05 UTC
I'm unsure of the best name for the option, but it would take the form:


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).