Metadata-Version: 2.4
Name: git-pulsar
Version: 0.10.2
Summary: Automated, paranoid git backups for students and casual coding.
Author-email: jackson.ferguson0@gmail.com
License-File: LICENSE
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# 🔭 Git Pulsar (v0.10.2)

[![Tests](https://github.com/jacksonfergusondev/git-pulsar/actions/workflows/ci.yml/badge.svg)](https://github.com/jacksonfergusondev/git-pulsar/actions)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Style: Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

**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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
# 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`:

```bash
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`.

```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:**
    ```bash
    git clone https://github.com/jacksonfergusondev/git-pulsar.git
    cd git-pulsar
    uv sync
    ```

2. **Set Up Pre-Commit Hooks**
   ```bash
   pre-commit install
   ```

3.  **Run Tests:**
    ```bash
    uv run pytest
    ```

## 📄 License

MIT © [Jackson Ferguson](https://github.com/jacksonfergusondev)
