|
1 | 1 | # Tig |
2 | 2 |
|
3 | | -Tig is an experimental version-control substrate for humans and coding agents. |
| 3 | +**A work-first version control substrate for humans and AI coding agents.** |
4 | 4 |
|
5 | | -The starting thesis: Git is a powerful object database, but the everyday workflow around commits, branches, worktrees, public repos, and pull requests is not the right primitive for agent-heavy software development. |
| 5 | +Tig is an experimental, local-first **Git alternative** built for a world where most code is written by **AI coding agents** working in parallel. Instead of branches, worktrees, and pull requests, Tig is organized around **workspaces**, automatic **snapshots**, recorded **runs**, and clean **review units** — with Git **export/import** for compatibility. |
6 | 6 |
|
7 | | -Tig explores a different model: |
| 7 | + |
| 8 | + |
| 9 | + |
8 | 10 |
|
9 | | -- Work is continuously captured as changes and snapshots. |
10 | | -- Workspaces are cheap editable views, not fragile branch/worktree rituals. |
11 | | -- Attempts connect code changes to goals, actors, checks, and evidence. |
12 | | -- Review units package useful results after the work is done. |
13 | | -- Projections control which parts of a project are visible to which audiences. |
14 | | -- Publication is intentional; editing is not publishing. |
15 | | -- Git export exists for compatibility, but does not define the internal model. |
| 11 | +> **Keywords:** version control, Git alternative, distributed version control (DVCS), source control, content-addressed storage, AI coding agents, agentic development, autonomous coding, snapshots, code review, developer tools, Rust CLI. |
16 | 12 |
|
17 | | -## Ideology |
| 13 | +--- |
18 | 14 |
|
19 | | -Tig starts from a few beliefs: |
| 15 | +## Why Tig? |
20 | 16 |
|
21 | | -- Source control should protect unfinished work instead of forcing teams to hide it in private forks, local branches, or separate repositories. |
22 | | -- Humans and agents should be able to work messily while the system preserves enough structure to review, compare, audit, and publish clean results. |
23 | | -- Visibility should be policy-driven. "Open source" should mean a project has a public projection, not that every file and every in-flight fix is public forever. |
24 | | -- Branches, worktrees, and commits should become compatibility concepts rather than the primary way users understand their work. |
25 | | -- Filesystems and Git remotes should be interfaces over source state, not the only place source state can live. |
| 17 | +Git is a brilliant content-addressed object database, but its *everyday workflow* — branches, worktrees, staging, commits, force-pushes, PRs — was designed for humans hand-authoring history. That model strains when **fleets of AI agents** try the same task ten different ways at once. |
26 | 18 |
|
27 | | -See [docs/ideology.md](docs/ideology.md) for the longer project philosophy. |
| 19 | +Tig starts from a different thesis: |
28 | 20 |
|
29 | | -## Documentation |
| 21 | +- **Work is captured continuously.** Every edit produces a snapshot automatically — no `git add`, no "oops, lost my work." |
| 22 | +- **Workspaces are cheap, editable views** — not fragile branch/worktree rituals. Spin up ten parallel attempts at one bug; keep the one that passes. |
| 23 | +- **Runs are first-class.** A test/command result is attached to the *exact* snapshot it ran against, so review evidence is reproducible. |
| 24 | +- **Review units package clean results** *after* messy work is done. The working process can be chaotic; the reviewed output is intentional. |
| 25 | +- **Publication is intentional.** Editing is not publishing — visibility is meant to be policy-driven, not "everything is public forever." |
| 26 | +- **Git is an interface, not the source of truth.** Export to a Git commit or patch whenever you need compatibility; the internal model isn't defined by Git. |
| 27 | + |
| 28 | +If you build with Claude Code, Codex, Cursor, or your own agents, Tig is an experiment in giving them a substrate where *messy, parallel, machine-speed work* stays reviewable, comparable, and auditable. |
| 29 | + |
| 30 | +--- |
| 31 | + |
| 32 | +## What works today |
| 33 | + |
| 34 | +This is an early but **functional** prototype (not a production VCS yet — see [Status](#status)). The local work → review → Git loop runs end to end: |
| 35 | + |
| 36 | +- ✅ **Content-addressed object store** — SHA-256, raw-byte blobs (binary-safe, no bloat) |
| 37 | +- ✅ **Workspaces** — cheap editable views over project state |
| 38 | +- ✅ **Automatic snapshots** on every change, with an incremental stat-cache (no full re-hash per edit) |
| 39 | +- ✅ **Real unified diff/patch** (binary files detected, never mangled) |
| 40 | +- ✅ **Runs** — execute a command and attach its stdout/stderr/exit-code to a snapshot |
| 41 | +- ✅ **Review units** — package a chosen snapshot with its run evidence |
| 42 | +- ✅ **Git export/import** — turn a review unit into a Git commit or patch |
| 43 | +- ✅ **Crash-safe atomic writes** + a process-level **write lock** for safe concurrent use |
| 44 | +- ✅ **CLI** *and* a **programmatic Rust API** for agents |
| 45 | + |
| 46 | +--- |
| 47 | + |
| 48 | +## Install |
| 49 | + |
| 50 | +Tig is a single self-contained Rust binary. |
| 51 | + |
| 52 | +### Option 1 — install straight from GitHub (recommended) |
| 53 | + |
| 54 | +```bash |
| 55 | +cargo install --git https://github.com/KrtinShet/tig |
| 56 | +``` |
| 57 | + |
| 58 | +This puts a `tig` binary on your `PATH` (via `~/.cargo/bin`). |
| 59 | + |
| 60 | +### Option 2 — build from source |
| 61 | + |
| 62 | +```bash |
| 63 | +git clone https://github.com/KrtinShet/tig |
| 64 | +cd tig |
| 65 | +cargo build --release |
| 66 | +# binary at ./target/release/tig |
| 67 | +``` |
| 68 | + |
| 69 | +> Requires a [Rust toolchain](https://rustup.rs) (stable). `git` must be installed for the Git export/import bridge. |
| 70 | +
|
| 71 | +--- |
| 72 | + |
| 73 | +## Quickstart (60 seconds) |
| 74 | + |
| 75 | +```bash |
| 76 | +# 1. Initialize a Tig project in the current directory |
| 77 | +tig init --name my-project |
| 78 | + |
| 79 | +# 2. Create a workspace (an actor can be you or an agent like "claude"/"codex") |
| 80 | +tig workspace create fix-auth --actor claude --goal "Fix the auth timeout" |
| 81 | + |
| 82 | +# 3. Write files — every write auto-creates a snapshot |
| 83 | +tig write /src/auth.js --content 'exports.timeout = 30000;' |
| 84 | +# ...or pull content from a file: |
| 85 | +tig write /src/auth.js --from ./patch-content.js |
| 86 | + |
| 87 | +# 4. Run a check — its result is attached to the exact snapshot |
| 88 | +tig run execute "node -e \"require('./src/auth.js')\"" |
| 89 | + |
| 90 | +# 5. Inspect history and runs |
| 91 | +tig snapshot list |
| 92 | +tig run list |
| 93 | + |
| 94 | +# 6. Package a review unit (from the latest passing snapshot → a target) |
| 95 | +tig review create --from latest-passing --target <base-snapshot-id> |
| 96 | +tig review list |
| 97 | +tig review show <review-id> |
| 98 | + |
| 99 | +# 7. Export the reviewed result to Git for compatibility |
| 100 | +tig git export --review <review-id> # creates a Git commit |
| 101 | +tig git export --review <review-id> --patch # or a .patch file |
| 102 | +``` |
| 103 | + |
| 104 | +Want to see the whole loop run, including two parallel attempts at the same bug where one passes and one fails? Run the end-to-end demo: |
| 105 | + |
| 106 | +```bash |
| 107 | +bash tests/e2e_demo.sh |
| 108 | +``` |
| 109 | + |
| 110 | +### Full command reference |
| 111 | + |
| 112 | +| Command | What it does | |
| 113 | +|---|---| |
| 114 | +| `tig init [--name <n>]` | Initialize a project (creates `.tig/`) | |
| 115 | +| `tig workspace create <name> [--actor <a>] [--goal <g>]` | Create an editable workspace | |
| 116 | +| `tig workspace list` | List workspaces | |
| 117 | +| `tig workspace switch <name>` | Set the active workspace | |
| 118 | +| `tig read <path>` | Read a file from the active workspace | |
| 119 | +| `tig write <path> --content <s> \| --from <file>` | Write a file (auto-snapshots) | |
| 120 | +| `tig run execute "<command>"` | Run a command, record evidence against a snapshot | |
| 121 | +| `tig run list` | List recorded runs | |
| 122 | +| `tig snapshot list [--passing]` | List snapshots (optionally only passing ones) | |
| 123 | +| `tig review create --from <snap\|latest\|latest-passing> --target <snap>` | Build a review unit | |
| 124 | +| `tig review list` / `tig review show <id>` | Inspect review units | |
| 125 | +| `tig git export --review <id> [--patch]` | Export a review unit to a Git commit or patch | |
| 126 | +| `tig git import <path-to-git-repo>` | Seed a Tig project from an existing Git repo | |
| 127 | + |
| 128 | +--- |
| 129 | + |
| 130 | +## Use Tig in your own project |
| 131 | + |
| 132 | +### A) From any language — drive the CLI |
| 133 | + |
| 134 | +Because every Tig operation is a CLI command with deterministic output, agents and scripts in **any language** can use it by shelling out — no Git plumbing, no branch management. |
| 135 | + |
| 136 | +```python |
| 137 | +import subprocess |
| 138 | + |
| 139 | +def tig(*args): |
| 140 | + return subprocess.run(["tig", *args], capture_output=True, text=True, check=True).stdout |
| 141 | + |
| 142 | +tig("init", "--name", "runtime-platform") |
| 143 | +tig("workspace", "create", "fix-auth", "--actor", "my-agent", "--goal", "Fix auth timeout") |
| 144 | +tig("write", "/src/auth.js", "--content", "exports.timeout = 30000;") |
| 145 | +tig("run", "execute", "npm test auth") |
| 146 | +tig("review", "create", "--from", "latest-passing", "--target", "main") |
| 147 | +``` |
30 | 148 |
|
31 | | -- [Problem](docs/problem.md): what Git/GitHub do not model well enough for agent-heavy work. |
32 | | -- [Solution](docs/solution.md): the work-first model Tig proposes. |
33 | | -- [Ideology](docs/ideology.md): the beliefs that should constrain product and engineering choices. |
34 | | -- [Primitives](docs/primitives.md): the core nouns in the system. |
35 | | -- [Workflows](docs/workflows.md): concrete human, agent, security, and projection examples. |
36 | | -- [MVP](docs/mvp.md): the first prototype scope and non-goals. |
37 | | -- [Comparisons](docs/comparisons.md): how Tig relates to Git, GitHub, jj, and monorepo systems. |
38 | | -- [Security Model](docs/security-model.md): actors, policies, projections, and publication checks. |
39 | | -- [Architecture](docs/architecture.md): early component boundaries for the prototype. |
40 | | -- [Roadmap](docs/roadmap.md): staged path from docs to local prototype to hosted collaboration. |
41 | | - |
42 | | -## Early Primitives |
43 | | - |
44 | | -- **Project**: the top-level source, policy, review, and publication boundary. |
45 | | -- **Object Store**: immutable file contents and source-state objects. |
46 | | -- **Workspace**: an editable view over project state. |
47 | | -- **Change**: a tracked edit or operation inside a workspace. |
48 | | -- **Snapshot**: a complete project/workspace state at a point in time. |
49 | | -- **Attempt**: a purposeful line of work by a human or agent. |
50 | | -- **Run**: a command/check executed against an exact snapshot. |
51 | | -- **Review Unit**: a clean reviewable package derived from one or more snapshots. |
52 | | -- **Projection**: a policy-controlled visible view of a project. |
53 | | -- **Publication**: an intentional update to a projection or external system. |
| 149 | +### B) From Rust — use the programmatic API |
| 150 | + |
| 151 | +Add Tig as a dependency: |
| 152 | + |
| 153 | +```toml |
| 154 | +[dependencies] |
| 155 | +tig = { git = "https://github.com/KrtinShet/tig" } |
| 156 | +``` |
| 157 | + |
| 158 | +Then drive it in-process — ideal for embedding in a Rust-based agent or tool: |
| 159 | + |
| 160 | +```rust |
| 161 | +use std::path::Path; |
| 162 | +use tig::api::Tig; |
| 163 | + |
| 164 | +fn main() -> anyhow::Result<()> { |
| 165 | + // Initialize (or `Tig::open`) a project |
| 166 | + let tig = Tig::init(Path::new("./my-project"), Some("my-project".into()))?; |
| 167 | + |
| 168 | + // Create a workspace for an actor + goal |
| 169 | + tig.create_workspace("fix-auth", "claude", Some("Fix auth timeout".into()))?; |
| 170 | + |
| 171 | + // Edits auto-create snapshots; returns the new snapshot id |
| 172 | + let snap = tig.write_file("fix-auth", "/src/auth.js", "exports.timeout = 30000;")?; |
| 173 | + |
| 174 | + // Or apply a unified diff/patch |
| 175 | + // tig.apply_patch("fix-auth", "/src/auth.js", patch_str)?; |
| 176 | + |
| 177 | + // Run a check; evidence is bound to the exact snapshot |
| 178 | + let run = tig.run_check("fix-auth", "npm test auth", "claude")?; |
| 179 | + println!("run {} -> {:?}", run.id, run.status); |
| 180 | + |
| 181 | + // Package a review unit and export it to Git |
| 182 | + let review = tig.create_review_unit("fix-auth", "latest-passing", &snap)?; |
| 183 | + let commit = tig.export_to_git(&review.id)?; |
| 184 | + println!("exported Git commit {commit}"); |
| 185 | + Ok(()) |
| 186 | +} |
| 187 | +``` |
| 188 | + |
| 189 | +--- |
| 190 | + |
| 191 | +## Core concepts |
| 192 | + |
| 193 | +| Primitive | Meaning | |
| 194 | +|---|---| |
| 195 | +| **Project** | Top-level source, review, and publication boundary (a `.tig/` directory) | |
| 196 | +| **Object Store** | Immutable, content-addressed file contents and source-state objects | |
| 197 | +| **Workspace** | An editable view over project state (replaces branches/worktrees) | |
| 198 | +| **Change** | A tracked edit or operation inside a workspace | |
| 199 | +| **Snapshot** | A complete project state at a point in time (created automatically) | |
| 200 | +| **Attempt** | A purposeful line of work by a human or agent | |
| 201 | +| **Run** | A command/check executed against an exact snapshot, with captured evidence | |
| 202 | +| **Review Unit** | A clean, reviewable package derived from one or more snapshots | |
| 203 | +| **Projection** | A policy-controlled visible view of a project *(planned)* | |
| 204 | +| **Publication** | An intentional update to a projection or external system *(planned)* | |
| 205 | + |
| 206 | +--- |
| 207 | + |
| 208 | +## How Tig compares |
| 209 | + |
| 210 | +| | **Git** | **jj (Jujutsu)** | **Tig** | |
| 211 | +|---|---|---|---| |
| 212 | +| Primary unit | Commit on a branch | Mutable change | Snapshot in a workspace | |
| 213 | +| Capturing work | Manual (`add`/`commit`) | Automatic working-copy | **Automatic snapshots** | |
| 214 | +| Parallel attempts | Branches/worktrees | Anonymous changes | **Cheap workspaces** | |
| 215 | +| Test/check evidence | External (CI) | External | **First-class runs bound to snapshots** | |
| 216 | +| Review artifact | Pull request | Change/PR | **Review unit (post-hoc, clean)** | |
| 217 | +| Visibility model | Repo-level | Repo-level | **Policy-driven projections** *(planned)* | |
| 218 | +| Git compatibility | — | Native | **Export/import bridge** | |
| 219 | + |
| 220 | +Tig is **not** trying to replace Git's object model — it reuses the same content-addressed idea and exports to Git on demand. It's reworking the *workflow layer* above it for agent-heavy development. |
| 221 | + |
| 222 | +--- |
| 223 | + |
| 224 | +## Project layout |
| 225 | + |
| 226 | +A Tig project lives entirely under `.tig/`: |
| 227 | + |
| 228 | +``` |
| 229 | +.tig/ |
| 230 | + objects/ # content-addressed blobs, trees, snapshots |
| 231 | + refs/ # snapshot references |
| 232 | + workspaces/ # per-workspace files + metadata + stat cache |
| 233 | + runs/ # recorded command runs (evidence) |
| 234 | + reviews/ # review units |
| 235 | + metadata.json |
| 236 | + lock # advisory write lock |
| 237 | +``` |
| 238 | + |
| 239 | +--- |
54 | 240 |
|
55 | 241 | ## Status |
56 | 242 |
|
57 | | -This repository is a blank-slate research and implementation workspace. The first milestone is to turn the primitive model into a concrete local prototype that can: |
| 243 | +Tig is an **experimental research prototype**, not a production version-control system. The local work-to-review loop is implemented and tested (19 unit + 2 integration tests + an end-to-end demo, all green), with crash-safe writes and concurrency-safe locking. |
| 244 | + |
| 245 | +**Implemented:** object store, workspaces, automatic + incremental snapshots, diff/patch, runs, review units, Git export/import, atomic writes, write lock, CLI + Rust API. |
| 246 | + |
| 247 | +**Not yet (and intentionally out of scope for the first prototype):** |
| 248 | + |
| 249 | +- Policy-driven **projections** and intentional **publication** (the visibility model) |
| 250 | +- Hosted, multi-tenant collaboration / a GitHub-style server |
| 251 | +- `fsync` power-loss durability and full Git history fidelity on import |
| 252 | +- Merge UI, permissions dashboards, package registry |
| 253 | + |
| 254 | +Treat it as a place to **dogfood the workflow**, not yet as the home for irreplaceable work. Feedback and ideas are very welcome. |
| 255 | + |
| 256 | +--- |
| 257 | + |
| 258 | +## Documentation |
| 259 | + |
| 260 | +- [Problem](docs/problem.md) — what Git/GitHub don't model well for agent-heavy work |
| 261 | +- [Solution](docs/solution.md) — the work-first model Tig proposes |
| 262 | +- [Ideology](docs/ideology.md) — the beliefs constraining product/engineering choices |
| 263 | +- [Primitives](docs/primitives.md) — the core nouns in the system |
| 264 | +- [Workflows](docs/workflows.md) — concrete human, agent, security, and projection examples |
| 265 | +- [MVP](docs/mvp.md) — first prototype scope and non-goals |
| 266 | +- [Comparisons](docs/comparisons.md) — Tig vs Git, GitHub, jj, monorepo systems |
| 267 | +- [Security Model](docs/security-model.md) — actors, policies, projections, publication checks |
| 268 | +- [Architecture](docs/architecture.md) — early component boundaries |
| 269 | +- [Roadmap](docs/roadmap.md) — staged path from prototype to hosted collaboration |
| 270 | + |
| 271 | +--- |
| 272 | + |
| 273 | +## Contributing |
| 274 | + |
| 275 | +Issues, discussions, and PRs are welcome — especially around the workflow model, the agent API surface, and real-world agent integrations. Build and test with: |
| 276 | + |
| 277 | +```bash |
| 278 | +cargo build |
| 279 | +cargo test |
| 280 | +bash tests/e2e_demo.sh |
| 281 | +``` |
| 282 | + |
| 283 | +## License |
58 | 284 |
|
59 | | -1. Create a project. |
60 | | -2. Create workspaces from a base snapshot. |
61 | | -3. Apply file changes through an API. |
62 | | -4. Record snapshots automatically. |
63 | | -5. Attach runs/check results to snapshots. |
64 | | -6. Produce a review unit from a selected snapshot. |
65 | | -7. Export the result to Git for compatibility. |
| 285 | +Licensed under the [MIT License](LICENSE). |
0 commit comments