backdot 1.0.0 → 1.1.0

package/README.md

@@ -1,89 +1,46 @@
 # backdot
 
-Lightweight CLI to back up dotfiles and gitignored files to a private Git repo, with optional daily scheduling via macOS launchd.
+Back up dotfiles and gitignored files to a private Git repo — on demand or on a daily schedule.
 
-## How it works
-
-1. Reads `~/.backdot.json` for the target repository and file entries
-2. Resolves file entries — either gitignored files in a directory or glob patterns
-3. Copies resolved files to `~/.backdot/repo/`, preserving directory structure relative to `~`
-4. Commits and pushes changes to the configured remote
-
-## Installation
+## Getting started
 
 ```bash
 npm install -g backdot
 ```
 
-Requires Node.js and `git` available on your PATH.
-
-## Configuration
-
-Create `~/.backdot.json`:
+Create `~/.backdot.json` pointing to a private repo and the files you want backed up:
 
 ```json
 {
   "repository": "git@github.com:USERNAME/dotfiles-backup.git",
+  "machine": "my-work-laptop",
   "files.gitignored": ["~/my-project"],
-  "files.match": ["~/.zshrc", "~/.config/ghostty/**"]
+  "files.match": ["~/.zshrc", "~/.oh-my-zsh/custom/*.zsh", "~/.ssh/config/config", "~/.npmrc"]
 }
 ```
 
