Rsync CLI Wrapper

0.6.1 · active · verified Wed Apr 22

node-rsync is a Node.js library that provides a programmatic interface for building and executing `rsync` commands. It functions as a wrapper around the system's `rsync` utility, allowing developers to construct complex synchronization commands using a fluent API in JavaScript or TypeScript applications. The current stable version is 0.6.1. Releases are infrequent, typically addressing specific bugs or adding minor enhancements (such as Windows path support), rather than following a strict cadence. Its primary utility lies in automating file synchronization, backup tasks, and deployments within Node.js environments by abstracting the command-line intricacies of `rsync` into a more manageable, object-oriented structure.

Common errors

```
Error: spawn rsync ENOENT
```
cause The operating system cannot find the `rsync` executable. This typically means `rsync` is not installed or not in the system's PATH.

fix Install the `rsync` utility on your system. For example, `sudo apt-get install rsync` (Linux), `brew install rsync` (macOS), or ensure it's available in your chosen Windows environment (e.g., WSL, Cygwin).
```
rsync error: syntax or usage error (code 1) at main.c(XXX) [client=X.X.X]
```
cause The `rsync` command generated by `node-rsync` contains an invalid option, flag, or argument combination. This often occurs due to a typo or misunderstanding of `rsync`'s command-line syntax when using `.set()` or `.flags()`.

fix Call `rsync.command()` to inspect the full `rsync` command string. Execute this string manually in your terminal to debug the `rsync` error directly, then adjust your `node-rsync` builder calls accordingly.
```
rsync: [sender] failed to open ...: No such file or directory (2)
```
cause One of the specified source or destination paths does not exist or is inaccessible to the user running the `rsync` command. This can also happen with incorrect path formats, especially on Windows.

fix Verify that both your source and destination paths are correct, exist, and have appropriate read/write permissions for the user executing the `node-rsync` process. For Windows, ensure paths are correctly formatted (e.g., using `/` instead of `\` or correctly mapping Cygwin paths).

Warnings

gotcha This library acts as a wrapper for the system's `rsync` command-line utility. The `rsync` binary must be pre-installed and available in the system's PATH for this package to function. The Node.js package does not bundle the `rsync` executable itself.
Fix: Ensure `rsync` is installed on your operating system. For Linux (Debian/Ubuntu): `sudo apt-get install rsync`; for macOS: `brew install rsync`; for Windows: utilize WSL, Cygwin, or a similar environment with `rsync`.
gotcha The `.set(option, value)` method and other configuration methods (like `.flags()`) do not validate options or arguments against the official `rsync` manual. Providing incorrect options, malformed values, or values for valueless flags can lead to silent `rsync` failures (exit code 1, 23, etc.) that are only discoverable during execution.
Fix: Always consult the official `rsync` man page (`man rsync`) or documentation for correct options and syntax. Test complex `rsync` commands directly on the command line before integrating them into `node-rsync`.
breaking Older versions of `node-rsync` (prior to 0.6.1) had known issues with handling Windows file paths, particularly when running `rsync` through environments like Cygwin. This could lead to incorrect path resolution, 'No such file or directory' errors, or failed synchronizations.
Fix: Upgrade to `node-rsync` version 0.6.1 or newer, which includes explicit support for Windows file paths under Cygwin. If upgrading isn't possible, ensure all paths are strictly POSIX-style (e.g., `/cygdrive/c/path`) and avoid native Windows path separators.

Install

npm install rsync npm
yarn add rsync yarn
pnpm add rsync pnpm

Imports

Rsync
```
const Rsync = require('rsync');
```
This package is primarily a CommonJS module. This is the canonical and most reliable import method for Node.js environments.
Rsync
```
import Rsync from 'rsync';
```
When used in an ESM environment, bundlers (like Webpack, Rollup) or Node.js's built-in CJS-ESM interop will typically treat the `Rsync` class as the default export of the module.
Rsync
wrong:
```
import { Rsync } from 'rsync';
```
correct:
```
import Rsync from 'rsync';
```
Attempting a named import (`import { Rsync }`) for this CommonJS package's single export will typically result in `undefined` for `Rsync`, as it's not explicitly exported as a named member. Use the default import syntax instead.

Quickstart

Demonstrates how to initialize an Rsync instance, configure a basic remote synchronization command using SSH, common flags (archive, compress), and then execute it with error handling.

const Rsync = require('rsync');

// 1. Build the rsync command configuration
const rsync = new Rsync()
  .shell('ssh')                 // Use SSH for remote connections
  .flags('az')                 // 'a' for archive mode, 'z' for compress
  .source('/path/to/local/source/') // Local directory to synchronize from
  .destination('user@remote.server:/path/to/remote/destination/'); // Remote destination

// 2. Execute the command and handle results
rsync.execute(function(error, code, cmd) {
    if (error) {
        console.error('Rsync command failed:', error.message);
        console.error('Exit Code:', code);
        console.error('Executed Command:', cmd);
        // Depending on `code`, you might want to retry or log specific errors
    } else {
        console.log('Rsync command completed successfully.');
        console.log('Executed Command:', cmd);
        // Further processing after successful synchronization
    }
});

view raw JSON →