git-pulsar 0.11.0

Automated, paranoid git backups for students and casual coding.

🔭 Git Pulsar (v0.11.0)

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

Pulsar is designed to feel like a native git command.

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

Backup Management

Command	Description
git pulsar	Default. Registers the current repo and ensures the daemon is watching it.
git pulsar now	Force an immediate backup (e.g., before closing lid).
git pulsar sync	Pull the latest session from any machine to your current directory.
git pulsar restore <file>	Restore a specific file from the latest backup.
git pulsar diff	See what has changed since the last backup.
git pulsar finalize	Squash-merge all backup streams into main.

Repository Control

Command	Description
git pulsar list	Show all watched repositories and their status.
git pulsar pause	Temporarily suspend backups for this repo.
git pulsar resume	Resume backups.
git pulsar remove	Stop tracking this repository entirely (keeps files).
git pulsar ignore <glob>	Add a pattern to .gitignore (and untrack it if needed).

Maintenance

Command	Description
git pulsar status	Show daemon health and backup status for the current repo.
git pulsar doctor	Clean up the registry and check system health.
git pulsar prune	Delete old backup history (>30 days) to save disk space.
git pulsar log	Tail the background daemon log.

Service

Command	Description
git pulsar install-service	Register the background daemon (LaunchAgent/Systemd).
git pulsar uninstall-service	Remove the background daemon.

---

⚙️ 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