Archivar la web con Git: construyendo un crawler e indexador histórico

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

Actualización: El prototipo descrito en este artículo ya es una realidad y está disponible en código abierto como gitcrawl. Puedes leer el desglose técnico, benchmarks y especificaciones de arquitectura completas en: gitcrawl: crawler web direccionable por contenido y motor de snapshots en Git.

Las páginas web mutan y desaparecen a cada rato. Las empresas borran documentación durante rediseños corporativos, los términos de servicio cambian sin avisar y los links se rompen de la nada.

La Wayback Machine de Internet Archive es una nota para ver páginas en el navegador, pero no está hecha para correr diffs rápidos en local, meterle grep o armar scripts en la terminal.

He estado probando una jugada distinta: crawlear páginas web y guardar todo el historial directamente dentro de repositorios Git.

Aquí te muestro cómo funciona Git como motor de almacenamiento para archivar la web y lo que aprendí armando un prototipo.

1. Por qué Git funciona brutal como backend de almacenamiento

En el fondo, Git es un almacén de objetos direccionable por contenido estructurado como un grafo acíclico dirigido. Está pensado para rastrear cambios en archivos de texto ocupando el menor espacio posible en disco.

Pipeline del crawler
Descarga URL -> Sanitización DOM -> Normalización a Markdown
                       │
                       ▼ Commit atómico
Almacén de objetos Git (.git/objects)
Commit (Autor, Timestamp, Hash del árbol)
  └── Tree (ejemplo.com/docs/)
        ├── Blob (index.md) -> Compresión delta
        ├── Blob (metadata.json)
        └── Blob (assets/hero.webp) -> Deduplicado por SHA

Ventajas clave:

Deduplicación por contenido. Git indexa cada archivo por su hash criptográfico. Si 500 páginas crawleadas usan el mismo CSS o la misma foto, Git guarda ese blob una sola vez y listo.
Compresión delta en packfiles. Cuando una página de documentación cambia una sola línea, los packfiles de Git (git pack-objects) guardan solo la diferencia en bytes. Crawlear un sitio cientos de veces no te va a reventar el disco duplicando el HTML entero.
Herramientas estándar de Git. Tienes acceso inmediato a comandos nativos:
- git diff v1..v2 -- ruta/a/pagina.md te muestra los cambios exactos en la terminal.
- git log -p -S "parametro_deprecado" encuentra el commit exacto donde se agregó o borró una palabra en todo el historial.
- git bisect corre pruebas automáticas sobre los snapshots para encontrar cuándo un sitio externo rompió una API.

2. Ingesta y reducción de ruido

El reto más bravo al meter HTML en Git es el ruido dinámico.

Si haces commit del HTML crudo que devuelve el servidor, cada corrida te va a generar diffs falsos por tokens CSRF, cookies de sesión, banners con fechas y bloques de publicidad aleatorios.

Respuesta HTTP en crudo
       │
       ▼
[ Stream de descarga ]
       │
       ▼
[ Sanitizador de DOM ] ──> Quita scripts, pixeles de rastreo y atributos locos
       │
       ▼
[ Parser de streams ]  ──> Convierte el DOM limpio en Markdown normalizado
       │
       ▼
[ Plomería de Git ]    ──> Escribe el commit directo en .git/objects

Esquema de almacenamiento en dos archivos:

Para tener diffs limpios sin perder la respuesta original, cada captura guarda dos archivos:

archive/
  └── example.com/
        └── api/
              └── v1/
                    ├── index.md        <-- Markdown limpio para git diff
                    ├── index.html.gz   <-- HTML original comprimido intacto
                    └── metadata.json   <-- Cabeceras HTTP, status code, IP, fecha

index.md genera diffs limpiecitos en la terminal con tablas, code fences y listas.
metadata.json guarda cabeceras HTTP, cadenas de redirección y hashes de certificados TLS.

3. Fragmentación de carpetas

Guardar miles de URLs en una sola carpeta colapsa el rendimiento del sistema de archivos.

Dividir la URL en subcarpetas mantiene los directorios ordenados y volando:

https://docs.kernel.org/process/submitting-patches.html
  └── docs.kernel.org/
        └── process/
              └── submitting-patches/
                    ├── index.md
                    └── metadata.json

