initial commit

Signed-off-by: ale <ale@manalejandro.com>
2025-10-31 00:29:18 +01:00
commit 5e520b42df
--- a/README.md
+++ b/README.md
@@ -0,0 +1,300 @@
+# topdir.sh
+
+Script en bash que compara recursivamente un directorio y genera informes de archivos nuevos, modificados y eliminados desde la última ejecución.
+
+## Características
+
+- 🔍 **Detección de cambios**: Identifica archivos nuevos, modificados y eliminados
+- 🔐 **Múltiples algoritmos de hash**: SHA256 (default), SHA1, MD5
+- 📊 **Formatos de salida**: Text (humano), JSON (programático), CSV (hoja de cálculo)
+- 🚫 **Sistema de exclusiones**: Excluye archivos/directorios por patrón o archivo `.topdirignore`
+- 💾 **Snapshot personalizable**: Ubicación configurable del archivo de estado
+- ⚡ **Portable**: Bash estándar con utilidades comunes (find, sed, awk)
+
+## Instalación
+
+```bash
+chmod +x topdir.sh
+# Opcionalmente, mover a un directorio en tu PATH
+sudo cp topdir.sh /usr/local/bin/topdir
+```
+
+## Uso básico
+
+```bash
+# Monitorear directorio actual
+./topdir.sh
+
+# Monitorear directorio específico
+./topdir.sh /path/to/directory
+
+# Ver ayuda completa
+./topdir.sh --help
+```
+
+### Primera ejecución
+La primera vez que ejecutas el script en un directorio, crea un archivo `.topdir_snapshot` con el estado inicial:
+
+```bash
+$ ./topdir.sh /data
+Snapshot creado en './.topdir_snapshot' (no había ejecución previa).
+```
+
+### Ejecuciones posteriores
+Las siguientes ejecuciones comparan contra el snapshot y muestran cambios:
+
+```bash
+$ ./topdir.sh /data
+Informe de comparación para: /data
+
+Nuevos archivos (2):
+  ./report.pdf
+  ./images/photo.jpg
+
+Archivos modificados (1):
+  ./config.txt
+
+Archivos eliminados desde último snapshot (1):
+  ./temp.log
+```
+
+## Opciones avanzadas
+
+### Algoritmos de hash
+
+Elige entre SHA256 (default), SHA1 o MD5:
+
+```bash
+# Usar MD5 (más rápido para archivos grandes)
+./topdir.sh --hash md5 /data
+
+# Usar SHA1
+./topdir.sh --hash sha1 /data
+```
+
+### Formatos de salida
+
+#### Formato Text (default)
+Salida legible para humanos:
+
+```bash
+./topdir.sh /data
+```
+
+#### Formato JSON
+Para procesamiento programático:
+
+```bash
+./topdir.sh --format json /data
+```
+
+Salida:
+```json
+{
+  "status": "ok",
+  "directory": "/data",
+  "hash": "sha256",
+  "new": ["./file1.txt", "./file2.txt"],
+  "modified": ["./config.json"],
+  "deleted": ["./old.log"]
+}
+```
+
+#### Formato CSV
+Para análisis en hojas de cálculo:
+
+```bash
+./topdir.sh --format csv /data
+```
+
+Salida:
+```csv
+status,path
+new,"./file1.txt"
+new,"./file2.txt"
+modified,"./config.json"
+deleted,"./old.log"
+```
+
+### Exclusiones de archivos
+
+#### Opción --exclude
+
+Excluye patrones específicos (puede repetirse):
+
+```bash
+# Excluir logs y temporales
+./topdir.sh --exclude "*.log" --exclude "*.tmp" /data
+
+# Excluir directorios completos
+./topdir.sh --exclude "node_modules/*" --exclude ".git/*" /project
+```
+
+#### Archivo .topdirignore
+
+Crea un archivo `.topdirignore` en el directorio monitoreado con patrones (similar a `.gitignore`):
+
+```bash
+# .topdirignore
+*.log
+*.tmp
+node_modules/*
+.git/*
+__pycache__/*
+*.pyc
+```
+
+Luego ejecuta normalmente:
+
+```bash
+./topdir.sh /project
+# Lee automáticamente .topdirignore
+```
+
+#### Archivo de exclusión personalizado
+
+```bash
+./topdir.sh --ignore-file /path/to/custom.ignore /data
+```
+
+### Snapshot personalizado
+
+Por defecto, el snapshot se guarda como `.topdir_snapshot` dentro del directorio monitoreado. Puedes especificar una ubicación diferente:
+
+```bash
+# Snapshot en /tmp
+./topdir.sh --snapshot-file /tmp/data.snapshot /data
+
+# Snapshot en directorio home
+./topdir.sh --snapshot-file ~/snapshots/project.snap /project
+```
+
+Útil para:
+- Monitorear directorios de solo lectura
+- Mantener múltiples snapshots del mismo directorio
+- Guardar snapshots en almacenamiento centralizado
+
+## Ejemplos completos
+
+### Monitoreo de proyecto de desarrollo
+
+```bash
+# Primera ejecución - crear snapshot con MD5 y excluir archivos de build
+./topdir.sh --hash md5 \
+  --exclude "node_modules/*" \
+  --exclude "dist/*" \
+  --exclude "*.log" \
+  /home/user/myproject
+
+# Después de trabajar, verificar cambios en JSON
+./topdir.sh --hash md5 \
+  --format json \
+  --exclude "node_modules/*" \
+  --exclude "dist/*" \
+  --exclude "*.log" \
+  /home/user/myproject | jq .
+```
+
+### Monitoreo de directorio de datos
+
+```bash
+# Snapshot en ubicación centralizada, salida CSV
+./topdir.sh --snapshot-file /var/snapshots/data.snap \
+  --format csv \
+  --exclude "*.tmp" \
+  /data > changes.csv
+```
+
+### Integración con cron
+
+```bash
+# Agregar a crontab para chequeo diario
+# 0 3 * * * /usr/local/bin/topdir --format json --snapshot-file /var/snapshots/backup.snap /backup > /var/log/topdir.json 2>&1
+```
+
+### Comparar con snapshot anterior sin actualizar
+
+Si quieres ver cambios sin actualizar el snapshot:
+
+```bash
+# Hacer backup del snapshot
+cp /data/.topdir_snapshot /tmp/snapshot.bak
+
+# Ejecutar topdir (actualiza el snapshot)
+./topdir.sh /data
+
+# Restaurar snapshot original
+mv /tmp/snapshot.bak /data/.topdir_snapshot
+```
+
+## Notas técnicas
+
+### Rendimiento
+
+- **SHA256**: Más seguro, recomendado para verificación de integridad (default)
+- **SHA1**: Balance entre velocidad y seguridad
+- **MD5**: Más rápido, adecuado para detección de cambios en archivos grandes (no para seguridad)
+
+### Limitaciones
+
+- Los archivos con nombres que contienen saltos de línea pueden no procesarse correctamente
+- El script no sigue enlaces simbólicos (por diseño)
+- Requiere bash >= 3.2 y utilidades estándar (find, sed, awk, sha256sum/sha1sum/md5sum)
+
+### Archivos excluidos automáticamente
+
+El script siempre excluye:
+- `.topdir_snapshot` (archivo de estado)
+- `.topdirignore` (archivo de configuración de exclusiones)
+
+### Formato del snapshot
+
+El snapshot es un archivo de texto con formato:
+```
+<path><TAB><hash>
+```
+
+Ejemplo:
+```
+./file1.txt	e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
+./file2.txt	d4735e3a265e16eee03f59718b9b5d03019c07d8b6c51f90da3a666eec13ab35
+```
+
+## Solución de problemas
+
+### "Command not found: sha256sum"
+
+En macOS, instala `coreutils`:
+```bash
+brew install coreutils
+```
+
+O usa SHA1/MD5 que vienen preinstalados:
+```bash
+./topdir.sh --hash sha1 /data
+```
+
+### "Snapshot file not found" en ejecuciones posteriores
+
+Asegúrate de usar la misma opción `--snapshot-file` en todas las ejecuciones:
+```bash
+# Primera ejecución
+./topdir.sh --snapshot-file /tmp/my.snap /data
+
+# Ejecuciones posteriores - debe usar el mismo snapshot
+./topdir.sh --snapshot-file /tmp/my.snap /data
+```
+
+### Archivos no se detectan como modificados
+
+- Verifica que no estén excluidos por `.topdirignore` o `--exclude`
+- Confirma que el contenido cambió (el script usa hash, no mtime)
+- Verifica que usas el mismo algoritmo de hash (`--hash`)
+
+## Licencia
+
+Dominio público / MIT - Usa como quieras.
+
+## Autor
+
+Creado para monitoreo sencillo de cambios en directorios sin dependencias pesadas.