{"_id":"3h-backup","_rev":"1-49677f90e47e87666fc183cb56452ce1","name":"3h-backup","dist-tags":{"latest":"1.1.0"},"versions":{"1.0.0":{"name":"3h-backup","version":"1.0.0","description":"A personal backup helper.","type":"module","main":"./src/index.js","bin":{"3h-backup":"src/cli.js"},"types":"./types/src/index.d.ts","scripts":{"help":"node ./src/cli.js --help","test:auto":"cd ./test/scripts && node --test","test:manual":"node ./test/scripts/manualTest.js","build":"tsc -p tsconfig.src.json","typecheck:src":"tsc -p tsconfig.src.json","typecheck:test":"tsc -p tsconfig.json","typecheck":"tsc -b tsconfig.json"},"repository":{"type":"git","url":"git+https://github.com/huang2002/3h-backup.git"},"keywords":["backup","sync","3h"],"author":{"name":"3h"},"license":"ISC","bugs":{"url":"https://github.com/huang2002/3h-backup/issues"},"homepage":"https://github.com/huang2002/3h-backup#readme","devDependencies":{"@types/node":"^20.10.4","typescript":"^5.3.3"},"dependencies":{"3h-cli":"^4.0.0","3h-validate":"^0.7.0","fast-glob":"^3.3.2","pave-path":"^0.2.0"},"engines":{"node":">=15"},"gitHead":"cad2a2f1c9daa3599a5c5b32bd875902533f5635","_id":"3h-backup@1.0.0","_nodeVersion":"20.10.0","_npmVersion":"8.3.0","dist":{"integrity":"sha512-3Zj2ejpJPDWWzh8ksfaEhugSQrJLx/spiKMkwD9vFfHWKWm6tthmXuTQngAawIuG3cZw9KvRSg7OewSHchv8hA==","shasum":"7c8ba92d16c04cb81bbf391bc09353433e311b9c","tarball":"https://registry.npmjs.org/3h-backup/-/3h-backup-1.0.0.tgz","fileCount":27,"unpackedSize":36027,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQC0KrKBBi4EwlkpYeA/gygxG8fZeOOLjCrs09XrxhCR2AIgQNpXl/0Fcms5h/GEHEdRQQ93X+ENFKOq1kdb/6w0WaA="}]},"_npmUser":{"name":"3h","email":"1340545944@qq.com"},"directories":{},"maintainers":[{"name":"3h","email":"1340545944@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/3h-backup_1.0.0_1702725516444_0.3555174104103671"},"_hasShrinkwrap":false},"1.1.0":{"name":"3h-backup","version":"1.1.0","description":"A personal backup helper.","type":"module","main":"./src/index.js","bin":{"3h-backup":"src/cli.js"},"types":"./types/src/index.d.ts","scripts":{"help":"node ./src/cli.js --help","test:auto":"cd ./test/scripts && node --test","test:manual":"node ./test/scripts/manualTest.js","build":"tsc -p tsconfig.src.json","typecheck:src":"tsc -p tsconfig.src.json","typecheck:test":"tsc -p tsconfig.json","typecheck":"tsc -b tsconfig.json"},"repository":{"type":"git","url":"git+https://github.com/huang2002/3h-backup.git"},"keywords":["backup","sync","3h"],"author":{"name":"3h"},"license":"ISC","bugs":{"url":"https://github.com/huang2002/3h-backup/issues"},"homepage":"https://github.com/huang2002/3h-backup#readme","devDependencies":{"@types/node":"^20.10.4","typescript":"^5.3.3"},"dependencies":{"3h-cli":"^4.0.0","3h-validate":"^0.7.0","fast-glob":"^3.3.2","pave-path":"^0.2.0"},"engines":{"node":">=15"},"gitHead":"9469439af0d5b4a5f4e0a855329cf8731af54063","_id":"3h-backup@1.1.0","_nodeVersion":"20.10.0","_npmVersion":"8.3.0","dist":{"integrity":"sha512-Z1gOAWOCVzgrGodvWVjJGg2NPZ67PJEs88ykSv6ogYsBIEkFSlZ7wt/dX3JWamrr95LD25ZZ/uBnQbJia8QuHA==","shasum":"37e37e49e375a2a58e2c6c4db99401b512df5e01","tarball":"https://registry.npmjs.org/3h-backup/-/3h-backup-1.1.0.tgz","fileCount":27,"unpackedSize":36092,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQCHRQde6UMT/ZmopDd5lqdnuA0kVL51GloWw6ro3tYU0gIgWoLyU41Uv88FXiaAdv4sOw23CJTa6ip/aY11fNDD1GQ="}]},"_npmUser":{"name":"3h","email":"1340545944@qq.com"},"directories":{},"maintainers":[{"name":"3h","email":"1340545944@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/3h-backup_1.1.0_1702997460918_0.7235374510800574"},"_hasShrinkwrap":false}},"time":{"created":"2023-12-16T11:18:36.443Z","1.0.0":"2023-12-16T11:18:36.703Z","modified":"2023-12-19T14:51:01.261Z","1.1.0":"2023-12-19T14:51:01.081Z"},"maintainers":[{"name":"3h","email":"1340545944@qq.com"}],"description":"A personal backup helper.","homepage":"https://github.com/huang2002/3h-backup#readme","keywords":["backup","sync","3h"],"repository":{"type":"git","url":"git+https://github.com/huang2002/3h-backup.git"},"author":{"name":"3h"},"bugs":{"url":"https://github.com/huang2002/3h-backup/issues"},"license":"ISC","readme":"# 3h-backup\r\n\r\n> A personal backup helper.\r\n\r\n## Table of Contents\r\n\r\n- [Introduction](#introduction)\r\n- [Usage](#usage)\r\n- [List Files](#list-files)\r\n    - [List File Processing](#list-file-processing)\r\n    - [Glob Patterns](#glob-patterns)\r\n- [Configuration](#configuration)\r\n    - [Config File](#config-file)\r\n    - [Filter](#filter)\r\n    - [Replace](#replace)\r\n- [License](#license)\r\n\r\n## Introduction\r\n\r\n`3h-backup` is a personal backup helper that simply maintains a copy\r\nof the files you specified. Its backup mechanism basically makes\r\nfile structure under destination path the same as source path.\r\nThe designed purpose of `3h-backup` is to backup important files\r\nin somewhere like a USB drive.\r\n\r\n## Usage\r\n\r\n1. It is recommended to install `3h-backup` as a global package\r\n    to have better version control and avoid potential breakage:\r\n\r\n    ```bash\r\n    npm install -g 3h-backup\r\n    ```\r\n\r\n2. Create a configuration file:\r\n\r\n    ```json\r\n    {\r\n        \"tasks\": [\r\n            {\r\n                \"source\": \"/path/to/data-root\",\r\n                \"destination\": \"/path/to/backup-root\",\r\n                \"filter\": \"source\"\r\n            }\r\n        ]\r\n    }\r\n    ```\r\n\r\n3. Create a list file in your data folder to specify the files you want to include or exclude:\r\n\r\n    ```txt\r\n    patterns-to-include\r\n    !patterns-to-exclude\r\n    ```\r\n\r\n4. Execute `3h-backup` and specifies your config file:\r\n\r\n    ```bash\r\n    3h-backup -c /path/to/config\r\n    ```\r\n\r\nNow, the program should be processing your backup tasks and you can\r\nfollow the instructions in your terminal to complete your backup.\r\n\r\nFor more help on the CLI program:\r\n\r\n```bash\r\n$ 3h-backup --help\r\nA personal backup helper.\r\n\r\nUsage:\r\n  3h-backup [options]\r\n\r\nOptions:\r\n  --help, -h                      Show help info.\r\n  --config, -c <path>             The Path to the config file.\r\n                                  Default: 3h-backup.json\r\n  --tasks, -t <identities...>     Tasks to execute.\r\n                                  Default: execute all tasks\r\n  --encoding, -e <enc>            The encoding of the config file and list files.\r\n                                  Default: utf-8\r\n  --json, -j                      Print tasks in json format.\r\n                                  Default format: simple\r\n```\r\n\r\n## List Files\r\n\r\nList files are text files that placed in directories to scan and contains\r\nthe file patterns that you want to include or exclude.\r\n\r\n### List File Processing\r\n\r\nProcessing of a single list file follows these steps and rules:\r\n\r\n1. Lines are splitted by `\\n`;\r\n2. Each line is trimmed to remove beginning and trailing whitespace characters;\r\n3. Empty lines and lines starting with `#` are ignored;\r\n4. Lines starting with `!` are regarded as negative patterns that exclude matched files;\r\n5. Other lines are regarded as positive patterns that include matched files.\r\n\r\nEach list file takes effect in its own directory. `3h-backup` will scan for\r\nlist files recursively in each included directory to decide\r\nthe file list of a task. If a directory is included by a list file\r\nin parent directory or by a task config directly, but there are no list files\r\nin it, then all the entries(files & sub-directories) will be included.\r\nAn empty list file makes all the entries in containing directory ignored.\r\n\r\n### Glob Patterns\r\n\r\nThe file patterns in list files are processed by `fast-glob`\r\nwith `{ onlyFiles: false, deep: 1 }`. That means,\r\n\r\n1. Both files and directories can be matched by patterns in list files;\r\n2. Patterns in list files take effect only in current path level.\r\n\r\n## Configuration\r\n\r\n### Config File\r\n\r\nHere, configuration items are described using the following TypeScript code,\r\nwhere `BackupConfig` is the type of the whole JSON config file:\r\n\r\n```ts\r\n/**\r\n * File list filter. (See the subsections below for more info.)\r\n */\r\ntype BackupFilter = (\r\n    | 'intersection'\r\n    | 'source'\r\n    | 'destination'\r\n    | 'union'\r\n);\r\n\r\n/**\r\n * Replace strategy. (See the subsections below for more info.)\r\n */\r\ntype BackupReplace = (\r\n    | 'mtime'\r\n    | 'ctime'\r\n    | 'all'\r\n);\r\n\r\n/**\r\n * Configuration per task. Note that `source`/`destination`\r\n * can be either an absolute path or a relative path based on\r\n * the path of the config file.\r\n */\r\ninterface BackupTaskConfig {\r\n    name?: string;\r\n    /**\r\n     * Base path of source files which are going to be backed up.\r\n     */\r\n    source: string;\r\n    /**\r\n     * Path of destination where file copies should be placed.\r\n     */\r\n    destination: string;\r\n    filter?: BackupFilter;\r\n    replace?: BackupReplace;\r\n    /**\r\n     * If this is set to `true`,\r\n     * any empty directory will be removed\r\n     * when the last file in it is deleted.\r\n     */\r\n    removeEmptyDirectory?: boolean;\r\n}\r\n\r\ninterface BackupConfig {\r\n    tasks: readonly BackupTaskConfig[];\r\n    /**\r\n     * Encoding of list files.\r\n     * @default 'utf-8'\r\n     */\r\n    encoding?: BufferEncoding;\r\n    /**\r\n     * Possible name of list files that\r\n     * tell the program which file to back up.\r\n     * @default ['.3h-backup-list']\r\n     */\r\n    listFiles?: readonly string[];\r\n    /**\r\n     * Default `filter` for all tasks.\r\n     * @default source\r\n     */\r\n    filter?: BackupFilter;\r\n    /**\r\n     * Default `replace` for all tasks.\r\n     * @default mtime\r\n     */\r\n    replace?: BackupReplace;\r\n    /**\r\n     * Default `removeEmptyDirectory` for all tasks.\r\n     * @default true\r\n     */\r\n    removeEmptyDirectory?: boolean;\r\n    /**\r\n     * Whether to skip confirming step.\r\n     * @default false\r\n     */\r\n    skipConfirm?: boolean;\r\n}\r\n```\r\n\r\n### Filter\r\n\r\nThe `filter` option controls which files should be considered:\r\n\r\n- `source`(default) -- Include files existing in source path only.\r\n- `destination` -- Include files existing in destination path only.\r\n- `intersection` -- Intersection of `source` files and `destination` files.\r\n- `union` -- Union of `source` files and `destination` files.\r\n\r\nAlso, it affects creating new files and removing extra files:\r\n\r\n- `source`(default) -- Create new files in destination path\r\n    if there are corresponding source files.\r\n- `destination` -- Remove extra files in destination path\r\n    if corresponding source files don't exist.\r\n- `intersection` -- Never create or remove files.\r\n- `union` -- Combination of `source` and `destination`.\r\n\r\n### Replace\r\n\r\nThe `replace` option tells when to replace an existing destination file:\r\n\r\n- `all` -- Replace all destination files.\r\n- `mtime`(default) -- Replace an existing destination file only if its\r\n    last-modified time is earlier than that of corresponding source file.\r\n- `ctime` -- Replace an existing destination file only if its creation\r\n    time is earlier than that of corresponding source file.\r\n\r\n## License\r\n\r\n[ISC License](./LICENSE)\r\n","readmeFilename":"README.md"}