gitcrawl: crawler web direccionable por contenido y motor de snapshots en Git

Publicado: 31 de agosto de 2026. Categoría: Sistemas & Arquitectura. Tiempo de lectura: ~6 min
Etiquetas: C99, Git, Web Archiving, Crawlers, POSIX, Arquitectura, Sistemas

En mi artículo anterior sobre archivar la web con Git, me puse a explorar la teoría detrás de usar el almacén de objetos direccionable por contenido de Git como base de datos histórica para páginas web y documentación técnica.

La jugada era sencilla: en vez de calarse gigabytes de archivos WARC pesadísimos o carpetas atiborradas de HTML repetido, aprovechar los grafos acíclicos y la compresión delta de Git para sacar diffs instantáneos en la terminal con git diff y git log.

Hoy liberé la implementación completa en código abierto: gitcrawl.

Aquí te echo el cuento de la arquitectura del motor en C99, cómo se conecta directo con la plomería interna de Git sin tocar el directorio de trabajo para ir volando, y los números de compresión.

1. Arquitectura del pipeline

gitcrawl sigue la filosofía UNIX: una herramienta modular, escrita en C99 pulcro, sin dependencias raras ni runtimes pesados, lista para meterla en pipelines y cron jobs.

                  ┌────────────────────────────────────────┐
                  │          URL / Stream de Entrada       │
                  └───────────────────┬────────────────────┘
                                      │
                                      ▼
                  ┌────────────────────────────────────────┐
                  │      Motor HTTP & Conexión POSIX       │
                  │   - Headers, TLS info, Status Codes    │
                  └───────────────────┬────────────────────┘
                                      │
                                      ▼
                  ┌────────────────────────────────────────┐
                  │          Sanitizador de DOM            │
                  │ - Stripping de scripts, ads y CSRF     │
                  │ - Preservación de tags semánticos      │
                  └───────────────────┬────────────────────┘
                                      │
                                      ▼
                  ┌────────────────────────────────────────┐
                  │    Parser a Markdown (via unipaste)    │
                  │ - Tablas ASCII / Markdown estructurado │
                  └───────────────────┬────────────────────┘
                                      │
                                      ▼
                  ┌────────────────────────────────────────┐
                  │      Capa de Plomería Git (C99)        │
                  │  1. Hash-object: Blob Markdown         │
                  │  2. Hash-object: Blob Metadata JSON    │
                  │  3. Mktree: Árbol de directorios       │
                  │  4. Commit-tree: Commit histórico      │
                  │  5. Update-ref: Actualización de rama  │
                  └───────────────────┬────────────────────┘
                                      │
                                      ▼
                  ┌────────────────────────────────────────┐
                  │         .git/objects (Packfiles)       │
                  └────────────────────────────────────────┘

2. Ingesta a memoria: saltándonos el directorio de trabajo

Uno de los peores cuellos de botella al rastrear miles de URLs es el sistema de archivos. Si te pones a hacer un checkout en un repositorio con 50.000 páginas, el disco colapsa creando y borrando inodos a lo loco.

gitcrawl no toca el árbol de trabajo (working tree) para nada. Le escribe directo a la base de datos de objetos en .git/objects:

/* Estructura básica de inserción directa a la base de objetos */
typedef struct {
    char sha_hex[41];
    size_t size;
    const char *path;
} git_blob_t;

/* Inyecta un blob en memoria sin escribir archivo temporal en disco */
int git_write_blob_stream(const char *data, size_t len, char *out_sha) {
    /* Ejecuta el equivalente de plomería interna: git hash-object -w --stdin */
    return git_plumbing_hash_object(data, len, out_sha);
}

Al procesar cada URL:
1. El HTML crudo se limpia en un buffer de memoria de tamaño acotado.
2. El motor genera dos blobs: index.md (el contenido normalizado y al pelo) y metadata.json (encabezados HTTP, timestamp, IP, status code y saltos de redirección).
3. Se arma el árbol de directorios (git mktree) picando el host y la ruta (docs.rs/tokio/index.md).
4. Si el hash del árbol resultante es idéntico al commit anterior, gitcrawl detecta en 0 ms que la página no cambió y se ahorra el commit de una vez.
5. Si hubo cambios, clava un commit atómico amarrado al padre (git commit-tree) y actualiza la rama (git update-ref refs/heads/archive).

3. Reducción de ruido y normalización

Si comiteas el HTML crudo tal cual, cada corrida te va a generar diffs falsos por culpa de tokens de sesión, nonces CSRF, banners publicitarios y tiempos de render dinámicos.

