🔭 Git Pulsar (v0.10.1)

Paranoid, invisible backups for students and distributed developers.

Git Pulsar is a background daemon that wakes up every 15 minutes to snapshot your work. Unlike standard autosave tools, Pulsar uses Shadow Commits—it writes directly to the git object database without touching your staging area, index, or active branch.

It ensures that even if your laptop dies (or you forget to push before leaving the library), your work is safe on the server and accessible from any other machine.

---

⚡ Features

• 👻 Ghost Mode (Shadow Commits): Backups are stored in a hidden namespace (refs/heads/wip/pulsar/...). Your git status, git branch, and git log remain completely clean.
• 🌍 Roaming Profiles: Hop between your laptop, desktop, and university lab computer. Pulsar tracks sessions per machine and lets you sync to pick up exactly where you left off.
• 🛡 Zero-Interference:
  • Uses a temporary index so it never messes up your partial git add.
  • Detects if you are rebasing or merging and waits for you to finish.
  • Prevents accidental upload of large binaries (>100MB).
• 🐙 Grand Unification: When you are done, finalize merges the backup history from all your devices into your main branch in one clean squash commit.

---

🧬 Environment Bootstrap (macOS)

Pulsar includes a one-click scaffolding tool to set up a modern, robust Python environment.

git-pulsar --env

This bootstraps the current directory with:

• uv: Initializes a project with fast package management and Python 3.12+ pinning.

• direnv: Creates an .envrc for auto-activating virtual environments and hooking into the shell.

• VS Code: Generates a .vscode/settings.json pre-configured to exclude build artifacts and use the local venv.

---

📦 Installation

macOS (Recommended)

Install via Homebrew to handle the background service registration automatically.

brew tap jacksonfergusondev/tap
brew install git-pulsar
brew services start git-pulsar

Linux / Generic

Install via uv (or pipx) and register the systemd timer.

uv tool install git-pulsar
git-pulsar install-service --interval 300  # Check every 5 mins (default: 15m)

---

🚀 The Pulsar Workflow

1. Initialize & Identify

Navigate to your project. The first time you run Pulsar, it will ask for a Machine ID (e.g., macbook, lab-pc) to namespace your backups.

cd ~/University/Astro401
git-pulsar

You are now protected. The daemon will silently snapshot your work every 15 minutes.

2. The "Session Handoff" (Sync)

You worked on your Desktop all night but forgot to push. You open your Laptop at class.

git-pulsar sync

Pulsar checks the remote, finds the newer session from desktop, and asks to fast-forward your working directory to match it. You just recovered your homework.

3. Restore a File

Mess up a script? Grab the version from 15 minutes ago.

# Restore specific file from the latest shadow backup
git-pulsar restore src/main.py

4. Finalize Your Work

When you are ready to submit or merge to main:

git-pulsar finalize

This performs an Octopus Merge. It pulls the backup history from your Laptop, Desktop, and Lab PC, squashes them all together, and stages the result on main.

---

🛠 Command Reference

Command	Description
git-pulsar	Register current repo for backups.
git-pulsar now	Force an immediate backup (e.g., before closing lid).
git-pulsar sync	New: Pull latest work from any other machine.
git-pulsar status	Check when the last backup occurred.
git-pulsar diff	Show changes between working tree and last backup.
git-pulsar restore <file>	Reset a file to its backed-up state.
git-pulsar finalize	Squash-merge all backup streams into main.
git-pulsar log	Tail the daemon logs in real-time.

---

⚙️ Configuration

You can customize behavior via ~/.config/git-pulsar/config.toml.

[core]
remote_name = "origin"

[daemon]
# Don't backup if battery is below 20% and unplugged
eco_mode_percent = 20

[limits]
# Prevent git from choking on massive files
large_file_threshold = 104857600  # 100MB

🧩 Architecture: How it works

Pulsar separates Data Safety from Git History.

1. Isolation: When the daemon wakes up, it sets GIT_INDEX_FILE=.git/pulsar_index. It stages your files there, leaving your actual staging area untouched.
2. Plumbing: It uses low-level commands (write-tree, commit-tree) to create a commit object.
3. Namespacing: This commit is pushed to a custom refspec: refs/heads/wip/pulsar/<machine-id>/<branch-name>
4. Topology: Each backup commit has two parents: the previous backup (for history) and your current HEAD (for context), creating a "Zipper" graph that tracks your work alongside the project evolution.

---

🛑 Development

1. Clone & Sync:

   git clone https://github.com/jacksonfergusondev/git-pulsar.git
   cd git-pulsar
   uv sync

2. Set Up Pre-Commit Hooks

   pre-commit install

3. Run Tests:

   uv run pytest

📄 License

MIT © Jackson Ferguson