{"id":22484914,"url":"https://github.com/mattijs/node-rsync","last_synced_at":"2025-08-02T18:30:53.316Z","repository":{"id":6165944,"uuid":"7395652","full_name":"mattijs/node-rsync","owner":"mattijs","description":"Rsync wrapper for Node.js","archived":true,"fork":false,"pushed_at":"2021-12-20T11:48:04.000Z","size":82,"stargazers_count":283,"open_issues_count":22,"forks_count":64,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-12-06T17:13:24.680Z","etag":null,"topics":["javascript","js","mit","node","nodejs"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mattijs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-01-01T13:38:32.000Z","updated_at":"2024-11-15T22:58:14.000Z","dependencies_parsed_at":"2022-09-05T22:40:54.449Z","dependency_job_id":null,"html_url":"https://github.com/mattijs/node-rsync","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/mattijs/node-rsync","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattijs%2Fnode-rsync","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattijs%2Fnode-rsync/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattijs%2Fnode-rsync/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattijs%2Fnode-rsync/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mattijs","download_url":"https://codeload.github.com/mattijs/node-rsync/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattijs%2Fnode-rsync/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268432625,"owners_count":24249585,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-02T02:00:12.353Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript","js","mit","node","nodejs"],"created_at":"2024-12-06T17:11:44.855Z","updated_at":"2025-08-02T18:30:53.061Z","avatar_url":"https://github.com/mattijs.png","language":"JavaScript","readme":"# Rsync ![build status](https://travis-ci.org/mattijs/node-rsync.svg?branch=master)\n\n[![NPM](https://nodei.co/npm/rsync.png?downloads=true)](https://nodei.co/npm/rsync/)\n\n`Rsync` is a class for building and executing `rsync` commands with Node.js.\n\n## Installation\n\nInstallation goes through NPM:\n\n```\n$ npm install rsync\n```\n\n## License\n\nThis module is licensed under the MIT License. See the `LICENSE` file for more details.\n\n## Simple usage\n\n```javascript\nvar Rsync = require('rsync');\n\n// Build the command\nvar rsync = new Rsync()\n  .shell('ssh')\n  .flags('az')\n  .source('/path/to/source')\n  .destination('server:/path/to/destination');\n\n// Execute the command\nrsync.execute(function(error, code, cmd) {\n    // we're done\n});\n```\n\nFor more examples see the `examples` directory.\n\n# API\n\n  * [constructor](#constructor)\n  * [instance methods](#instance-methods)\n  * [accessor methods](#accessor-methods)\n  * [static methods](#static-methods)\n\n## constructor\n\nConstruct a new Rsync command instance. The constructor takes no arguments.\n\n```javascript\nvar rsync = new Rsync();\n```\n\n## instance methods\n\n### set(option, value)\n\nSet 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.\n\n```javascript\nrsync.set('a')\n  .set('progress')\n  .set('list-only')\n  .set('exclude-from', '/path/to/exclude-file');\n```\n\nOptions 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.\n\nThe `set` method is chainable.\n\n### unset(option)\n\nUnset an option. Any leading dashes (-) are stripped when unsetting an option.\n\n```javascript\nrsync.unset('progress')\n  .unset('quiet');\n```\n\nThe `unset` method is chainable.\n\n### flags(flags, set)\n\nSet one or more flags. Flags are single letter options without a value, for example _compress_ (`-z`) or _archive_ (`-a`).\n\nThe `flags` method is a polymorphic function: it can take different arguments to set flags.\nFlags 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.\n\nWhether 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.\n\n```javascript\n// As String\nrsync.flags('avz');        // set\nrsync.flags('avz', false); // unset\n\n// As String arguments\nrsync.flags('a', 'v', 'z');        // set\nrsync.flags('a', 'v', 'z', false); // unset\n\n// As Array\nrsync.flags(['a', 'v', 'z']);   // set\nrsync.flags(['a', 'z'], false); // unset\n\n// As Object\nrsync.flags({\n  'a': true, // set\n  'z': true, // set\n  'v': false // unset\n});\n```\n\nThe `flags` method is chainable.\n\n### isSet(option)\n\nCheck if an option is set.\n\nThis 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.\n\n```javascript\nrsync.set('quiet');\nrsync.isSet('quiet'); // is TRUE\nrsync.isSet('q');     // is FALSE\n```\n\n### option(option)\n\nGet the value for an option by name. If a valueless option is requested null will be returned.\n\n```javascript\nrsync.option('rsh');      // returns String value\nrsync.option('progress'); // returns NULL\n```\n\n### args()\n\nGet 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.\n\n### command()\n\nGet the complete command that is going to be executed.\n\n```javascript\nvar rsync = new Rsync()\n  .shell('ssh')\n  .flags('az')\n  .source('/p/t/source')\n  .destination('server:/p/t/dest');\n\nvar c = rsync.command();\n// c is \"rsync -az --rsh=\"ssh\" /p/t/source server:/p/t/dest\n```\n\n### cwd(path)\n\nSet or get the value for rsync process cwd.\n\n```javascript\nrsync.cwd(__dirname); // Set cwd to __dirname\nrsync.cwd(); // Get cwd value\n```\n\n### env(envObj)\n\nSet or get the value for rsync process environment variables.\n\nDefault: process.env\n\n```javascript\nrsync.env(process.env); // Set env to process.env\nrsync.env(); // Get env values\n```\n\n### output(stdoutHandler, stderrHandler)\n\nRegister output handler functions for the commands stdout and stderr output. The handlers will be\ncalled with streaming data from the commands output when it is executed.\n\n```javascript\nrsync.output(\n    function(data){\n        // do things like parse progress\n    }, function(data) {\n        // do things like parse error output\n    }\n);\n```\n\nThis method can be called with an array containing one or two functions. These functions will\nbe treated as the stdoutHandler and stderrHandler arguments. This makes it possible to register\nhandlers through the `Rsync.build` method by specifying the functions as an array.\n\n```javascript\nvar rsync = Rsync.build({\n    // ...\n    output: [stdoutFunc, stderrFunc] // these are references to functions defined elsewhere\n    // ...\n});\n```\n\n### execute(callback, stdoutHandler, stderrHandler)\n\nExecute the command. The callback function is called with an Error object (or null when there\nwas none), the exit code from the executed command and the executed command as a String.\n\nWhen `stdoutHandler` and `stderrHandler` functions are provided they will be used to stream\ndata from stdout and stderr directly without buffering. Any output handlers that were\ndefined previously will be overwritten.\n\nThe function returns the child process object, which can be used to kill the\nrsync process or clean up if the main program exits early.\n\n```javascript\n// signal handler function\nvar quitting = function() {\n  if (rsyncPid) {\n    rsyncPid.kill();\n  }\n  process.exit();\n}\nprocess.on(\"SIGINT\", quitting); // run signal handler on CTRL-C\nprocess.on(\"SIGTERM\", quitting); // run signal handler on SIGTERM\nprocess.on(\"exit\", quitting); // run signal handler when main process exits\n\n// simple execute\nvar rsyncPid = rsync.execute(function(error, code, cmd) {\n    // we're done\n});\n\n// execute with stream callbacks\nvar rsyncPid = rsync.execute(\n    function(error, code, cmd) {\n        // we're done\n    }, function(data){\n        // do things like parse progress\n    }, function(data) {\n        // do things like parse error output\n    }\n);\n```\n\n## option shorthands\n\nThe following option shorthand methods are available:\n\n  - **shell(value)**: `--rsh=SHELL`\n  - **delete()**: `--delete`\n  - **progress()**: `--progress`\n  - **archive()**: `-a`\n  - **compress()**: `-z`\n  - **recursive()**: `-r`\n  - **update()**: `-u`\n  - **quiet()**: `-q`\n  - **dirs()**: `-d`\n  - **links()**: `-l`\n  - **dry()**: `-n`\n  - **chmod(value)**: `--chmod=VALUE` (accumulative)\n  - **hardLinks()**: `-H`\n  - **perms()**: `-p`\n  - **executability()**: `-E`\n  - **owner()**: `-o`\n  - **group()**: `-g`\n  - **acls()**: `-A`\n  - **xattrs()**: `-X`\n  - **devices()**: `--devices`\n  - **specials**: `--specials`\n  - **times()**: `-t`\n\n\nAll shorthand methods are chainable as long as options that require a value are provided with one.\n\n## accessor methods\n\nThese 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.\n\n### executable(executable)\n\nGet or set the executable to use as the rsync command.\n\n### executableShell(shell)\n\nGet 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.  \n\nOn 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.\n\n### destination(destination)\n\nGet or set the destination for the rsync command.\n\n### source(source)\n\nGet 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\n\n```javascript\n// chained\nrsync.source('/a/path')\n  .source('/b/path');\n\n// as Array\nrsync.source(['/a/path', '/b/path']);\n```\n\nIn both cases the list of sources will contain two paths.\n\n### patterns(patterns)\n\nRegister a list of file patterns to include/exclude in the transfer. Patterns can be registered as\nan array of Strings or Objects.\n\nWhen registering a pattern as a String it be prefixed with a `+` or `-` sign to\nsignal include or exclude for the pattern. The sign will be stripped of and the\npattern will be added to the ordered pattern list.\n\nWhen registering the pattern as an Object it must contain the `action` and\n`pattern` keys where `action` contains the `+` or `-` sign and the `pattern`\nkey contains the file pattern, without the `+` or `-` sign.\n\nThe order of patterns is important for some rsync commands. The patterns are stored in the order\nthey are added either through the `patterns` method or the `include` and `exclude` methods. The\n`patterns` method can be used with `Rsync.build` to provide an ordered list for the command.\n\n```javascript\n// on an existing Rsync object\nrsync.patterns([ '-.git', { action: '+', pattern: '/some_dir' });\n\n// through Rsync.build\nvar command = Rsync.build({\n    // ...\n    patterns: [ '-.git', { action: '+', pattern: '/some_dir' } ]\n    // ...\n});\n```\n### exclude(pattern)\n\nExclude a pattern from transfer. When this method is called multiple times with a value it is\nappended to the list of patterns. It is also possible to present the list of excluded\npatterns as an array where each pattern will be appended to the list.\n\n```javascript\n// chained\nrsync.exclude('.git')\n  .exclude('.DS_Store');\n\n// as Array\nrsync.exclude(['.git', '.DS_Store']);\n```\n\n### include(pattern)\n\nInclude a pattern for transfer. When this method is called multiple times with a value it is\nappended to the list of patterns. It is also possible to present the list of included patterns as\nan array where each pattern will be appended to the list.\n\n```javascript\n// chained\nrsync.include('/a/file')\n  .include('/b/file');\n\n// as Array\nrsync.include(['/a/file', '/b/file']);\n```\n\n### debug(flag)\n\nGet or set the debug flag. This is only used internally and must be a Boolean to set or unset.\n\n## static methods\n\n### build\n\nFor convenience there is the `build` function on the Rsync contructor. This function can be\nused to create a new Rsync command instance from an options object.\n\nFor each key in the options object the corresponding method on the Rsync instance will be\ncalled. When a function for the key does not exist it is ignored. An existing Rsync instance\ncan optionally be provided.\n\n```javascript\nvar rsync = Rsync.build({\n  source:      '/path/to/source',\n  destination: 'server:/path/to/destination',\n  exclude:     ['.git'],\n  flags:       'avz',\n  shell:       'ssh'\n});\n\nrsync.execute(function(error, stdout, stderr) {\n  // we're done\n});\n```\n\n# Development\n\nIf there is something missing (which there probably is) just fork, patch and send a pull request.\n\nFor adding a new shorthand method there are a few simple steps to take:\n- Fork\n- Add the option through the `exposeShortOption`, `exposeLongOption` or `exposeMultiOption` functions. For examples see the source file.\n- Update this README file to list the new shorthand method\n- Make a pull request\n\nWhen adding a shorthand make sure it does not already exist, it is a sane name and a shorthand is necessary.\n\nIf there is something broken (which there probably is), the same applies: fork, patch, pull request. Opening an issue is also possible.\n\n# Changelog\n\nv0.6.1\n\n  - Add support for windows file paths under cygwin (#53)\n\nv0.6.0\n\n  - Escape dollar signs in filenames (#40)\n  - Add permission shorthands (#46)\n  - Added env() option to set the process environment variables (#51)\n\nv0.5.0\n\n  - Properly treat flags as String\n  - Differentiate between shell and file arguments (escaping)\n  - Added a bunch of unit tests\n  - Added TravisCI setup to run tests on branches and PRs\n  - Added cwd() option to set the process CWD (#36)\n\nv0.4.0\n\n  - Child process pid is returned from `execute` (#27)\n  - Command execution shell is configurable for Unix systems (#27)\n  - Better escaping for filenames with spaces (#24)\n\nv0.3.0\n\n  - Launch the command under a shell (#15)\n  - Typo fix isaArray -\u003e isArray for issue (#14)\n  - Error: rsync exited with code 14 (#11)\n\nv0.2.0\n\n  - use spawn instead of exec (#6)\n\nv0.1.0\n\n  - better support for include/exclude filters\n  - better support for output handlers\n  - removed output buffering (#6)\n\nv0.0.2\n\n  - swapped exclude and include order\n  - better shell escaping\n\nv0.0.1\n\n  - initial version (actually the second)\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattijs%2Fnode-rsync","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmattijs%2Fnode-rsync","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattijs%2Fnode-rsync/lists"}