@zamiell/sync-directory

Description

sync-directory can sync files from src directory to target directory.

CLI and API are supported.

We have two ways to sync files: hardlink and copy.

If type is copy, sync-directory will copy files from src directory to target directory.

If type is hardlink, sync-directory can create hardlink files in target directory from src directory.

sync-directory uses copy by default for safety. (hardlink will be quicker but some watchers can't trigger change event for target files.)

Cli

npm i sync-directory -g

syncdir <from> <to> [options]

Example: syncdir aaa bbb -w

options:

-w, --watch

Watch changes. false as default.

Same as config watch.
--quiet

Disable unnecessary logs.
--exclude <strings...>

Exclude some path. Such as syncdir a b --exclude node_modules package-lock.json.

Same as config exclude
-si, --skipInitialSync

Skip the first time sync actions when it's true. It's useful when you just want the srcFolder to be watched. false as default.

Same as config skipInitialSync.
-nd, --nodeep

Just walk the first level sub files/folders. Avoids deep scanning of big folders.

Same as config nodeep.
-do, --deleteOrphaned

Delete orphaned or excluded (when using API) files/folders in target folder. false as default.

Same as config deleteOrphaned.
-hardlink, --hardlink

Sync with type hardlink, copy as default.

Same as config type: 'hardlink'.
-symlink, --symlink

support symlink while sync running. false as default.

Same as config staySymlink.

API (commonjs and esm are supported)

sync

commonjs

const syncDirectory = require('sync-directory');

esm

import syncDirectory from 'sync-directory/index.mjs'

syncDirectory(srcDir, targetDir, {
    afterEachSync({ eventType, nodeType, relativePath, srcPath, targetPath }) {

    },
});

async

commonjs

const { async } = require('sync-directory');

esm

import { async } from 'sync-directory/index.mjs'

(async () => {
    const delay = (time = 2000) => new Promise(r => setTimeout(r, time));

    console.log('start'); // time a

    // wait several 2s: 2 * file number
    await async(srcDir, targetDir, {
        async afterEachSync({ eventType, nodeType, relativePath, srcPath, targetPath }) {
            await delay(2000); // delay 2s after one file/folder was synced
        },
    });

    console.log('end'); // time a + 2 * (file number)
})()

Pick Your API

commonjs

const syncDirectory = require('sync-directory');

esm

import syncDirectory from 'sync-directory/index.mjs';

syncDirectory(srcDir, targetDir[, config]);

Syntax

Function	Returns	Syntax	Block the thread?
`syncDirectory()` `syncDirectory.sync()`	`undefined` or chokidar watcher	Synchronous	Yes
`syncDirectory.async()`	`Promise`	`async / await` `Promise.then()`	No

Returns

const watcher = syncDirectory(A, B);

watcher is undefined.

const watcher = syncDirectory(A, B, {
    watch: true
});

watcher is a chokidar watcher.

Params

Params Overview

name	description	type	values	default	can be `async` ?
`srcDir`	src directory	String	absolute or relative path	-	-
`targetDir`	target directory	String	absolute or relative path	-	-
`config.cwd`	when srcDir or targetDir is a relative path, they will be formatted to absolute path by `path.join(cwd, srcDir	targetDir)`	string	-	`process.cwd()`
`config.watch`	watch file changes	Boolean	-	false	-
`config.chokidarWatchOptions`	watch options (chokidar is used for watching)	Object	-	`{}`	-
`config.type`	way to sync files	String	`'copy' \| 'hardlink'`	`'copy'`	-
`config.skipInitialSync`	skip the first time sync actions when it's `true`. It's useful when you just want the srcFolder to be watched.	Boolean	`true \| false`	`false`	-
`config.deleteOrphaned`	delete orphaned or `excluded` (API using) files/folders in target folder. `false` as default.	Boolean	-	`false`	-
`config.afterEachSync`	callback function when every file synced	Function	-	blank function	Yes when `syncDirectory.async()`
`config.staySymlink`	if src folder "A/" is a symlink, the target folder "A/" will also be the same symlink.	Boolean	-	false	-
`config.stayHardlink`	only worked when `type: 'hardlink'`. When `stayHardlink: true`, if src file is "src/a.js", the target file "target/a.js" will be a hardlink of "src/a.js".	Boolean	-	`true`	-
`config.exclude`	Priority: `forceSync > exclude`. Filter which src files should not be synced.	RegExp / String / Array (item is RegExp / String)	-	null	-
`config.forceSync`	Priority: `forceSync > exclude`. Force sync some files even though they are `excluded`.	RegExp / String / Array (item is RegExp / String)	-	`(file) => { return false }`	No
`config.nodeep`	Just walk the first level sub files/folders.	Boolean	-	`false`	-
`config.onError`	callback function when something wrong	Function	-	`(err) => { throw new Error(err) }`	Yes when `syncDirectory.async()`

Some confusing params

Params Details

cwd

Type: String

Default: process.cwd()

For: format srcDir | targetDir to absolute path when they are relative paths
```
syncDirectory(srcDir, targetDir, {
    cwd: __dirname
});
```

watch

Type: true | false

Default: false

For: watch file changes.

syncDirectory(srcDir, targetDir, {
    watch: true
});

chokidarWatchOptions

Type: Object

Default: {}

For: watch options (chokidar is used for watching).

syncDirectory(srcDir, targetDir, {
    chokidarWatchOptions: {
        awaitWriteFinish: {
            stabilityThreshold: 2000,
            pollInterval: 100
        }
    },
});

afterEachSync

Type: Function

Default: () => {}

For: callback function when every file synced.

syncDirectory.sync(srcDir, targetDir, {
    afterEachSync({ eventType, nodeType, relativePath, srcPath, targetPath }) {

    }
});

await syncDirectory.async(srcDir, targetDir, {
    async afterEachSync({ eventType, nodeType, relativePath, srcPath, targetPath }) {
        
    }
});

eventType: "init:hardlink" / "init:copy" / "add" / "change" / "unlink" / "unlinkDir" / "addDir"
nodeType: "file" / "dir"
relativePath: relative file/folder path
srcPath: absolute or relative src file/folder path
targetPath: absolute or relative target file/folder path

type

Type: 'copy' | 'hardlink'

Default: 'copy'

For: way to sync files.

copy (default)
```
syncDirectory(srcDir, targetDir);
```

hardlink

syncDirectory(srcDir, targetDir, {
    type: 'hardlink'
});

skipInitialSync

Type: true | false

Default: false

For: enhance the performance

It's for enhancing the sync performance when you just want srcDir to be watched.
```
syncDirectory(srcDir, targetDir, {
    skipInitialSync: true,
    watch: true,
})
```
The srcDir won't be synced to targetDir when skipInitialSync: true and the srcDir's file changes will be watched and synced to targetDir.
stayHardlink

Type: true | false

Default: true

Only works when type: 'hardlink'.

When stayHardlink: true, if src file is "src/a.js", the target file "target/a.js" will be a hardlink of "src/a.js".

Then when "src/a.js" changed, "target/a.js" will remain a hardlink. Otherwise will be a copied file.

Some watchers will not be able to watch changes of "target/a.js".
nodeep

Type: true | false

Default: false

Just walk the first level sub files/folders. Avoids deep scanning of big folders.

The reason why deep was not used is that cli options is --nodeep. Just keep this two the same.
```
// srcFolder:
//     a/     a is symlink
//      1.js

// targetFolder:
//     a/
syncDirectory(srcDir, targetDir, {
    nodeep: true, // 1.js will be ignored
});
```

deleteOrphaned

Type: true | false

Default: false

Delete orphaned or excluded (when using API) files/folders in target folder. false as default.

For instance:

srcDir:

dir1/
    1.js
    2.js

targetDir:

dir2/
    1.js
    2.js
    3.js

syncDirectory(srcDir, targetDir, {
    deleteOrphaned: true,
    excluded: [ '2.js' ]
});

// dir2/3.js will be removed because dir1/3.js does not exist.
// dir2/2.js will be removed because dir1/2.js is excluded.

exclude

Type: Function / RegExp / String / Array (item is RegExp / String)

Priority: forceSync > exclude.

Default: null

For: declare files that should not sync to target directory.

Function

syncDirectory(srcDir, targetDir, {
    exclude(filePath) {
        return /node_modules/.test(filePath);
    }
});

String

syncDirectory(srcDir, targetDir, {
    exclude: 'node_modules'
});

RegExp

syncDirectory(srcDir, targetDir, {
    exclude: /node\_modules/
});

Array

syncDirectory(srcDir, targetDir, {
    exclude: [/node\_modules/]
});

syncDirectory(srcDir, targetDir, {
    exclude: ['node_modules']
});

forceSync

Type: Function / RegExp / String / Array (item is RegExp / String)

Priority: forceSync > exclude.

Default: null

For: some files must be synced even though 'excluded'.

Function

syncDirectory(srcDir, targetDir, {
    exclude: ['node_modules'],
    forceSync(filePath) {
        return /node_modules\/jquery/.test(filePath);
    }
});

String

syncDirectory(srcDir, targetDir, {
    exclude: ['node_modules'],
    forceSync: 'node_modules/jquery'
});

RegExp

syncDirectory(srcDir, targetDir, {
    exclude: ['node_modules'],
    forceSync: /node_modules\/jquery/
});

Array

syncDirectory(srcDir, targetDir, {
    exclude: ['node_modules'],
    forceSync: [/node_modules\/jquery/]
});

syncDirectory(srcDir, targetDir, {
    exclude: ['node_modules'],
    forceSync: ['node_modules/jquery']
});

staySymlink

Type: true | false

Default: false

If src folder "A/" is a symlink, the target folder "A/" will also be the same symlink.

// srcFolder:
//     a/     a is symlink
//      1.js

// targetFolder:
//     a/     a is not symlink
//      1.js
syncDirectory(srcDir, targetDir, {
    staySymlink: false,
});

// srcFolder:
//     a/     a is symlink
//      1.js

// targetFolder:
//     a/     a is the same symlink
//      1.js
syncDirectory(srcDir, targetDir, {
    staySymlink: true,
});

onError

Type: Function

Default: (err) => { throw new Error(err) }

For: callback function when something wrong.

syncDirectory(srcDir, targetDir, {
    onError(err) {
        console.log(err.message);
    },
});

LICENSE

MIT

@zamiell/sync-directory

Description

Cli

API (commonjs and esm are supported)

sync

async

Pick Your API

Syntax

Returns

Params

Params Overview

Some confusing params

Params Details

LICENSE

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

Weekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

@zamiell/sync-directory

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads