DOCUMENTATION · v0.1 ALPHADOCUMENTACIÓN · v0.1 ALPHA

The GitWeave theory La teoría de GitWeave

Git tracks states. GitWeave tracks changes. This single shift — from snapshots to patches — unlocks deterministic merges, parallel development without branches, and a VCS that speaks natively to AI agents. Git guarda estados. GitWeave guarda cambios. Este único cambio — de snapshots a patches — desbloquea merges determinísticos, desarrollo paralelo sin ramas, y un VCS que habla de forma nativa con agentes IA.

1 · The problem with Git 1 · El problema de Git

Git models history as a graph of snapshots. Each commit is a photo of the entire tree. Branches are just pointers to those snapshots. This model worked beautifully for a single human developer working in series, but it starts to crack the moment you add concurrency. Git modela el historial como un grafo de snapshots. Cada commit es una foto del árbol completo. Las ramas son solo punteros a esos snapshots. Este modelo funcionó para un desarrollador humano trabajando en serie, pero se rompe en cuanto agregas concurrencia.

GitButler tried to patch it with "virtual branches" on top of Git's object model. The problem doesn't disappear: eventually you still have to reconcile back into Git's worldview. In multi-agent environments where N processes modify the same repository in parallel, that reconciliation becomes O(conflicts²). GitButler intentó parcharlo con "virtual branches" encima del modelo de objetos de Git. El problema no desaparece: eventualmente hay que reconciliar de vuelta con el modelo de Git. En ambientes multi-agente donde N procesos modifican el mismo repositorio en paralelo, esa reconciliación se vuelve O(conflictos²).

CORE INSIGHTIDEA CENTRAL

The problem isn't the UX of Git. It's that Git tracks states when it should track changes. The atomic unit must have its own hash, be commutative, and never the other way around — mathematically, not heuristically. El problema no es la UX de Git. Es que Git trackea estados cuando debería trackear cambios. La unidad atómica debe tener su propio hash, ser conmutativa, y nunca al revés — matemáticamente, no heurísticamente.

2 · What it replaces exactly 2 · Qué reemplaza exactamente

GitWeave doesn't aim to be "a better Git UI". It's a different primitive. Here's how the daily GitFlow pain maps to the new model: GitWeave no busca ser "una mejor UI de Git". Es una primitiva diferente. Así se mapea el dolor diario de GitFlow al nuevo modelo:

GitFlow
The daily painEl dolor diario
  • 1 Create feature/X branch from develop Crear rama feature/X desde develop Already coupled to develop state at that momentYa está acoplada al estado de develop en ese momento
  • 2 Work for 2 weeks on the branch Trabajar 2 semanas en la rama Develop moves forward / increasing divergenceDevelop avanza / divergencia creciente
  • 3 Merge request / Pull request Merge request / Pull request Conflicts. Stash. Rebase. "It works on my branch"Conflictos. Stash. Rebase. "Funciona en mi rama"
  • 4 Release branch + hotfix + cherry-pick Release branch + hotfix + cherry-pick Cherry-pick history is fragile and manualEl histórico de cherry-picks es frágil y manual
  • 5 Merge freeze before every release Merge freeze antes de cada release Whole team blocked until it stabilizesTodo el equipo bloqueado mientras se estabiliza
Patch modelModelo de patches
The new flowEl nuevo flujo
  • 1 Open a WorkSlot for the task Abrir un WorkSlot para la tarea No branch. Just an isolated workspaceSin rama. Solo un espacio de trabajo aislado
  • 2 Write patches with explicit dependencies Escribir patches con dependencias explícitas Each patch knows what it needs, nothing moreCada patch sabe qué necesita, nada más
  • 3 Propose patches to shared store Proponer patches al store compartido If hunks don't touch, automatic mergeSi los hunks no se tocan, merge automático
  • 4 Release = curated patch selection Release = selección de patches curada Pick exactly which patches ship. ReproducibleSelecciona exactamente qué patches entran. Reproducible
  • 5 Hotfix = patch on top of production Hotfix = patch encima de producción The rest of the team keeps workingEl resto del equipo sigue trabajando
GitFlow conceptConcepto GitFlow In GitEn Git In the new modelEn el nuevo modelo
Feature branch Branch lineage, diverges over timeRama lineal, diverge con el tiempo WorkSlot + named patch seriesWorkSlot + serie de patches nombrados
Develop branch Perpetual integration branchRama de integración perpetua Shared PatchStore — emergent statePatchStore compartido — estado emergente
Release branch Manual stabilization branchRama en estabilización manual Curated patch set + immutable tagPatch set curado + tag inmutable
Hotfix branch Branch from main + cherry-pickRama desde main + cherry-pick Patch with explicit production depsPatch con deps explícitas de producción
Merge conflict 3-way merge heuristic, manualHeurística de 3-way merge, manual Hunk collision: exact, deterministicColisión de hunks: exacto, determinístico
git stash Volatile state, easy to loseEstado volátil, fácil de perder Doesn't exist — WorkSlots are independentNo existe — los WorkSlots son independientes

