$obj = new File::Rsync;
$obj = File::Rsync->new;
$obj = File::Rsync->new(@options);
Create a File::Rsync object.
Any options passed at creation are stored in the object as defaults for all
future exec calls on that object.
Options may be passed in the style of a hash (key/value pairs) and are the
same as the long options in rsync(1) without the leading double-hyphen.
Any leading single or double-hyphens are removed, and you may use underscore
in place of hyphens in option names to simplify quoting and avoid possible
equation parsing (subtraction).
Although options are key/value pairs, as of version 0.46 the order is now
preserved. Passing a hash reference is still supported for backwards
compatibility, but is deprecated as order cannot be preserved for this case.
An additional option of <B>path-to-rsyncB> also exists which can be used to
override the using PATH environemt variable to find the rsync command binary,
and <B>moddebugB> which causes the module methods to print some debugging
information to STDERR.
There are also 2 options to wrap the source and/or destination paths in
double-quotes: these are <B>quote-srcB> and <B>quote-dstB>, which may be useful
in protecting the paths from shell expansion (particularly useful for paths
containing spaces). This wraps all source and/or destination paths in
double-quotes to limit remote shell expansion. It is similar but not
necessarily the same result as the <B>protect-argsB> option in rsync itself.
The <B>outfunB> and <B>errfunB> options take a function reference, called once
for each line of output from the rsync program with the output line passed
in as the first argument, the second arg is either out or err depending
on the source.
This makes it possible to use the same function for both and still determine
where the output came from.
If options are passed as a hash reference (deprecated), the <B>excludeB>
needs an array reference as its value since there cannot be duplicate keys
in a hash. Since order cannot be preserved in a hash, this module currently
limits the use of <B>excludeB> or <B>includeB> together.
They can be mixed together if options are in the form of a list or array ref.
Use the + or - prefix trick to put includes in an <B>excludeB> array, or
to put excludes in an <B>includeB> array (see rsync(1) for details).
Include/exclude options form an ordered list.
The order must be retained for proper execution.
There are also <B>sourceB> and <B>destB> keys.
The key <B>srcB> is also accepted as an equivalent to <B>sourceB>, and <B>dstB> or
<B>destinationB> may be used as equivalents to <B>destB>.
The <B>sourceB> option may take a scalar or an array reference.
If the source is the local system then multiple <B>sourceB> paths are allowed.
In this case an array reference should be used.
There is also a method for passing multiple source paths to a remote system.
This method may be triggered in this module by passing the remote hostname to
the <B>srchostB> key and passing an array reference to the <B>sourceB> key.
If the source host is being accessed via an Rsync server, the remote hostname
should have a single trailing colon on the name.
When rsync is called, the <B>srchostB> value and the values in the <B>sourceB>
array will be joined with a colon resulting in the double-colon required for
The <B>destB> key only takes a scalar since rsync only accepts a single
Version 2.6.0 of rsync(1) provides a new <B>files-fromB> option along with
a few other supporting options (<B>from0B>, <B>no-relativeB>, and
To support this wonderful new option at the level it deserves, this module
now has an additional parameter.
As of version 0.46 the value of <B>files-fromB> may be an array reference.
The contents of the array are passed to <B>files-fromB> the same as the
below method using <B>infunB> but implemented inside the module.
If <B>files-fromB> is set to - (meaning read from stdin) you can define
<B>infunB> to be a reference to a function that prints your file list to the
default file handle.
The output from the function is attached to stdin of the rsync call during
If <B>infunB> is defined it will be called regardless of the value of
<B>files-fromB>, so it can provide any data expected on stdin, but keep in mind
that stdin will not be attached to a tty so it is not very useful for sending
passwords (see the rsync(1) and ssh(1) man pages for ways to handle
The rsync(1) man page has a more complete description of <B>files-fromB>.
Also see File::Find for ideas to use with <B>files-fromB> and <B>infunB>.
The <B>infunB> option may also be used with the <B>include-fromB> or
<B>exclude-fromB> options, but this is generally more clumsy than using the
<B>includeB> or <B>excludeB> arrays.
Version 2.6.3 of rsync(1) provides new options <B>partial-dirB>,
<B>checksum-seedB>, <B>keep-dirlinksB>, <B>inplaceB>, <B>ipv4B>, and <B>ipv6B>.
Version 2.6.4 of rsync(1) provides new options <B>delB>, <B>delete-beforeB>
<B>delete-duringB>, <B>delay-updatesB>, <B>dirsB>, <B>filterB>, <B>fuzzyB>,
<B>itemize-changesB>, <B>list-onlyB>, <B>omit-dir-timesB>, <B>remove-sent-filesB>,
<B>max-sizeB>, and <B>protocolB>.
Version 0.38 of this module also added support for the <B>aclsB> option that
is not part of rsync(1) unless the patch has been applied, but people do
It also includes a new <B>literalB> option that takes an array reference
similar to <B>includeB>, <B>excludeB>, and <B>filterB>.
Any arguments in the array are passed as literal arguments to rsync, and are
They should have the proper single or double hyphen prefixes and the elements
should be split up the way you want them passed to exec.
The purpose of this option is to allow the use of arbitrary options added by
patches, and/or to allow the use of new options in rsync without needing an
imediate update to the module in addtition to rsync(1) itself.