gitcrawl monta un parser de streams basado en el motor de unipaste. Agarra el contenido semántico de verdad (<main>, <article>, o el bloque con más texto), convirtiendo títulos, tablas, listas y bloques de código a Markdown limpiecito.

<!-- Diff limpio generado por git diff en una actualización de API -->
--- a/api.stripe.com/v1/charges/index.md
+++ b/api.stripe.com/v1/charges/index.md
@@ -14,3 +14,5 @@
 | `amount` | integer | Monto en centavos |
-| `currency` | string | Código ISO de 3 letras |
+| `currency` | string | Código ISO de 3 letras (ej. usd, eur) |
+| `payment_method` | string | ID del método de pago asociado |

4. Benchmarks y eficiencia de almacenamiento

Puse a prueba gitcrawl archivando 500 páginas de documentación técnica (incluyendo specs de RFCs, docs de Python y manuales POSIX) con revisiones diarias durante un mes entero:

Estrategia de Archivo	Espacio en Disco (30 corridas)	Velocidad de Diff en Terminal	Requiere Base de Datos
HTML Crudo en Disco	4.8 GB	Lento (`diff -r`)	No
Archivos WARC	3.2 GB	No nativo (requiere herramientas WARC)	Sí / Índices
`gitcrawl` (Git Packfiles)	142 MB	Instantáneo (`git diff`, `git log`)	No (Git nativo)

Gracias a la compresión delta de Git (git pack-objects), las páginas donde solo cambia una línea o un párrafo ocupan apenas unos cuantos bytes por snapshot histórico. Una mantequilla.

5. ¿Por qué no SQLite o almacenamiento plano? Lo que estuve pensando sobre crawlers distribuidos

Cuando estaba diseñando este motor, me puse a pensar si no era más fácil tirar los snapshots en una base de datos embebida como SQLite o en un bucket S3 con archivos planos y ya.

Para un crawler solitario en mi propia laptop, SQLite es tremenda nota. Pero en el momento en que me puse a pensar en escalar esto con múltiples agentes de rastreo corriendo en paralelo en varias máquinas, contenedores o lambdas, las bases de datos monolíticas y los archivos planos empiezan a mostrar las costuras y se arma un saperoco:

Los rollos de SQLite y archivos planos en entornos distribuidos

Bloqueos de concurrencia y replicación pesada. SQLite no aguanta múltiples escritores concurrentes en red sin trabarse (SQLITE_BUSY o bloqueos de WAL). Sincronizar bases de datos SQLite entre servidores exige protocolos de consenso complejos (Raft/LiteFS) o mover bases de datos enteras por la red.
La pesadilla de fusionar capturas. Si tienes tres agentes crawleando en distintas regiones y luego quieres unir sus bases de datos SQLite, te toca resolver colisiones de IDs autoincrementales, marcas de tiempo chocando y reconciliación manual fila por fila.
Archivos planos en disco o S3. Guardar carpetas crudas produce condiciones de carrera (Last Write Wins), borrando versiones intermedias si dos agentes le caen a la misma URL casi al mismo tiempo. Además, te quedas sin compresión delta nativa.

                      Agente Alpha (us-east)   --> Branch: agent/alpha
                                                            |
                      Agente Bravo (eu-west)   --> Branch: agent/bravo --> Git Merge (Sin Trancas)
                                                            |             ├── Deduplicación SHA al tiro
                      Agente Charlie (ap-tokyo)--> Branch: agent/charlie  └── Compresión Delta en Packfiles

Por qué el Merkle DAG de Git doma el caos multi-agente sin despeinarse

Deduplicación criptográfica sin coordinar nada. Git es un almacén direccionable por contenido. Si 10 agentes en servidores distintos descargan la misma página al mismo segundo y el contenido está intacto, los 10 calculan exactamente el mismo hash SHA del blob. La deduplicación es matemática y al tiro, sin tener que preguntarle a un servidor central ni pedir bloqueos distribuidos.
Ramas independientes y convergencia relajada. Cada agente trabaja en su propia rama (agent/crawler-eu, agent/crawler-us, etc.) o en un fork local. Cuando terminan su tanda, hacen git push a un bare repo central o sincronizan peer-to-peer. Unir todo el historial es un simple git merge de árboles. Como los crawlers suelen tocar rutas distintas, los merges se resuelven en milisegundos sin trancas.
Procedencia e inmutabilidad. Cada snapshot queda amarrado a su commit padre con autor y timestamp. No hay forma de meter mano y alterar una captura vieja sin romper todo el grafo. Y si quieres auditar con lupa qué agente o modelo de IA capturó cada versión, le firmas los commits con git commit -S.
Transporte de red optimizado al máximo. El protocolo nativo de Git (git-upload-pack / git-receive-pack) calcula deltas al vuelo. Cuando un agente sube su trabajo, solo viajan los bytes que cambiaron de verdad, ahorrando un gentío de ancho de banda en la nube.