3 · Why this actually matters 3 · Por qué esto importa

The Git model was designed in 2005 for Linux kernel development — one human at a time, careful, deliberate changes, reviewed on mailing lists. That world is gone. Today a single codebase is touched simultaneously by: El modelo de Git fue diseñado en 2005 para el desarrollo del kernel de Linux — un humano a la vez, cambios cuidadosos y deliberados, revisados en mailing lists. Ese mundo ya no existe. Hoy un codebase es tocado simultáneamente por:

Git's response to all of this is "create another branch". GitWeave's response is "add another patch". The difference is everything. La respuesta de Git a todo esto es "crea otra rama". La respuesta de GitWeave es "agrega otro patch". La diferencia lo es todo.

Core concepts Conceptos core

GitWeave is built on five primitives. Understand these and you understand the entire system. GitWeave está construido sobre cinco primitivas. Entiende estas y entiendes todo el sistema.

◆
Patch
An immutable, content-addressed unit of change. Identified by blake3(deps + hunks + author). Once created, it never changes. Unidad de cambio inmutable identificada por contenido. Se identifica con blake3(deps + hunks + author). Una vez creado, no cambia.
  • id: PatchId (blake3)
  • deps: Vec<PatchId>
  • hunks: Vec<Hunk>
  • author: AgentId
  • meta: PatchMeta
⊙
Hunk
A contiguous region of change in a single file. Contains the old lines, new lines, and the line range. Hunks are the atoms of conflict detection. Región contigua de cambio en un archivo. Contiene las líneas viejas, nuevas, y el rango de líneas. Los hunks son los átomos de detección de conflictos.
  • file_path: String
  • start_line: u32
  • end_line: u32
  • old_content: Vec<String>
  • new_content: Vec<String>
◈
PatchDAG
A directed acyclic graph of patches. Edges represent explicit dependencies. No cycles, no hidden ordering — topological sort gives you a valid apply order. Grafo acíclico dirigido de patches. Las aristas son dependencias explícitas. Sin ciclos, sin ordenamiento oculto — el topological sort te da un orden válido de aplicación.
  • add_patch(p): validates deps exist
  • topo_order(): dependencies first
  • roots(): patches with no deps
  • tips(): patches nothing depends on
⧓
WorkSlot
An isolated workspace where a single developer or agent accumulates patches. Slots never block each other. Merging two slots is a pure function of their hunks. Espacio de trabajo aislado donde un dev o agente acumula patches. Los slots nunca se bloquean. Merge de dos slots es una función pura de sus hunks.
  • id: SlotId (UUID)
  • name: String
  • owner: AgentId
  • patches: Vec<Patch>
⊕
ConflictEngine
The heart of GitWeave. Asks one question, gets one answer: do the hunks of two patches intersect? Same file + overlapping line ranges = conflict. Everything else = compatible. No heuristics, no three-way merge, no "ours vs theirs". Just set theory. El corazón de GitWeave. Hace una pregunta, obtiene una respuesta: ¿se intersectan los hunks de dos patches? Mismo archivo + rangos superpuestos = conflicto. Todo lo demás = compatible. Sin heurísticas, sin 3-way merge, sin "ours vs theirs". Solo teoría de conjuntos.
conflict_check.rs Rust
// The entire conflict detection logic, literally: impl Hunk { pub fn intersects(&self, other: &Hunk) -> bool { self.file_path == other.file_path && self.start_line <= other.end_line && other.start_line <= self.end_line } } // Two patches conflict iff any of their hunks intersect. // That's it. That's the algorithm.
WHY THIS IS POWERFULPOR QUÉ ESTO ES PODEROSO

Because conflict detection is pure, deterministic, and local, N agents can work in parallel and merge their slots without human arbitration. Two patches either commute or they don't — a mathematical property, not a policy decision. Porque la detección de conflictos es pura, determinística y local, N agentes pueden trabajar en paralelo y mergear sus slots sin arbitraje humano. Dos patches conmutan o no conmutan — una propiedad matemática, no una decisión de política.

From zero to merge — the five-command flow De cero a merge — el flujo de cinco comandos

01

Initialize the storeInicializar el store

Creates .gw/ with the local PatchStore and snapshot index. Works standalone or alongside an existing Git repo. Crea .gw/ con el PatchStore local y el índice de snapshots. Funciona standalone o junto a un repo Git existente.

gw init
02

Open a WorkSlotAbrir un WorkSlot

