@mattlyons/rsync
Advanced tools
Rsync is a class for building and executing rsync commands with Node.js.
Installation goes through NPM:
$ npm install rsync
This module is licensed under the MIT License. See the LICENSE file for more details.
var Rsync = require('rsync');
// Build the command
var rsync = new Rsync()
.shell('ssh')
.flags('az')
.source('/path/to/source')
.destination('server:/path/to/destination');
// Execute the command
rsync.execute(function(error, code, cmd) {
// we're done
});
For more examples see the examples directory.
Construct a new Rsync command instance. The constructor takes no arguments.
var rsync = new Rsync();
Set an option. This can be any option from the rsync manual. The value is optional and only applies to options that take a value. This is not checked however. Supplying a value for an option that does not take a value will append the value regardless. This may cause errors when the command is executed.
rsync.set('a')
.set('progress')
.set('list-only')
.set('exclude-from', '/path/to/exclude-file');
Options must be unique and setting the same option twice will override any existing value. For options that can be set multiple times special methods exist (see accessor methods). Any leading dashes (-) are stripped when setting the option.
The set method is chainable.
Unset an option. Any leading dashes (-) are stripped when unsetting an option.
rsync.unset('progress')
.unset('quiet');
The unset method is chainable.
Set one or more flags. Flags are single letter options without a value, for example compress (-z) or archive (-a).
The flags method is a polymorphic function: it can take different arguments to set flags.
Flags can be presented as a single string with multiple flags, multiple strings as arguments, an array containing strings or an object with the flags as keys.
Whether the presented flags need to be set or unset is determined based on the last argument, if this is a Boolean. When presenting the flags as an Object the value for each key (flag) determines if the flag is set or unset. This version can be used to mix setting and unsetting of flags in one statement.
// As String
rsync.flags('avz'); // set
rsync.flags('avz', false); // unset
// As String arguments
rsync.flags('a', 'v', 'z'); // set
rsync.flags('a', 'v', 'z', false); // unset
// As Array
rsync.flags(['a', 'v', 'z']); // set
rsync.flags(['a', 'z'], false); // unset
// As Object
rsync.flags({
'a': true, // set
'z': true, // set
'v': false // unset
});
The flags method is chainable.
Check if an option is set.
This method does not check alternate versions for an option. When an option is set as the short version this method will still return false when checking for the long version, event though they are the same option.
rsync.set('quiet');
rsync.isSet('quiet'); // is TRUE
rsync.isSet('q'); // is FALSE
Get the value for an option by name. If a valueless option is requested null will be returned.
rsync.option('rsh'); // returns String value
rsync.option('progress'); // returns NULL
Get the arguments list for the command that is going to be executed. Returns an Array with the complete options that will be passed to the command.
Get the complete command that is going to be executed.
var rsync = new Rsync()
.shell('ssh')
.flags('az')
.source('/p/t/source')
.destination('server:/p/t/dest');
var c = rsync.command();
// c is "rsync -az --rsh="ssh" /p/t/source server:/p/t/dest
Set or get the value for rsync process cwd.
rsync.cwd(__dirname); // Set cwd to __dirname
rsync.cwd(); // Get cwd value
Set or get the value for rsync process environment variables.
Default: process.env
rsync.env(process.env); // Set env to process.env
rsync.env(); // Get env values
Register output handler functions for the commands stdout and stderr output. The handlers will be called with streaming data from the commands output when it is executed.
rsync.output(
function(data){
// do things like parse progress
}, function(data) {
// do things like parse error output
}
);
This method can be called with an array containing one or two functions. These functions will
be treated as the stdoutHandler and stderrHandler arguments. This makes it possible to register
handlers through the Rsync.build method by specifying the functions as an array.
var rsync = Rsync.build({
// ...
output: [stdoutFunc, stderrFunc] // these are references to functions defined elsewhere
// ...
});
Execute the command. The callback function is called with an Error object (or null when there was none), the exit code from the executed command and the executed command as a String.
When stdoutHandler and stderrHandler functions are provided they will be used to stream
data from stdout and stderr directly without buffering. Any output handlers that were
defined previously will be overwritten.
The function returns the child process object, which can be used to kill the rsync process or clean up if the main program exits early.
// signal handler function
var quitting = function() {
if (rsyncPid) {
rsyncPid.kill();
}
process.exit();
}
process.on("SIGINT", quitting); // run signal handler on CTRL-C
process.on("SIGTERM", quitting); // run signal handler on SIGTERM
process.on("exit", quitting); // run signal handler when main process exits
// simple execute
var rsyncPid = rsync.execute(function(error, code, cmd) {
// we're done
});
// execute with stream callbacks
var rsyncPid = rsync.execute(
function(error, code, cmd) {
// we're done
}, function(data){
// do things like parse progress
}, function(data) {
// do things like parse error output
}
);
The following option shorthand methods are available:
--rsh=SHELL--delete--progress-a-z-r-u-q-d-l-n--chmod=VALUE (accumulative)-H-p-E-o-g-A-X--devices--specials-tAll shorthand methods are chainable as long as options that require a value are provided with one.
These methods can be used to get or set values in a chainable way. When the methods are called without arguments the current value is returned. When the methods are called with a value this will override the current value and the Rsync instance is returned to provide the chainability.
Get or set the executable to use as the rsync command.
Get or set the shell to use to launch the rsync command on non-Windows (Unix and Mac OS X) systems. The default shell is /bin/sh.
On some systems (Debian, for example) /bin/sh links to /bin/dash, which does not do proper process control. If you have problems with leftover processes, try a different shell such as /bin/bash.
Get or set the destination for the rsync command.
Get or set the source or sources for the rsync command. When this method is called multiple times with a value it is appended to the list of sources. It is also possible to present the list of source as an array where each value will be appended to the list of sources
// chained
rsync.source('/a/path')
.source('/b/path');
// as Array
rsync.source(['/a/path', '/b/path']);
In both cases the list of sources will contain two paths.
Register a list of file patterns to include/exclude in the transfer. Patterns can be registered as an array of Strings or Objects.
When registering a pattern as a String it be prefixed with a + or - sign to
signal include or exclude for the pattern. The sign will be stripped of and the
pattern will be added to the ordered pattern list.
When registering the pattern as an Object it must contain the action and
pattern keys where action contains the + or - sign and the pattern
key contains the file pattern, without the + or - sign.
The order of patterns is important for some rsync commands. The patterns are stored in the order
they are added either through the patterns method or the include and exclude methods. The
patterns method can be used with Rsync.build to provide an ordered list for the command.
// on an existing Rsync object
rsync.patterns([ '-.git', { action: '+', pattern: '/some_dir' });
// through Rsync.build
var command = Rsync.build({
// ...
patterns: [ '-.git', { action: '+', pattern: '/some_dir' } ]
// ...
});
Exclude a pattern from transfer. When this method is called multiple times with a value it is appended to the list of patterns. It is also possible to present the list of excluded patterns as an array where each pattern will be appended to the list.
// chained
rsync.exclude('.git')
.exclude('.DS_Store');
// as Array
rsync.exclude(['.git', '.DS_Store']);
Include a pattern for transfer. When this method is called multiple times with a value it is appended to the list of patterns. It is also possible to present the list of included patterns as an array where each pattern will be appended to the list.
// chained
rsync.include('/a/file')
.include('/b/file');
// as Array
rsync.include(['/a/file', '/b/file']);
Get or set the debug flag. This is only used internally and must be a Boolean to set or unset.
For convenience there is the build function on the Rsync contructor. This function can be
used to create a new Rsync command instance from an options object.
For each key in the options object the corresponding method on the Rsync instance will be called. When a function for the key does not exist it is ignored. An existing Rsync instance can optionally be provided.
var rsync = Rsync.build({
source: '/path/to/source',
destination: 'server:/path/to/destination',
exclude: ['.git'],
flags: 'avz',
shell: 'ssh'
});
rsync.execute(function(error, stdout, stderr) {
// we're done
});
If there is something missing (which there probably is) just fork, patch and send a pull request.
For adding a new shorthand method there are a few simple steps to take:
exposeShortOption, exposeLongOption or exposeMultiOption functions. For examples see the source file.When adding a shorthand make sure it does not already exist, it is a sane name and a shorthand is necessary.
If there is something broken (which there probably is), the same applies: fork, patch, pull request. Opening an issue is also possible.
v0.6.1
v0.6.0
v0.5.0
v0.4.0
execute (#27)v0.3.0
v0.2.0
v0.1.0
v0.0.2
v0.0.1
FAQs
Rsync cli wrapper
We found that @mattlyons/rsync demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.