backdot 1.0.0 → 1.2.0

package/README.md

@@ -1,89 +1,50 @@
-# backdot
+<p align="center">
+  <img src="logo-small.png" alt="backdot" width="400" />
+</p>
 
-Lightweight CLI to back up dotfiles and gitignored files to a private Git repo, with optional daily scheduling via macOS launchd.
+<h1 align="center">backdot</h1>
 
-## How it works
+<p align="center">Automated backup of important files (configs, dotfiles, gitignored files) to your own private Git repo.</p>
 
-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,50 +1,110 @@
 #!/usr/bin/env node
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import chalk from "chalk";
 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, compareFiles } 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(config.repository);
+        spinner.text = "Pushing to remote";
+        const result = await gitCommitAndPush();
+        const successMsg = result?.commitUrl
+            ? `Backup complete → ${result.commitUrl}`
+            : "Backup complete";
+        spinner.succeed(successMsg);
+        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() {
+function tildePath(filePath) {
+    const home = os.homedir();
+    return filePath.startsWith(home) ? "~" + filePath.slice(home.length) : filePath;
+}
+async function status() {
     const scheduled = isScheduled();
     console.log();
     console.log(`  Schedule:  ${scheduled ? "active (daily at 02:00)" : "not active"}`);
     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.");
+            console.log();
+            return;
+        }
+        const files = [...userFiles, CONFIG_PATH];
+        spinner.text = "Comparing with remote backup";
+        const { backedUp, modified, notBackedUp } = await compareFiles(files, config.machine);
+        spinner.stop();
+        if (modified.length === 0 && notBackedUp.length === 0) {
+            console.log(chalk.green(`  All ${files.length} file(s) are backed up ✓`));
         }
         else {
-            spinner.succeed(`${files.length} file(s) resolved`);
-            console.log();
-            for (const file of files) {
-                console.log(`  ${file}`);
+            if (modified.length > 0) {
+                console.log(chalk.yellow(`  Modified since last backup (${modified.length}):`));
+                for (const f of modified) {
+                    console.log(`        ${tildePath(f)}`);
+                }
+                console.log();
+            }
+            if (notBackedUp.length > 0) {
+                console.log(chalk.red(`  Not yet backed up (${notBackedUp.length}):`));
+                for (const f of notBackedUp) {
+                    console.log(`        ${tildePath(f)}`);
+                }
+                console.log();
             }
+            if (backedUp.length > 0) {
+                console.log(chalk.green(`  Backed up (${backedUp.length}):`));
+                for (const f of backedUp) {
+                    console.log(`        ${tildePath(f)}`);
+                }
+                console.log();
+            }
+            console.log(`  Run ${chalk.bold("backdot --backup")} to back up all changes.`);
         }
     }
     catch (err) {
@@ -54,6 +114,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,16 +127,21 @@ async function main() {
             await backup();
         }
         else if (command === "--schedule") {
+            requireMacOS();
             setupLaunchd();
         }
         else if (command === "--unschedule") {
+            requireMacOS();
             uninstallLaunchd();
         }
         else if (command === "--status") {
-            status();
+            await status();
         }
         else if (command === "--restore") {
-            await restore();
+            await restore(args[1]);
+        }
+        else if (command === "--version") {
+            console.log(getVersion());
         }
         else {
             console.log();
@@ -80,10 +150,11 @@ async function main() {
             console.log("  Commands:");
             console.log();
             console.log("    --backup       Run a backup now");
-            console.log("    --restore      Restore files from the backup repo");
+            console.log("    --restore [url] Restore files from the backup repo");
             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/commitUrl.d.ts

@@ -0,0 +1 @@
+export declare function getCommitUrl(remoteUrl: string, sha: string): string | null;

package/dist/commitUrl.js

@@ -0,0 +1,18 @@
+const PROVIDERS = {
+    "github.com": (p, sha) => `https://github.com/${p}/commit/${sha}`,
+    "gitlab.com": (p, sha) => `https://gitlab.com/${p}/-/commit/${sha}`,
+    "bitbucket.org": (p, sha) => `https://bitbucket.org/${p}/commits/${sha}`,
+};
+export function getCommitUrl(remoteUrl, sha) {
+    for (const [host, buildUrl] of Object.entries(PROVIDERS)) {
+        const idx = remoteUrl.indexOf(host);
+        if (idx === -1)
+            continue;
+        let repoPath = remoteUrl.slice(idx + host.length + 1).trim();
+        if (repoPath.endsWith(".git")) {
+            repoPath = repoPath.slice(0, -4);
+        }
+        return buildUrl(repoPath, sha);
+    }
+    return null;
+}

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,4 @@
 export declare function gitPull(repository: string): Promise<void>;
-export declare function gitSync(repository: string): Promise<void>;
+export declare function gitCommitAndPush(): Promise<{
+    commitUrl: string | null;
+} | null>;

package/dist/git.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { simpleGit, CleanOptions } from "simple-git";
 import { logger } from "./log.js";
 import { STAGING_DIR } from "./staging.js";
+import { getCommitUrl } from "./commitUrl.js";
 export async function gitPull(repository) {
     if (fs.existsSync(path.join(STAGING_DIR, ".git"))) {
         const git = simpleGit(STAGING_DIR);
@@ -12,37 +13,33 @@ 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()) {
         logger.info("No changes to commit");
-        return;
+        return null;
     }
     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}`);
+    const sha = await git.revparse(["HEAD"]);
+    const remoteUrl = (await git.remote(["get-url", "origin"])) ?? "";
+    const commitUrl = getCommitUrl(remoteUrl, sha);
+    return { commitUrl };
 }

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.d.ts

@@ -1 +1 @@
-export declare function restore(): Promise<void>;
+export declare function restore(repoUrl?: string): Promise<void>;

package/dist/restore.js

@@ -2,10 +2,10 @@ import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import ora from "ora";
-import { checkbox } from "@inquirer/prompts";
+import { checkbox, select } 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,60 @@ function walkDir(dir) {
     }
     return results;
 }
-export async function restore() {
+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);
+}
+async function resolveRepoAndMachine(repoUrl) {
+    if (!repoUrl) {
+        const config = loadConfig();
+        return { repository: config.repository, machine: config.machine };
+    }
+    const spinner = ora("Cloning backup repository").start();
+    await gitPull(repoUrl);
+    spinner.stop();
+    const machines = listMachines();
+    if (machines.length === 0) {
+        throw new Error("The backup repository is empty (no machine directories found).");
+    }
+    let machine;
+    if (machines.length === 1) {
+        machine = machines[0];
+    }
+    else {
+        machine = await select({
+            message: "Multiple machines found. Which one do you want to restore?",
+            choices: machines.map((m) => ({ name: m, value: m })),
+        });
+    }
+    return { repository: repoUrl, machine };
+}
+export async function restore(repoUrl) {
     logger.info("Starting restore");
-    const config = loadConfig();
+    const { repository, machine } = await resolveRepoAndMachine(repoUrl);
     const spinner = ora("Fetching latest backup").start();
-    await gitPull(config.repository);
+    const baseDir = machineDir(machine);
+    if (!repoUrl) {
+        await gitPull(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 "${machine}".`);
+            console.log(`  Available machines: ${available.join(", ")}\n`);
+        }
+        else {
+            console.log(`\n  No backup found for machine "${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 +84,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,12 @@
 export declare const STAGING_DIR: string;
-export declare function copyToStaging(files: string[]): void;
+export declare function machineDir(machine: string): string;
+export declare function getStagedPath(filePath: string, machine: string): string;
+export declare function cleanStaging(machine: string): void;
+export declare function copyToStaging(files: string[], machine: string): void;
+export interface ComparisonResult {
+    backedUp: string[];
+    modified: string[];
+    notBackedUp: string[];
+}
+export declare function compareFiles(files: string[], machine: string): Promise<ComparisonResult>;
+export declare function writeRepoReadme(repository: string): void;

package/dist/staging.js

@@ -1,18 +1,32 @@
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
+import { execFileSync } from "node:child_process";
+import { simpleGit } from "simple-git";
 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 getStagedPath(filePath, machine) {
+    const rel = path.relative(HOME, filePath);
+    const destRel = rel.startsWith("..") ? filePath.slice(1) : rel;
+    return path.join(machineDir(machine), destRel);
+}
+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 = getStagedPath(filePath, machine);
         try {
             fs.mkdirSync(path.dirname(dest), { recursive: true });
             fs.copyFileSync(filePath, dest);
@@ -24,3 +38,86 @@ export function copyToStaging(files) {
     }
     logger.info(`Copied ${copied} file(s) to staging`);
 }
+export async function compareFiles(files, machine) {
+    const result = { backedUp: [], modified: [], notBackedUp: [] };
+    if (files.length === 0)
+        return result;
+    const gitDir = path.join(STAGING_DIR, ".git");
+    if (!fs.existsSync(gitDir)) {
+        result.notBackedUp.push(...files);
+        return result;
+    }
+    const git = simpleGit(STAGING_DIR);
+    await git.fetch("origin");
+    let branch;
+    try {
+        branch = (await git.revparse(["--abbrev-ref", "HEAD"])).trim();
+    }
+    catch {
+        result.notBackedUp.push(...files);
+        return result;
+    }
+    const committedHashes = new Map();
+    try {
+        const treeOutput = execFileSync("git", ["ls-tree", "-r", `origin/${branch}`, `${machine}/`], {
+            encoding: "utf-8",
+            cwd: STAGING_DIR,
+        });
+        for (const line of treeOutput.split("\n")) {
+            if (!line)
+                continue;
+            const match = line.match(/^\d+ blob ([0-9a-f]+)\t(.+)$/);
+            if (match) {
+                committedHashes.set(match[2], match[1]);
+            }
+        }
+    }
+    catch {
+        result.notBackedUp.push(...files);
+        return result;
+    }
+    let sourceHashes;
+    try {
+        const hashOutput = execFileSync("git", ["hash-object", "--", ...files], {
+            encoding: "utf-8",
+        });
+        sourceHashes = hashOutput.trim().split("\n");
+    }
+    catch {
+        result.notBackedUp.push(...files);
+        return result;
+    }
+    for (let i = 0; i < files.length; i++) {
+        const repoRelPath = path.relative(STAGING_DIR, getStagedPath(files[i], machine));
+        const committedHash = committedHashes.get(repoRelPath);
+        const sourceHash = sourceHashes[i];
+        if (!committedHash) {
+            result.notBackedUp.push(files[i]);
+        }
+        else if (committedHash === sourceHash) {
+            result.backedUp.push(files[i]);
+        }
+        else {
+            result.modified.push(files[i]);
+        }
+    }
+    return result;
+}
+function repoReadme(repository) {
+    return `# Backdot Backup
+
+This repository contains dotfiles backed up automatically using [backdot](https://github.com/sorenlouv/backdot).
+
+## Restore
+
+\`\`\`bash
+npx backdot --restore ${repository}
+\`\`\`
+
+For full documentation, configuration options, and scheduling, see the [official README](https://github.com/sorenlouv/backdot).
+`;
+}
+export function writeRepoReadme(repository) {
+    fs.writeFileSync(path.join(STAGING_DIR, "README.md"), repoReadme(repository));
+    logger.info("Wrote README.md to staging directory");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backdot",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Lightweight CLI to backup dotfiles and gitignored files to a Git repo on a daily schedule",
   "type": "module",
   "license": "MIT",
@@ -21,6 +21,8 @@
   ],
   "scripts": {
     "build": "tsc",
+    "build:watch": "tsc --watch",
+    "release": "./scripts/release.sh",
     "start": "node dist/cli.js",
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
@@ -31,6 +33,7 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^8.3.0",
+    "chalk": "^5.6.2",
     "fast-glob": "^3.3.3",
     "ora": "^9.3.0",
     "simple-git": "^3.32.2",