6. Integración con el ecosistema CLI

Al dejar los snapshots en un repositorio Git estándar, puedes combinar gitcrawl con tus herramientas de diario en la terminal:

Búsqueda difusa en el historial con approx:
bash git log --name-only --format="" | sort -u | approx "stripe charges"
Rastreo de cambios en palabras clave:
bash git log -p -S "deprecated" -- docs.github.com/
Exportación limpia a LLMs y pipelines RAG:
Como el repositorio almacena Markdown estructurado, puedes alimentar modelos de lenguaje locales directamente con cat o scripts en Bash.

El código fuente, manual de instalación y opciones de configuración están disponibles en GitHub: github.com/riccivr/gitcrawl.

gitcrawl: content-addressable web archiver and snapshot engine backed by Git

Published: August 31, 2026. Category: Systems & Architecture. Reading time: ~6 min
Tags: C99, Git, Web Archiving, Crawlers, POSIX, Architecture, Systems

In my previous article on archiving the web with Git, I explored using Git's content-addressable object store as a historical database for web pages and documentation.

The core idea was simple: instead of hoarding gigabytes of monolithic WARC archives or directories full of duplicate HTML, use Git's directed acyclic graph and delta compression to get instant terminal diffs with git diff and git log.

Today I published the open-source implementation: gitcrawl.

Here is the C99 engine architecture, how it talks directly to Git plumbing without touching the working directory, and the storage numbers.

1. Pipeline architecture

gitcrawl follows the UNIX philosophy: a modular CLI tool written in clean C99, free of heavy runtimes, and built for automated pipelines and cron jobs.

                  ┌────────────────────────────────────────┐
                  │             Target URL / Stream        │
                  └───────────────────┬────────────────────┘
                                      │
                                      ▼
                  ┌────────────────────────────────────────┐
                  │       HTTP Engine & POSIX Sockets      │
                  │   - Headers, TLS info, Status Codes    │
                  └───────────────────┬────────────────────┘
                                      │
                                      ▼
                  ┌────────────────────────────────────────┐
                  │             DOM Sanitizer              │
                  │ - Strip scripts, trackers, CSRF nonces │
                  │ - Preserve structural semantic tags    │
                  └───────────────────┬────────────────────┘
                                      │
                                      ▼
                  ┌────────────────────────────────────────┐
                  │    Markdown Parser (via unipaste)      │
                  │ - ASCII tables / Structured Markdown   │
                  └───────────────────┬────────────────────┘
                                      │
                                      ▼
                  ┌────────────────────────────────────────┐
                  │        Git Plumbing Layer (C99)        │
                  │  1. Hash-object: Markdown Blob         │
                  │  2. Hash-object: Metadata JSON Blob    │
                  │  3. Mktree: Hierarchical directory tree│
                  │  4. Commit-tree: Historic commit node  │
                  │  5. Update-ref: Atomic branch pointer  │
                  └───────────────────┬────────────────────┘
                                      │
                                      ▼
                  ┌────────────────────────────────────────┐
                  │         .git/objects (Packfiles)       │
                  └────────────────────────────────────────┘

2. In-memory ingest: bypassing the working tree

A primary bottleneck when tracking thousands of URLs is filesystem I/O. If you checkout a repository containing 50,000 pages, the filesystem struggles creating and deleting inodes.

gitcrawl never touches the working tree. It writes directly to the .git/objects database:

/* Core structure for direct object store insertion */
typedef struct {
    char sha_hex[41];
    size_t size;
    const char *path;
} git_blob_t;

/* Injects a blob in memory without writing a temporary file to disk */
int git_write_blob_stream(const char *data, size_t len, char *out_sha) {
    /* Executes internal plumbing equivalent: git hash-object -w --stdin */
    return git_plumbing_hash_object(data, len, out_sha);
}

When processing a URL:
1. Raw HTML is sanitized inside a memory-bounded buffer.
2. The engine generates two blobs: index.md (normalized readable content) and metadata.json (HTTP headers, timestamp, remote IP, status code, and redirect chain).
3. The hierarchical tree (git mktree) is constructed by sharding host and path (docs.rs/tokio/index.md).
4. If the computed tree hash matches the previous commit, gitcrawl detects in 0 ms that the page is unchanged and skips commit creation.
5. If changes occurred, it generates an atomic commit (git commit-tree) and updates the branch ref (git update-ref refs/heads/archive).

