{"id":15413125,"url":"https://github.com/vesparny/borgjs","last_synced_at":"2025-08-02T10:11:38.757Z","repository":{"id":66104138,"uuid":"59767424","full_name":"vesparny/borgjs","owner":"vesparny","description":"📦 A tiny wrapper for BorgBackup to automate your backup workflow","archived":false,"fork":false,"pushed_at":"2018-01-19T10:44:54.000Z","size":123,"stargazers_count":30,"open_issues_count":0,"forks_count":2,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-07-05T16:58:24.625Z","etag":null,"topics":["attic","backup","borg","borgbackup","nodejs"],"latest_commit_sha":null,"homepage":"","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/vesparny.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-05-26T16:48:14.000Z","updated_at":"2024-10-08T12:37:44.000Z","dependencies_parsed_at":"2023-02-23T23:15:20.994Z","dependency_job_id":null,"html_url":"https://github.com/vesparny/borgjs","commit_stats":{"total_commits":61,"total_committers":1,"mean_commits":61.0,"dds":0.0,"last_synced_commit":"36e91bb6519eb9cd159f64c83b869e173995fc2a"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/vesparny/borgjs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vesparny%2Fborgjs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vesparny%2Fborgjs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vesparny%2Fborgjs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vesparny%2Fborgjs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vesparny","download_url":"https://codeload.github.com/vesparny/borgjs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vesparny%2Fborgjs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268370180,"owners_count":24239766,"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":["attic","backup","borg","borgbackup","nodejs"],"created_at":"2024-10-01T16:55:33.185Z","updated_at":"2025-08-02T10:11:38.712Z","avatar_url":"https://github.com/vesparny.png","language":"JavaScript","readme":"# 📦 borgjs\n\n\u003e A tiny wrapper for BorgBackup to automate your backup workflow\n\n[![Gitter](https://img.shields.io/gitter/room/nwjs/nw.js.svg)](https://gitter.im/borgjs/discussion)\n[![npm](https://img.shields.io/npm/v/borgjs.svg)](https://www.npmjs.com/package/borgjs)\n[![Travis](https://img.shields.io/travis/vesparny/borgjs.svg)](https://travis-ci.org/vesparny/borgjs)\n\n\n[![npm](https://img.shields.io/npm/dm/borgjs.svg)](https://npm-stat.com/charts.html?package=borgjs\u0026from=2016-10-17)\n[![David](https://img.shields.io/david/vesparny/borgjs.svg)](https://david-dm.org/vesparny/borgjs)\n[![JavaScript Style Guide](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](http://standardjs.com/)\n\n## Overview\n\n**Please note borgjs needs you to run node \u003e=6 and has been tested using borg**\n\n* v1.0.7\n* v1.0.8\n* v1.0.9\n* v1.0.10\n* v1.1.4\n\nborgjs is a nodejs command line tool for [BorgBackup](http://borgbackup.readthedocs.io/en/stable/).\n\nAfter having tried a lot of backup solutions for my data, I've been using Borg for quite a while.\nIt's rock solid and never let me down.\nIt supports compression, de-duplication and encryption.\n\nBackups should be as boring as possible, that's why I've created this tool in order to automate and constantly monitor the whole process, making it a little bit more user friendly.\n\nInstead of writing complex bash scripts you can now just write a [declarative configuration file](#configuration), run borgjs in a crontab and forget about it.\n\nIt will take care of your backup workflow, sending you status reports through different possible channels.\n\n## Features\n\n* backup creation\n* prune old backup according to a set of rules declared in the [configuration file](#configuration).\n* check backups for consistency and integrity.\n* `onFinish` hook to do anything you want after finishing a backup.\n* lockfile system to prevent concurrent backup process running in the same destination.\n* output borg messages to stdout for easy logging.\n* highly [configurable](#configuration).\n* allow to fully customize borg commands and environment variables.\n\n## Usage CLI\n\nIn order to use borgjs, you need to configure borg before.\nThis is an easy step, just follow the [installation](http://borgbackup.readthedocs.io/en/stable/installation.html) guide on the borg website.\n\nInitialize an empty borg repository (for more details see the borg [quickstart](http://borgbackup.readthedocs.io/en/stable/quickstart.html) guide)\n\n```\n$ borg init /path/to/repo\n```\nInstall borgjs globally\n\n```\n$ npm i -g borgjs\n```\n\nRunning a backup is as easy as creating a [borg repository](http://borgbackup.readthedocs.io/en/stable/usage.html#borg-init) and run\n\n```shell\n$ borgjs -c /User/me/borgjs.config.js\n```\nor\n```\n$ borgjs $(date +%Y-%m-%d-%H%M%S) -c /User/me/borgjs.config.js \u003e\u003e /Users/me/logs/$(date +%Y-%m-%d-%H%M%S).log\n```\nin case you want to specify the archive name and log to a file (useful if you run in as a cronjob).\n\n```\n$ borgjs --help\n\n  A tiny wrapper for BorgBackup to automate your backup workflow\n\n  Usage\n  $ borgjs \u003carchive\u003e\u003coptions\u003e\n\nOptions\n  -c, --config         config file path\n\nExamples\n  # run borgjs\n  $ borgjs -c=/User/me/borgjs.config.js\n\n  #run borgjs specifying the archive name, and log output to a file\n  $ borgjs $(date +%Y-%m-%d-%H%M%S) -c /path/to/your/borgjs.config.js \u003e\u003e $(date +%Y-%m-%d-%H%M%S).log\n```\n\n## Usage API\n\nYou can also use borgjs programmatically:\n\n```js\nconst borgjs = require('borgjs')\nconst config = {\n  repository: '/Users/arny/Desktop/test/',\n  paths: [\n    '/Volumes/External/'\n  ]\n}\nconst archiveName = new Date().toString()\n\nborgjs(config, archiveName)\n.then(() =\u003e console.log('success'))\n.catch((err) =\u003e console.log('error', err))\n```\n\n## `onFinish` hook\n\nBy defining an `onFinish` callback function in the configuration file, it's possible to run any arbitrary code when a backup finishes.\n\n```js\n// the config file\nmodule.exports = {\n  onFinish: function (err, data, done) {\n    if (err) {\n      console.log('An error happened', err)\n    } else {\n      console.log(`Archive ${data.archiveName} created.`)\n    }\n    // invoke the done callback to let the process terminate properly\n    done()\n  }\n}\n```\n\nIt's possible to use the `onFinish` callback to send emails or notifications about the executed backup (see the paragraph below for an example)\n\n## Configuration\n\n```js\nmodule.exports = {\n  // Specify an alternative absolute path for the borg executable\n  // defaults to the one in $PATH\n  // borgPath: '',\n\n  // Borg repository path\n  // can be remote or local\n  // see http://borgbackup.readthedocs.io/en/stable/usage.html#borg-init\n  // e.g. '/Users/me/Desktop/borg_backup' or 'user@myserver.cc:borg_backup'\n  repository: '', // MANDATORY\n\n  // An array of absolute paths to include in the backup\n  // paths that do not exist will be excluded (useful when a network share is not mounted)\n  paths: [ // MANDATORY\n    //  '/Users/me',\n    //  '/etc\n  ],\n\n  // An array of files/directories to exclude from backup\n  // exclude: [\n  //  '*/node_modules',\n  //  '*.DS_Store'\n  // ],\n\n  // A prefix for backup archives\n  // archivePrefix: 'backup-',\n\n  // Create backup archive\n  // Use the options array to pass any options supported by borg create\n  // See https://borgbackup.readthedocs.org/en/stable/usage.html#borg-create\n  create: {\n    options: [\n     '--compression', 'lz4',\n     '--filter', 'AME?'\n    ]\n  },\n  // Check repo consistency\n  // Use the options array to pass any options supported by borg check\n  // See https://borgbackup.readthedocs.org/en/stable/usage.html#borg-check\n  // check: {\n  //  options: []\n  // },\n\n  // Retention policy for pruning old backups\n  // Use the options array to pass any options supported by borg prune\n  // https://borgbackup.readthedocs.org/en/stable/usage.html#borg-prune for details.\n //  prune: {\n //   options: [\n //    '-d', 30,\n //    '-w', 30,\n //    '--keep-within', '31d'\n //   ]\n // }\n\n  // Set the following environment variables\n  // See https://borgbackup.readthedocs.io/en/stable/usage.html#environment-variables\n  env: {\n    BORG_REMOTE_PATH: 'borg1',\n    BORG_PASSPHRASE: 'passphrase'\n  },\n  // the onFinish callback\n  onFinish: function (err, data, done) {\n    const message = err\n      ? 'the backup failed'\n      : `the archive ${data.archiveName} has been created`\n    var execSync = require('child_process').execSync\n\n    const command = `\n        curl -s --user 'api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0' \\\n        https://api.mailgun.net/v3/samples.mailgun.org/messages \\\n        -F from='Excited User \u003cexcited@samples.mailgun.org\u003e' \\\n        -F to='devs@mailgun.net' \\\n        -F subject='Hello from borgjs' \\\n        -F text='${message}'\n        `\n    try {\n      execSync(command)\n    } catch (e) {}\n    // invoke the done callback to let the process terminate properly\n    done()\n  }\n}\n```\n\n## Automate\n\nA backup is not a backup if it's not automated.\n\nI personally use [cronnix](https://www.macupdate.com/app/mac/7486/cronnix) to schedule my backup sessions on my mac.\n\n\u003cimg src=\"https://cloud.githubusercontent.com/assets/82070/19662868/be07d350-9a39-11e6-88a8-697627d30453.png\"\u003e\n\n## Recipes\n\n* Borg can store data on any remote host accessible over SSH. If you prefer to store your offsite backup in some other fancy cloud storage, you can always backup to a local target, then upload it anywhere using [rclone](http://rclone.org/)\n\n* I personally use [rsync.net](http://rsync.net/) for my backup, they also apply [dirt cheap](http://www.rsync.net/products/attic.html) pricing model to borg users.\nPlease note I'm not affiliated with them, I'm just an happy paying customer.\n\n## Change Log\n\nThis project adheres to [Semantic Versioning](http://semver.org/).  \nEvery release, along with the migration instructions, is documented in the [CHANGELOG.md](https://github.com/vesparny/borgjs/blob/master/CHANGELOG.md) file.\n\n## License\n\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvesparny%2Fborgjs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvesparny%2Fborgjs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvesparny%2Fborgjs/lists"}