Each dev or agent gets an isolated slot. No branch creation, no checkout, no switching. Multiple slots can exist simultaneously for the same person. Cada dev o agente obtiene un slot aislado. Sin crear ramas, sin checkout, sin switching. Varios slots pueden existir simultáneamente para la misma persona.

gw slot --name feature-auth
03

Write patchesEscribir patches

Edit files normally. gw record computes hunks with Myers diff, generates the blake3 PatchId, and adds the patch to the DAG with dependencies on current tips. Edita archivos normalmente. gw record computa hunks con Myers diff, genera el PatchId blake3, y agrega el patch al DAG con dependencias sobre los tips actuales.

gw record "fix: auth middleware"
04

Merge deterministicallyMerge determinístico

No conflicts unless hunks truly intersect. If they don't — instantaneous. If they do — GitWeave reports the exact pairs that collide, by file and line range. Sin conflictos a menos que los hunks se toquen. Si no — instantáneo. Si sí — GitWeave reporta los pares exactos que colisionan, por archivo y rango de líneas.

gw merge slot-a slot-b
05

Release and pushRelease y push

Freeze a curated patch set as a release tag. Export to regular Git commits via GitBridge. Your CI/CD sees nothing different — one commit per patch, with the PatchId in the trailer. Congela un patch set curado como tag de release. Exporta a commits Git regulares via GitBridge. Tu CI/CD no nota diferencia — un commit por patch, con el PatchId en el trailer.

gw release v1.0.0 && gw push origin

Parallel agents — the flagship use case Agentes en paralelo — el caso de uso insignia

GitWeave exposes a gRPC daemon designed for autonomous processes. An AI agent can open a WorkSlot, write patches, and merge them back into shared state without any human intervention. Here's what that looks like in practice: GitWeave expone un daemon gRPC diseñado para procesos autónomos. Un agente IA puede abrir un WorkSlot, escribir patches, y mergearlos de vuelta al estado compartido sin intervención humana. Esto se ve así en la práctica:

agent_workflow.proto gRPC
// 1. Agent Claude-1 opens a slot for feature work slot_a = OpenSlot({ name: "feature-x", agent: "claude-1" }) // 2. Agent Claude-2 opens a slot for refactoring slot_b = OpenSlot({ name: "refactor-y", agent: "claude-2" }) // 3. Both work simultaneously, no locks, no coordination RecordPatch({ slot: slot_a, hunks: [...], deps: [tips] }) RecordPatch({ slot: slot_b, hunks: [...], deps: [tips] }) // 4. Merge. Either works instantly, or returns exact conflicts. result = MergeSlots({ source: slot_a, target: slot_b }) match result { Merged { patch_count } => // done, no humans needed Conflict { pairs } => // structured conflict data // agents can coordinate and retry }
THE KEY DIFFERENCELA DIFERENCIA CLAVE

In Git, parallel agents inevitably produce merge conflicts that require a human to resolve. In GitWeave, parallel agents that don't touch the same lines never conflict at all. Humans only get involved when there's a real semantic collision — and even then, they get structured conflict data, not a 3-way merge marker mess. En Git, los agentes en paralelo inevitablemente producen conflictos de merge que requieren un humano. En GitWeave, los agentes que no tocan las mismas líneas nunca conflictúan. Los humanos solo intervienen cuando hay una colisión semántica real — y aun así, reciben datos estructurados, no un desastre de markers de 3-way merge.

The Git bridge El puente Git

GitWeave doesn't replace GitHub. It replaces the workflow layer above Git. The bridge exports your patch DAG as regular Git commits — one commit per patch, in topological order — so your existing CI/CD, code review, and deployment pipelines continue to work unchanged. GitWeave no reemplaza GitHub. Reemplaza la capa de flujo sobre Git. El bridge exporta tu patch DAG como commits Git regulares — un commit por patch, en orden topológico — para que tu CI/CD, code review y pipelines de deploy existentes sigan funcionando sin cambios.

export to git bash
$ gw export --to ./my-repo-git ✓ applied 3 patches ✓ wrote 3 commits to ./my-repo-git $ cd ./my-repo-git && git log --oneline 57192953 prueba merge Patch-Id: 57192953... 1b28553e add diff view + workslots Patch-Id: 1b28553e... cb4b16aa initial Patch-Id: cb4b16aa...

Each Git commit carries the original Patch-Id in the commit trailer, so the mapping is preserved. You can re-import a Git repo into GitWeave and reconstruct the DAG exactly. Cada commit Git lleva el Patch-Id original en el trailer del commit, así que el mapeo se preserva. Puedes re-importar un repo Git a GitWeave y reconstruir el DAG exactamente.

CLI reference Referencia del CLI