Los query parameters se ordenan alfabéticamente y se guardan en carpetas dedicadas. Los caracteres prohibidos en POSIX y Windows (:, *, ?, ", <, >, |) se escapan con hashes seguros.

4. Escribir directo a objetos para meterle chola

Comandos como git add y git checkout tocan el disco para cada archivo en el directorio de trabajo. En repositorios gigantes con miles de páginas, el disco se vuelve un dolor de cabeza.

Para una ingesta rápida, te saltas el directorio de trabajo por completo y escribes los objetos directo a .git/objects usando comandos de plomería de Git o bindings en C:

1. Escribir Blob:    git hash-object -w <contenido>     -> Hash del Blob
2. Armar Árbol:      git mktree <definicion_arbol>      -> Hash del Árbol
3. Crear Commit:     git commit-tree <hash_arbol> -p HEAD -> Hash del Commit
4. Actualizar Rama:  git update-ref refs/heads/main <hash_commit>

Esto procesa los commits en memoria a millón. Ejecutar git gc --prune=now cada cierto tiempo mantiene los packfiles comprimidos al máximo.

5. Del prototipo a `gitcrawl`

La herramienta CLI standalone basada en esta estructura ya está publicada:

Un motor central en C99 para descargas HTTP en streaming y sanitización sin dependencias externas: gitcrawl.
Un parser de streams basado en la lógica de conversión a Markdown de unipaste.
Búsqueda rápida con approx para encontrar páginas en el historial usando coincidencia difusa directo desde la shell.

Revisa el artículo completo con especificaciones, benchmarks de compresión y casos de uso en el post de lanzamiento: gitcrawl: crawler web direccionable por contenido y motor de snapshots en Git.

Archiving the web with Git: building a content-addressable crawler

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

Update: The concepts explored in this post are now implemented and available as an open-source project: gitcrawl. Read the full technical writeup, benchmarks, and architecture specifications in: gitcrawl: Content-Addressable Web Archiver and Snapshot Engine Backed by Git.

Web pages disappear all the time. Companies delete docs during rebrands, terms of service change without changelogs, and links rot.

The Wayback Machine is great for visual browsing, but it is not built for running fast local diffs, grep queries, or UNIX shell scripts.

I have been testing a different approach: crawling web pages and committing their history straight into Git repositories.

Here is how Git works as a storage backend for web archival and what I found while building a prototype.

1. Why Git works as a storage backend

Git is a content-addressable object store structured as a directed acyclic graph. It is built to track text changes over time with minimal disk space.

Crawler pipeline
URL fetch -> DOM sanitization -> Markdown normalization
                       │
                       ▼ Atomic commit
Git object store (.git/objects)
Commit (Author, Timestamp, Tree SHA)
  └── Tree (example.com/docs/)
        ├── Blob (index.md) -> Delta compressed
        ├── Blob (metadata.json)
        └── Blob (assets/hero.webp) -> SHA deduplicated

Useful properties:

Content deduplication. Git indexes every file by its cryptographic hash. If 500 crawled pages use the same CSS file or logo, Git stores that blob once.
Delta compression in packfiles. When a documentation page changes by a single line, Git packfiles (git pack-objects) store only the byte delta. Crawling a site hundreds of times does not duplicate the entire HTML body every run.
Standard CLI tools. You get immediate access to built-in Git commands:
- git diff v1..v2 -- path/to/page.md shows exact text changes in your terminal.
- git log -p -S "deprecated_param" finds the exact commit where a phrase was added or removed.
- git bisect runs automated tests across snapshots to find when an external site introduced a breaking change.

2. Ingestion and noise reduction

The main problem with archiving raw HTML into Git is non-deterministic noise.

If you commit raw HTML from a browser request, every run creates fake diffs from CSRF tokens, session cookies, timestamp banners, and randomized ad containers.

Raw HTTP response
       │
       ▼
[ Fetch stream ]
       │
       ▼
[ DOM sanitizer ] ──> Strip scripts, tracking pixels, volatile attributes
       │
       ▼
[ Stream parser ] ──> Convert clean DOM into normalized Markdown
       │
       ▼
[ Git plumbing ]  ──> Write tree and commit directly to .git/objects

Two-tier file layout:

To keep diffs clean while preserving original payloads, each snapshot writes two files:

archive/
  └── example.com/
        └── api/
              └── v1/
                    ├── index.md        <-- Clean Markdown for git diff
                    ├── index.html.gz   <-- Compressed original HTML payload
                    └── metadata.json   <-- HTTP headers, status code, IP, timestamp

index.md produces readable terminal diffs for prose, tables, and code fences.
metadata.json stores headers, redirect chains, and TLS cert hashes.

3. Directory sharding

Storing tens of thousands of URLs in a single flat folder hurts filesystem inode performance.

Decomposing the URL into directory shards keeps directories manageable:

https://docs.kernel.org/process/submitting-patches.html
  └── docs.kernel.org/
        └── process/
              └── submitting-patches/
                    ├── index.md
                    └── metadata.json

Query parameters are sorted alphabetically and saved under dedicated subfolders. Reserved characters on POSIX and Windows (:, *, ?, ", <, >, |) are escaped with hex hashes.

4. Bypassing the working tree for speed

Standard commands like git add and git checkout write every file to disk. On large crawls with thousands of pages, disk I/O becomes the bottleneck.

For fast ingestion, you can skip the working directory and write objects straight into .git/objects using Git plumbing commands or C bindings:

1. Write Blob:   git hash-object -w <payload>       -> Blob SHA
2. Make Tree:    git mktree <tree_definition>       -> Tree SHA
3. Make Commit:  git commit-tree <tree_sha> -p HEAD -> Commit SHA
4. Update Ref:   git update-ref refs/heads/main <commit_sha>

This keeps commits in memory and takes milliseconds instead of seconds per batch. Running git gc --prune=now periodically compresses the packfiles.

5. From prototype to `gitcrawl`

The standalone CLI tool based on this architecture is now live:

A core C99 engine for streaming HTTP fetches and DOM sanitization with zero dependencies: gitcrawl.
A stream parser based on the Markdown conversion engine from unipaste.
Fast terminal history search using fuzzy matching with approx.

Check out the full technical writeup, compression benchmarks, and usage patterns in the launch post: gitcrawl: Content-Addressable Web Archiver and Snapshot Engine Backed by Git.