You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Refactors documentation to emphasize deterministic engineering and distributed state reconciliation.
* docs: rebrand main readme with 'Signal vs Noise' philosophy
* docs(tests): add safety verification guide covering Fuzzing and Index Isolation
* refactor: remove src/__init__.py to enable namespace packaging
* docs(src): add architecture map detailing the 'No Porcelain' plumbing strategy
**Paranoid, invisible backups for students and distributed developers.**
9
+
**Fault-tolerant state capture for distributed development.**
10
10
11
-
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.
11
+
> **Standard `git commit` conflates two distinct actions: *saving your work* (frequency: high, noise: high) and *publishing a feature* (frequency: low, signal: high).**
12
+
>
13
+
> **Git Pulsar decouples them. It is a background daemon that provides high-frequency, out-of-band state capture, ensuring your work is immutable and recoverable without polluting your project history.**
12
14
13
-
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.
15
+
### 📡 The Mission: Decoupling Signal from Noise
16
+
In a typical workflow, developers are forced to make "WIP" commits just to switch machines or save their progress. This introduces **entropy** into the commit log, requiring complex interactive rebases to clean up later.
17
+
18
+
**Git Pulsar** treats the working directory state as a continuous stream of data. It captures this "noise" in a dedicated namespace (`refs/heads/wip/...`), keeping your primary branch purely focused on "signal" (logical units of work).
This system is designed to operate safely alongside standard Git commands without race conditions or index locking.
34
+
35
+
#### 1. Out-of-Band Indexing (The "Shadow" Index)
36
+
Most autosave tools aggressively run `git add .`, which destroys the user's carefully staged partial commits.
37
+
***The Invariant:** The user's `.git/index` must never be touched by the daemon.
38
+
***The Implementation:** Pulsar sets the `GIT_INDEX_FILE` environment variable to a temporary location (`.git/pulsar_index`). It constructs the tree object using low-level plumbing commands (`git write-tree`), bypassing the porcelain entirely. This ensures **Zero-Interference** with your active workflow.
39
+
40
+
#### 2. Distributed State Reconciliation (The "Zipper" Graph)
41
+
In a distributed environment (Laptop ↔ Desktop), state drift is inevitable.
42
+
***The Mechanism:** Pulsar maintains a separate refspec for each machine ID.
43
+
***The Topology:** When you run `git pulsar finalize`, the engine performs an **Octopus Merge**, traversing the DAG (Directed Acyclic Graph) of all machine streams and squashing them into a single, clean commit on `main`.
***The Solution:** By pushing shadow commits to the remote object database every 15 minutes, Pulsar guarantees that the **Mean Time To Recovery (MTTR)** of your work is never more than the snapshot interval, regardless of physical hardware failure.
48
+
49
+
---
50
+
24
51
## ⚡ Features
25
52
26
-
***Ghost Mode (Shadow Commits):** Backups are stored in a configured namespace (default: `refs/heads/wip/pulsar/...`). Your `git status`, `git branch`, and `git log` remain completely clean.
27
-
***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.
53
+
***Out-of-Band Indexing:** Backups are stored in a configured namespace (default: `refs/heads/wip/pulsar/...`). Your `git status`, `git branch`, and `git log` remain completely clean.
54
+
***Distributed Sessions:** 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.
28
55
***Zero-Interference:**
29
56
* Uses a temporary index so it never messes up your partial `git add`.
30
57
* Detects if you are rebasing or merging and waits for you to finish.
31
58
* Prevents accidental upload of large binaries (>100MB).
32
-
***Grand Unification:** When you are done, `finalize` merges the backup history from *all* your devices into your main branch in one clean squash commit.
59
+
***State Reconciliation:** When you are done, `finalize` merges the backup history from *all* your devices into your main branch in one clean squash commit.
33
60
34
61
---
35
62
@@ -74,7 +101,7 @@ You worked on your **Desktop** all night but forgot to push. You open your **Lap
74
101
```bash
75
102
git pulsar sync
76
103
```
77
-
*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.*
104
+
*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 work.*
78
105
79
106
### 3. Restore a File
80
107
Mess up a script? Grab the version from 15 minutes ago.
@@ -166,16 +193,6 @@ eco_mode_percent = 20
166
193
large_file_threshold = 104857600# 100MB
167
194
```
168
195
169
-
## 🧩 Architecture: How it works
170
-
171
-
Pulsar separates **Data Safety** from **Git History**.
172
-
173
-
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.
174
-
2.**Plumbing:** It uses low-level commands (`write-tree`, `commit-tree`) to create a commit object.
175
-
3.**Namespacing:** This commit is pushed to a custom refspec:
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.
The `src/` directory contains the package source code. The architecture strictly separates **OS-Level Mechanics** (Service management, Identity) from **Git Plumbing** (Object manipulation).
4
+
5
+
## Module Map
6
+
7
+
### 1. The Core Loop (State Management)
8
+
***`git_pulsar/daemon.py`**: The background process.
9
+
***Role:** The "Heartbeat." It wakes up, checks system constraints (Battery, CPU Load), and triggers the backup logic.
10
+
***Safety:** Implements `GIT_INDEX_FILE` isolation to ensure it never locks or corrupts the user's active git index.
11
+
***`git_pulsar/ops.py`**: High-level Business Logic.
12
+
***Role:** The "Controller." It orchestrates complex multi-step operations like `finalize` (Octopus Merges) and `restore`.
13
+
***Logic:** Calculates the "Zipper Graph" topology to merge shadow commits back into the main branch.
14
+
15
+
### 2. The Abstraction Layer (Plumbing)
16
+
***`git_pulsar/git_wrapper.py`**: The Git Interface.
17
+
***Role:** A strict wrapper around `subprocess`.
18
+
***Philosophy:****No Porcelain.** This module primarily uses git *plumbing* commands (`write-tree`, `commit-tree`, `update-ref`) rather than user-facing commands (`commit`, `add`) to ensure deterministic behavior.
19
+
***`git_pulsar/system.py`**: OS Abstraction.
20
+
***Role:** Identity & Environment.
21
+
***Logic:** Handles the chaos of cross-platform identity (mapping `IOPlatformUUID` on macOS vs `/etc/machine-id` on Linux) to ensure stable "Roaming Profiles."
22
+
23
+
### 3. Service Management (Lifecycle)
24
+
***`git_pulsar/service.py`**: The Installation Engine.
25
+
***Role:** Interface with the host init system.
26
+
***Logic:** Generates and registers `systemd` user timers (Linux) or instructions for `launchd` (macOS/Homebrew).
27
+
28
+
### 4. The Interface
29
+
***`git_pulsar/cli.py`**: The User Entry Point.
30
+
***Role:** Argument parsing and UI rendering.
31
+
***Tech:** Uses `rich` for terminal visualization. It delegates all logic to `ops.py` or `daemon.py`.
32
+
33
+
---
34
+
35
+
## Key Invariants
36
+
37
+
1.**Index Isolation:** The `daemon` module MUST ALWAYS set `os.environ["GIT_INDEX_FILE"]` to a temporary path before performing write operations.
38
+
2.**Zero-Destruction:** The `prune` logic in `ops.py` relies on strictly namespaced refspecs (`refs/heads/wip/pulsar/...`) and never touches standard heads.
39
+
3.**Identity Stability:** The `system` module guarantees that a Machine ID persists across reboots, preventing "Split Brain" backup histories.
Because Git Pulsar operates on the user's active working directory, our testing philosophy prioritizes **Non-Interference** and **Data Integrity** above all else. We use a multi-layered verification strategy to ensure the daemon never corrupts the staging area or the commit history.
Standard unit tests often miss edge cases in file handling. We use [Hypothesis](https://hypothesis.readthedocs.io/) to "fuzz" our critical registry logic.
9
+
***The Invariant:** The registry pruning algorithm must *never* delete a path that wasn't explicitly targeted, regardless of whitespace, encoding, or list size.
10
+
***The Mechanism:** Hypothesis generates thousands of semi-random file paths and registry states to attempt to break the `prune_registry` function.
This suite verifies the **Zero-Interference** architecture.
14
+
***Mocking the Environment:** We strictly enforce that the daemon cannot run unless `GIT_INDEX_FILE` is set to a temporary path.
15
+
***Plumbing Assertions:** We spy on the `subprocess` calls to ensure that *only* low-level plumbing commands (`git write-tree`, `git commit-tree`) are used. This proves that the user's high-level state (`git status`) remains untouched.
Pulsar relies on stable machine identity to manage distributed sessions.
19
+
***The Problem:** macOS uses `IOPlatformUUID`, Linux uses `/etc/machine-id`, and fallback behavior is flaky.
20
+
***The Solution:** We mock low-level system calls (`ioreg`, file reads) to simulate specific OS environments, ensuring that a "Session Handoff" works correctly regardless of the OS topology.
21
+
22
+
### 4. Topology Logic (`test_ops.py`)
23
+
Verifies the "State Reconciliation" engine.
24
+
***Octopus Merges:** Simulates complex multi-head merge scenarios (e.g., merging 3 different machine streams into `main`) to ensure the DAG (Directed Acyclic Graph) is constructed correctly without conflicts.
0 commit comments