GitKeep (bk / backup) 🛡️

Lightweight file & folder backup and version restoration CLI powered by native Git.

Zero Dependencies: Pure Node.js 18+, directly leverages system native git CLI.
Zero Pollution: Never places .git inside your project or data folders.
Zero Setup: Ready to use immediately without manual init.
Language: English throughout CLI interface and messages.

⚡ Quick Start & Common Usage

You can use the short command bk or backup from anywhere:

# 1. Backup current directory immediately (auto-initializes on first run)
bk

# 2. Backup with a custom message (no need for -m flag!)
bk "updated training hyperparameters"

# 3. Backup a specific folder or single file
bk data/ "added new dataset files"
bk config.json "bump version"

# 4. View backup history
bk log

# 5. Check what changed since the latest backup
bk diff

# 6. One-command instant rollback (revert to previous backup)
bk undo

# 7. Restore to any historical version
bk restore a1b2c3d

🌟 Key Features

1. Zero Project Pollution:
   • Your project folder (and subdirectories like data/) will NEVER contain any .git folder.
   • No hidden configuration files created in your workspace.
2. Centralized User-Directory Storage:
   • All backup repositories are safely stored in your OS User Home directory:
     • Windows: C:\Users\<username>\.gitkeep\
     • Linux / macOS: ~/.gitkeep/
3. 8-Character Unique ID & Collision Prevention:
   • An isolated registry (~/.gitkeep/registry.json) maps your workspace's absolute path to a unique 8-character ID (e.g. 632a477e).
   • Even if you have multiple folders with the same name across disks, each has a dedicated, independent Git repository.
4. Folder Deletion Synchronization:
   • When files are deleted in your workspace, bk automatically mirrors the deletion into the backup repository and commits a new version.
5. Strictly Additive & Safe Rollbacks:
   • Restoration does not rewrite or destroy Git history. It checks out the historical snapshot, writes it back to your project, and creates a new restore commit. History always moves forward!
6. Smart Command Ergonomics:
   • Eliminates redundant words (no backup backup).
   • bk without arguments backs up the current folder.
   • bk "message" automatically uses the string as commit message.

💻 CLI Commands Reference

| Command | Description | Example | | :--- | :--- | :--- | | bk | Quick backup of current directory | bk | | bk "message" | Quick backup of current directory with note | bk "fixed memory leak" | | bk <path> ["msg"] | Backup specific folder or file | bk data/ "sync dataset" | | bk log [path] | View commit history with relative time | bk log or bk log data/ | | bk diff [path] | Inspect added, modified, or deleted files | bk diff | | bk undo | Instantly roll back to previous backup version | bk undo | | bk restore <version> | Restore entire directory to specific commit | bk restore 19d3543 | | bk restore <path> <ver> | Restore single file or subfolder | bk restore config.json 19d3543 | | bk show <version> | Inspect version diffstat or file content | bk show 19d3543 | | bk status | Check project binding status and 8-char ID | bk status | | bk list | List all registered projects on this computer | bk list | | bk init | Explicitly initialize backup repository | bk init |

Command Options

• -m, --message <text>: Custom commit message.
• -n, --limit <number>: Limit number of history items in log (default: 15).
• --project <dir>: Custom target project root directory (default: cwd).
• --repo <dir>: Custom external Git repository path.
• --json: Output result in JSON format for scripting.
• -h, --help: Show help text.
• -v, --version: Show version.

📂 Storage Architecture

Your Workspace (e.g., C:\Users\meru6\Desktop\FNet)
├── data/
├── download_dataset.py
└── ...                         <--- 100% clean (NO .git, NO local config)

                        │
                        ▼
OS User Home Directory (~/.gitkeep/ or C:\Users\<username>\.gitkeep\)
├── registry.json               <--- Mapping: "C:/Users/.../FNet" -> "632a477e"
└── repos/
    └── 632a477e/               <--- Dedicated external Git repository
        ├── .git/
        └── ...

📦 Node.js Programmatic API

You can also import and use it in your Node.js scripts:

import { backup, history, restore, undo, diff } from 'gitkeep';

// Backup current directory
await backup('.', { message: 'automated daily backup' });

// Check history
const { commits } = await history('.');
console.log('Latest version:', commits[0].shortHash);

// Undo to previous version
await undo();

🧪 Testing

Run built-in tests using Node.js native test runner:

npm test

🚀 Standalone Binary Compilation (No Node.js Required)

You can compile GitKeep into a single, standalone executable binary that runs on any machine without Node.js or npm installed:

# Compile standalone Windows binary (dist/bk.exe)
npm run build

# Cross-compile for Windows, Linux, and macOS in one go
npm run build:all

Outputs in dist/:

• Windows: dist/bk.exe
• Linux: dist/bk-linux-x64
• macOS: dist/bk-macos-arm64

Simply drop bk.exe into any folder in your system PATH (or copy it to a server/USB drive), and you can run bk anywhere directly!

📄 License

MIT