3. Noise reduction and normalization

Committing raw HTML produces dirty diffs on every crawl cycle due to session cookies, CSRF nonces, and server render timestamps.

gitcrawl embeds a streaming parser inspired by unipaste. It extracts primary semantic content (<main>, <article>, or the densest text node), converting headings, tables, lists, and code blocks into clean Markdown.

<!-- Clean diff produced by git diff on an API doc update -->
--- a/api.stripe.com/v1/charges/index.md
+++ b/api.stripe.com/v1/charges/index.md
@@ -14,3 +14,5 @@
 | `amount` | integer | Amount in cents |
-| `currency` | string | 3-letter ISO code |
+| `currency` | string | 3-letter ISO code (e.g. usd, eur) |
+| `payment_method` | string | ID of the attached payment method |

4. Benchmarks and storage efficiency

I tested gitcrawl by snapshotting 500 technical documentation pages (RFC specs, Python docs, and POSIX manuals) daily across 30 days:

Archival Strategy	Disk Usage (30 snapshot cycles)	Terminal Diff Speed	Requires Database
Raw HTML on Disk	4.8 GB	Slow (`diff -r`)	No
WARC Archives	3.2 GB	Non-native (needs WARC tools)	Yes / Indices
`gitcrawl` (Git Packfiles)	142 MB	Instant (`git diff`, `git log`)	No (Native Git)

Thanks to Git delta compression (git pack-objects), pages with only minor text modifications take just a few bytes per historic snapshot.

5. Why not SQLite or flat files? My thoughts on distributed crawling

While designing this storage engine, I thought about just dumping snapshots into an embedded database like SQLite or an S3 bucket with flat files.

For single-node local runs on my laptop, SQLite works fine. But when I thought about scaling this to multiple crawler agents running concurrently across different machines, containers, or regions, traditional storage models fall apart:

Limitations of SQLite and flat files

Lock contention and network sync. SQLite does not support multiple concurrent network writers without blocking (SQLITE_BUSY or write-ahead log lock queues). Synchronizing SQLite across nodes requires consensus layers (Raft/LiteFS) or copying whole databases.
Merging conflicts. If three autonomous crawler agents run across different regions and later try to combine their SQLite databases, reconciling auto-increment IDs, timestamp collisions, and row-level conflicts is messy.
Flat files on S3. Storing raw files leads to race conditions (Last Write Wins), wiping intermediate historical states when two workers hit the same URL around the same time. There is also no native cross-revision delta compression.

                      Agent Alpha (us-east)    --> Branch: agent/alpha
                                                            |
                      Agent Bravo (eu-west)    --> Branch: agent/bravo --> Git Merge (Lock-Free)
                                                            |             ├── Automatic SHA Deduplication
                      Agent Charlie (ap-tokyo) --> Branch: agent/charlie  └── Packfile Delta Compression

Why Git's Merkle DAG handles multi-agent crawling

Zero-coordination cryptographic deduplication. Git is a content-addressable store. If 10 distributed crawler agents scrape the exact same page at the exact same moment and the content is unchanged, all 10 compute the exact same SHA hash. Deduplication happens mathematically and instantly without a central coordinator or distributed locks.
Independent branching and conflict-free convergence. Each crawler agent works on its own branch (agent/crawler-eu, agent/crawler-us) or local clone. When a batch finishes, they push to a central bare repo or sync peer-to-peer. Reconciling the entire archive history is a standard non-blocking git merge. Because crawlers touch disjoint directory paths in the tree, merges resolve in milliseconds.
Cryptographic provenance and tamper evidence. Every snapshot links to its parent tree and author metadata. It is mathematically impossible to modify a historical snapshot without invalidating all downstream commit hashes. Commits can be signed (git commit -S) to trace exactly which agent or AI pipeline captured a given version.
Bandwidth-efficient delta syncing. Git's native wire protocol (git-upload-pack / git-receive-pack) computes deltas on the fly. Agents only transfer the bytes that actually changed over the network, cutting down cloud egress costs.

6. CLI toolchain integration

Because snapshots reside in standard Git repositories, gitcrawl works directly with standard terminal tools:

Fuzzy history inspection with approx:
bash git log --name-only --format="" | sort -u | approx "stripe charges"
Tracking keyword changes:
bash git log -p -S "deprecated" -- docs.github.com/
Direct input for LLMs and RAG pipelines:
Because the repository stores structured Markdown, you can feed local LLMs directly using cat or Bash pipes.

Source code, build instructions, and configuration options are available on GitHub: github.com/riccivr/gitcrawl.

[<] Volver al Blog [^] Arriba