The gw command is the primary interface. The desktop app wraps these same operations via Tauri commands. El comando gw es la interfaz principal. La app de escritorio envuelve estas mismas operaciones vía comandos Tauri.

CommandComando DescriptionDescripción
gw init Initialize a new .gw/ patch store in the current directoryInicializa un nuevo store .gw/ en el directorio actual
gw status List all modified, added, and deleted files since last recordLista archivos modificados, añadidos, eliminados desde el último record
gw record "msg" Create a patch from current changes with the given messageCrea un patch desde los cambios actuales con el mensaje dado
gw log Show the patch DAG in topological orderMuestra el DAG en orden topológico
gw slot create X Create a new WorkSlot named XCrea un nuevo WorkSlot llamado X
gw slot list List all active WorkSlots and their patch countsLista todos los WorkSlots activos con su conteo de patches
gw merge A B Merge slot A into slot B. Reports conflicts if any.Mergea el slot A al slot B. Reporta conflictos si los hay.
gw export --to DIR Export the patch DAG as a Git repository at DIRExporta el patch DAG como repo Git en DIR

The types are the architecture Los tipos son la arquitectura

In Rust projects, the type system is the spec. Here are the core types — everything else is built on top of these. En proyectos Rust, el sistema de tipos es la especificación. Estos son los tipos core — todo lo demás se construye encima.

gw-core/src/patch.rs Rust
pub struct PatchId(blake3::Hash); pub struct Patch { pub id: PatchId, pub deps: Vec<PatchId>, pub hunks: Vec<Hunk>, pub author: AgentId, pub meta: PatchMeta, } pub struct Hunk { pub file_path: String, pub start_line: u32, pub end_line: u32, pub old_content: Vec<String>, pub new_content: Vec<String>, } pub struct WorkSlot { pub id: SlotId, pub name: String, pub owner: AgentId, pub base: Option<PatchId>, pub patches: Vec<Patch>, }

FAQ Preguntas frecuentes

Is GitWeave trying to replace Git?¿GitWeave busca reemplazar a Git?

No. GitWeave replaces the workflow layer (GitFlow, branches, merge requests). Git remains a valid storage/transport format via the bridge. You can keep using GitHub, GitLab, and your CI. No. GitWeave reemplaza la capa de flujo (GitFlow, ramas, merge requests). Git sigue siendo un formato válido de almacenamiento/transporte vía el bridge. Puedes seguir usando GitHub, GitLab y tu CI.

Why blake3 instead of SHA-1 or SHA-256?¿Por qué blake3 en vez de SHA-1 o SHA-256?

blake3 is faster, cryptographically strong, and the Rust ecosystem has excellent support for it. Git's SHA-1 is deprecated for security reasons, and SHA-256 is significantly slower than blake3 for no meaningful benefit. blake3 es más rápido, criptográficamente fuerte, y el ecosistema Rust tiene excelente soporte. El SHA-1 de Git está deprecado por razones de seguridad, y SHA-256 es significativamente más lento que blake3 sin un beneficio real.

What happens if two patches edit the same line?¿Qué pasa si dos patches editan la misma línea?

They conflict. GitWeave reports them as conflicting and refuses to merge until you resolve it — either by rebasing one on top of the other, or by manually choosing. No automatic 3-way merge magic. Conflictúan. GitWeave los reporta como conflictivos y se niega a mergearlos hasta que lo resuelvas — ya sea rebaseando uno sobre el otro, o eligiendo manualmente. Sin magia de 3-way merge automático.

Does GitWeave work on Windows and Linux?¿GitWeave funciona en Windows y Linux?

Yes. The desktop app is built with Tauri and ships as native binaries for macOS (.dmg), Windows (.exe), and Linux (.AppImage). The core library is pure Rust and runs anywhere Rust runs. Sí. La app de escritorio está construida con Tauri y se entrega como binarios nativos para macOS (.dmg), Windows (.exe) y Linux (.AppImage). La librería core es Rust puro y corre donde corra Rust.

How big is the desktop app?¿Cuánto pesa la app de escritorio?

The macOS .dmg is about 4 MB. The installed .app is about 12 MB. Compare to Electron-based alternatives that ship 200+ MB because they bundle Chrome. GitWeave uses the system webview via Tauri. El .dmg de macOS pesa unos 4 MB. La .app instalada unos 12 MB. Compara con alternativas basadas en Electron que pesan 200+ MB porque empacan Chrome. GitWeave usa el webview del sistema vía Tauri.

Is the source code open?¿El código fuente es abierto?

The binary is free to download and use. The source code is proprietary. GitWeave is built by Raphael Vielma and released to the community as a free tool. El binario es gratis de descargar y usar. El código fuente es propietario. GitWeave es desarrollado por Raphael Vielma y entregado a la comunidad como herramienta libre de uso.