-### File entry types
-
-| Key                | Description                                                                                                                       |
-| ------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
-| `files.gitignored` | Array of directories. Backs up all gitignored files in each directory (runs `git ls-files --others --ignored --exclude-standard`) |
-| `files.match`      | Array of glob patterns. Backs up all matching files (powered by [fast-glob](https://github.com/mrmlnc/fast-glob))                 |
-
-Both keys are optional, but at least one must be present and non-empty. Paths support `~` expansion.
-
-## Usage
-
-### Run a backup
+Run your first backup:
 
 ```bash
 backdot --backup
 ```
 
-### Restore from backup
-
-```bash
-backdot --restore
-```
-
-Pulls the latest state from the remote backup repo and copies files back to their original locations. If any files already exist, you'll be prompted to select which ones to overwrite.
-
-### Schedule daily backups (macOS)
-
-```bash
-backdot --schedule
-```
-
-Installs a launchd job (`com.backdot.daemon`) that runs the backup daily at 02:00.
-
-### Remove the schedule
-
-```bash
-backdot --unschedule
-```
-
-### Check status
-
-```bash
-backdot --status
-```
+## Configuration
 
-Shows whether the daily schedule is active and lists all files that would be backed up. Useful for verifying your `~/.backdot.json` is correct.
+| Key                | Description                                            |
+| ------------------ | ------------------------------------------------------ |
+| `files.gitignored` | Directories to scan for gitignored files               |
+| `files.match`      | Glob patterns matching individual files or directories |
 
-## File locations
+## Commands
 
-| Path                                              | Purpose                                |
-| ------------------------------------------------- | -------------------------------------- |
-| `~/.backdot.json`                                 | Configuration file                     |
-| `~/.backdot/repo/`                                | Local staging directory (the git repo) |
-| `~/.backdot/backup.log`                           | Backup log                             |
-| `~/Library/LaunchAgents/com.backdot.daemon.plist` | launchd job (when using `--schedule`)  |
+| Command        | Description                                            |
+| -------------- | ------------------------------------------------------ |
+| `--backup`     | Run a backup now                                       |
+| `--restore`    | Restore files to their original locations              |
+| `--schedule`   | Schedule automatic daily backup via launchd (Mac-only) |
+| `--unschedule` | Remove the daily schedule                              |
+| `--status`     | Show schedule and resolved file list                   |
 
 ## Development
 

package/dist/cli.js

@@ -1,29 +1,53 @@
 #!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
 import ora from "ora";
-import { loadConfig } from "./config.js";
+import { loadConfig, CONFIG_PATH } from "./config.js";
 import { resolveFiles } from "./resolve.js";
-import { copyToStaging } from "./staging.js";
-import { gitSync } from "./git.js";
+import { cleanStaging, copyToStaging, writeRepoReadme } from "./staging.js";
+import { gitPull, gitCommitAndPush } from "./git.js";
 import { restore } from "./restore.js";
 import { setupLaunchd, uninstallLaunchd, isScheduled } from "./plist.js";
 import { logger } from "./log.js";
+function getVersion() {
+    const pkgPath = path.resolve(path.dirname(new URL(import.meta.url).pathname), "../package.json");
+    try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+        return pkg.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
 async function backup() {
     logger.info("Starting backup");
     const config = loadConfig();
     logger.info(`Repository: ${config.repository}`);
+    logger.info(`Machine: ${config.machine}`);
     const spinner = ora("Resolving files").start();
-    const files = resolveFiles(config.files);
-    logger.info(`Resolved ${files.length} file(s)`);
-    if (files.length === 0) {
-        spinner.info("No files resolved, nothing to back up");
-        return;
+    try {
+        const userFiles = resolveFiles(config.files);
+        logger.info(`Resolved ${userFiles.length} file(s)`);
+        if (userFiles.length === 0) {
+            spinner.info("No files resolved, nothing to back up");
+            return;
+        }
+        const files = [...userFiles, CONFIG_PATH];
+        spinner.text = "Syncing with remote";
+        await gitPull(config.repository);
+        spinner.text = `Copying ${files.length} file(s) to staging`;
+        cleanStaging(config.machine);
+        copyToStaging(files, config.machine);
+        writeRepoReadme();
+        spinner.text = "Pushing to remote";
+        await gitCommitAndPush();
+        spinner.succeed("Backup complete");
+        console.log();
+    }
+    catch (err) {
+        spinner.fail("Backup failed");
+        throw err;
     }
-    spinner.text = `Copying ${files.length} file(s) to staging`;
-    copyToStaging(files);
-    spinner.text = "Pushing to remote";
-    await gitSync(config.repository);
-    spinner.succeed("Backup complete");
-    console.log();
     logger.info("Backup complete");
 }
 function status() {
@@ -33,14 +57,17 @@ function status() {
     try {
         const config = loadConfig();
         console.log(`  Repo:      ${config.repository}`);
+        console.log(`  Machine:   ${config.machine}`);
         console.log();
         const spinner = ora("Resolving files").start();
-        const files = resolveFiles(config.files);
-        if (files.length === 0) {
+        const userFiles = resolveFiles(config.files);
+        if (userFiles.length === 0) {
             spinner.warn("No files resolved. Check your ~/.backdot.json entries.");
         }
         else {
-            spinner.succeed(`${files.length} file(s) resolved`);
+            const files = [...userFiles, CONFIG_PATH];
+            spinner.stop();
+            console.log(`${files.length} file(s) resolved:`);
             console.log();
             for (const file of files) {
                 console.log(`  ${file}`);
@@ -54,6 +81,11 @@ function status() {
     }
     console.log();
 }
+function requireMacOS() {
+    if (process.platform !== "darwin") {
+        throw new Error("Scheduling is only supported on macOS (launchd). Use cron or systemd on Linux.");
+    }
+}
 async function main() {
     const args = process.argv.slice(2);
     const command = args[0];
@@ -62,9 +94,11 @@ async function main() {
             await backup();
         }
         else if (command === "--schedule") {
+            requireMacOS();
             setupLaunchd();
         }
         else if (command === "--unschedule") {
+            requireMacOS();
             uninstallLaunchd();
         }
         else if (command === "--status") {
@@ -73,6 +107,9 @@ async function main() {
         else if (command === "--restore") {
             await restore();
         }
+        else if (command === "--version") {
+            console.log(getVersion());
+        }
         else {
             console.log();
             console.log("  Usage: backdot <command>");
@@ -84,6 +121,7 @@ async function main() {
             console.log("    --schedule     Install daily backup schedule (macOS launchd)");
             console.log("    --unschedule   Remove the daily backup schedule");
             console.log("    --status       Show schedule and resolved files");
+            console.log("    --version      Show version");
             console.log();
             if (command && command !== "--help") {
                 console.error(`  Unknown command: ${command}`);

package/dist/config.d.ts

@@ -1,17 +1,21 @@
 import { z } from "zod";
+export declare const CONFIG_PATH: string;
 export declare function expandTilde(p: string): string;
 declare const ConfigSchema: z.ZodPipe<z.ZodObject<{
     repository: z.ZodString;
+    machine: z.ZodString;
     "files.gitignored": z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>>;
     "files.match": z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>>;
 }, z.core.$strip>, z.ZodTransform<{
     repository: string;
+    machine: string;
     files: {
         gitignored: string[];
         match: string[];
     };
 }, {
     repository: string;
+    machine: string;
     "files.gitignored": string[];
     "files.match": string[];
 }>>;

package/dist/config.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { z } from "zod";
-const CONFIG_PATH = path.join(os.homedir(), ".backdot.json");
+export const CONFIG_PATH = path.join(os.homedir(), ".backdot.json");
 export function expandTilde(p) {
     if (p.startsWith("~/") || p === "~") {
         return path.join(os.homedir(), p.slice(1));
@@ -13,6 +13,7 @@ const pathList = z.array(z.string().min(1).transform(expandTilde)).optional().de
 const ConfigSchema = z
     .object({
     repository: z.string().min(1),
+    machine: z.string().min(1),
     "files.gitignored": pathList,
     "files.match": pathList,
 })
@@ -21,6 +22,7 @@ const ConfigSchema = z
 })
     .transform((c) => ({
     repository: c.repository,
+    machine: c.machine,
     files: {
         gitignored: c["files.gitignored"],
         match: c["files.match"],
@@ -44,5 +46,13 @@ export function loadConfig() {
     catch {
         throw new Error(`Invalid JSON in config file: ${CONFIG_PATH}`);
     }
-    return ConfigSchema.parse(parsed);
+    const result = ConfigSchema.safeParse(parsed);
+    if (!result.success) {
+        const messages = result.error.issues.map((i) => {
+            const path = i.path.length > 0 ? `"${i.path.join(".")}"` : "config";
+            return `  - ${path}: ${i.message}`;
+        });
+        throw new Error(`Invalid config in ${CONFIG_PATH}:\n${messages.join("\n")}`);
+    }
+    return result.data;
 }

package/dist/git.d.ts

@@ -1,2 +1,2 @@
 export declare function gitPull(repository: string): Promise<void>;
-export declare function gitSync(repository: string): Promise<void>;
+export declare function gitCommitAndPush(): Promise<void>;

package/dist/git.js

@@ -12,20 +12,20 @@ export async function gitPull(repository) {
         await git.clean(CleanOptions.FORCE, ["-d"]);
     }
     else {
-        await simpleGit().clone(repository, STAGING_DIR);
+        try {
+            await simpleGit().clone(repository, STAGING_DIR);
+        }
+        catch {
+            fs.mkdirSync(STAGING_DIR, { recursive: true });
+            const git = simpleGit(STAGING_DIR);
+            await git.init();
+            await git.addRemote("origin", repository);
+        }
     }
     logger.info("Synced staging directory from remote");
 }
-export async function gitSync(repository) {
-    if (!fs.existsSync(STAGING_DIR)) {
-        fs.mkdirSync(STAGING_DIR, { recursive: true });
-    }
+export async function gitCommitAndPush() {
     const git = simpleGit(STAGING_DIR);
-    if (!fs.existsSync(path.join(STAGING_DIR, ".git"))) {
-        logger.info("Initializing new git repository in staging directory");
-        await git.init();
-        await git.addRemote("origin", repository);
-    }
     await git.add(".");
     const status = await git.status();
     if (status.isClean()) {
@@ -35,14 +35,6 @@ export async function gitSync(repository) {
     const date = new Date().toISOString().split("T")[0];
     const message = `Automated backup: ${date}`;
     await git.commit(message);
-    logger.info(`Committed: ${message}`);
-    try {
-        await git.push(["-u", "origin", "HEAD"]);
-        logger.info("Pushed to remote");
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        logger.error(`Push failed: ${msg}`);
-        throw new Error(`Push failed: ${msg}`);
-    }
+    await git.push(["-u", "origin", "HEAD"]);
+    logger.info(`Committed and pushed: ${message}`);
 }

package/dist/resolve.js

@@ -32,6 +32,7 @@ function resolveGlob(pattern) {
         return [];
     }
 }
+const LARGE_FILE_THRESHOLD = 10 * 1024 * 1024; // 10 MB
 /**
  * Resolve all file entries to absolute paths.
  * Skips entries that fail resolution and logs warnings.
@@ -44,7 +45,8 @@ export function resolveFiles(files) {
     for (const pattern of files.match) {
         allFiles.push(...resolveGlob(pattern));
     }
-    return allFiles.filter((filePath) => {
+    const unique = [...new Set(allFiles)];
+    return unique.filter((filePath) => {
         try {
             fs.accessSync(filePath, fs.constants.R_OK);
             const stat = fs.statSync(filePath);
@@ -52,6 +54,11 @@ export function resolveFiles(files) {
                 logger.warn(`Not a regular file, skipping: ${filePath}`);
                 return false;
             }
+            if (stat.size > LARGE_FILE_THRESHOLD) {
+                const sizeMB = (stat.size / 1024 / 1024).toFixed(1);
+                logger.warn(`Large file (${sizeMB} MB), skipping: ${filePath}`);
+                return false;
+            }
             return true;
         }
         catch {

package/dist/restore.js

@@ -5,7 +5,7 @@ import ora from "ora";
 import { checkbox } from "@inquirer/prompts";
 import { loadConfig } from "./config.js";
 import { gitPull } from "./git.js";
-import { STAGING_DIR } from "./staging.js";
+import { STAGING_DIR, machineDir } from "./staging.js";
 import { logger } from "./log.js";
 const HOME = os.homedir();
 function walkDir(dir) {
@@ -23,13 +23,34 @@ function walkDir(dir) {
     }
     return results;
 }
+function listMachines() {
+    if (!fs.existsSync(STAGING_DIR))
+        return [];
+    return fs
+        .readdirSync(STAGING_DIR, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && e.name !== ".git")
+        .map((e) => e.name);
+}
 export async function restore() {
     logger.info("Starting restore");
     const config = loadConfig();
+    const baseDir = machineDir(config.machine);
     const spinner = ora("Fetching latest backup").start();
     await gitPull(config.repository);
     spinner.text = "Resolving files";
-    const stagedFiles = walkDir(STAGING_DIR);
+    if (!fs.existsSync(baseDir)) {
+        spinner.stop();
+        const available = listMachines();
+        if (available.length > 0) {
+            console.log(`\n  No backup found for machine "${config.machine}".`);
+            console.log(`  Available machines: ${available.join(", ")}\n`);
+        }
+        else {
+            console.log(`\n  No backup found for machine "${config.machine}". The repository is empty.\n`);
+        }
+        return;
+    }
+    const stagedFiles = walkDir(baseDir);
     logger.info(`Found ${stagedFiles.length} file(s) in backup repository`);
     if (stagedFiles.length === 0) {
         spinner.stop();
@@ -37,7 +58,7 @@ export async function restore() {
         return;
     }
     const fileMappings = stagedFiles.map((src) => {
-        const rel = path.relative(STAGING_DIR, src);
+        const rel = path.relative(baseDir, src);
         return { src, dest: path.join(HOME, rel), rel };
     });
     const existing = fileMappings.filter((f) => fs.existsSync(f.dest));

package/dist/staging.d.ts

@@ -1,2 +1,5 @@
 export declare const STAGING_DIR: string;
-export declare function copyToStaging(files: string[]): void;
+export declare function machineDir(machine: string): string;
+export declare function cleanStaging(machine: string): void;
+export declare function copyToStaging(files: string[], machine: string): void;
+export declare function writeRepoReadme(): void;

package/dist/staging.js

@@ -4,15 +4,24 @@ import os from "node:os";
 import { logger } from "./log.js";
 const HOME = os.homedir();
 export const STAGING_DIR = path.join(HOME, ".backdot", "repo");
-export function copyToStaging(files) {
-    if (!fs.existsSync(STAGING_DIR)) {
-        fs.mkdirSync(STAGING_DIR, { recursive: true });
-    }
+export function machineDir(machine) {
+    return path.join(STAGING_DIR, machine);
+}
+export function cleanStaging(machine) {
+    const dir = machineDir(machine);
+    if (!fs.existsSync(dir))
+        return;
+    fs.rmSync(dir, { recursive: true, force: true });
+    logger.info(`Cleaned staging directory for machine "${machine}"`);
+}
+export function copyToStaging(files, machine) {
+    const dir = machineDir(machine);
+    fs.mkdirSync(dir, { recursive: true });
     let copied = 0;
     for (const filePath of files) {
         const rel = path.relative(HOME, filePath);
         const destRel = rel.startsWith("..") ? filePath.slice(1) : rel;
-        const dest = path.join(STAGING_DIR, destRel);
+        const dest = path.join(dir, destRel);
         try {
             fs.mkdirSync(path.dirname(dest), { recursive: true });
             fs.copyFileSync(filePath, dest);
@@ -24,3 +33,27 @@ export function copyToStaging(files) {
     }
     logger.info(`Copied ${copied} file(s) to staging`);
 }
+const REPO_README = `# Dotfiles Backup
+
+This repository contains dotfiles backed up automatically using [backdot](https://github.com/sorenlouv/backdot).
+
+## Quick start
+
+Install backdot:
+
+\`\`\`bash
+npm install -g backdot
+\`\`\`
+
+Restore files from this backup:
+
+\`\`\`bash
+backdot --restore
+\`\`\`
+
+For full documentation, configuration options, and scheduling, see the [official README](https://github.com/sorenlouv/backdot).
+`;
+export function writeRepoReadme() {
+    fs.writeFileSync(path.join(STAGING_DIR, "README.md"), REPO_README);
+    logger.info("Wrote README.md to staging directory");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backdot",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Lightweight CLI to backup dotfiles and gitignored files to a Git repo on a daily schedule",
   "type": "module",
   "license": "MIT",