Sync e Incremental

acs2md mantiene un archivo de estado local llamado .convert-sync-state.json en el directorio de salida cuando usas space convert con --sync o --incremental. Esto hace que las exportaciones masivas sean eficientes al reconvertir solo las páginas cuyo contenido ha cambiado desde la ultima ejecución.

Ambos modos usan el mismo archivo de estado y el mismo mecanismo de deteccion de cambios. La unica diferencia es lo que ocurre cuando una página se elimina de Confluence.

Resumen

Como funciona el archivo de estado

Cuando ejecutas space convert con cualquiera de los dos flags, acs2md:

1. Lee .convert-sync-state.json del directorio de salida
2. Obtiene metadatos de todas las páginas del espacio para detectar cambios de forma eficiente
3. Compara la versión de cada página con la versión registrada en el archivo de estado
4. Salta las páginas que no han cambiado, descarga y reconvierte las que si
5. Reescribe los enlaces internos despues de la conversion cuando la reescritura de enlaces esta activada
6. Actualiza el archivo de estado con la nueva información de versión

Primera ejecución con --sync

acs2md space convert by-key DEVOPS --sync

📚 Converting space: DevOps (DEVOPS)
📂 Output directory: output/DEVOPS

🔄 Mode: sync — state file: output/DEVOPS/.convert-sync-state.json

🔍 Fetching page metadata for sync...
  📥 Fetched metadata for 100 pages...
  📥 Fetched metadata for 199 pages ✅

📋 Found 199 page(s) to convert (0 up-to-date)


✅ Sync complete!
  ✅ Converted: 199
  ❌ Failed: 0
  ✅ Up-to-date (skipped): 0
  🗑️  Deleted: 0
  🔗 Links rewritten: 39 files
  📂 Output: output/DEVOPS

Segunda ejecución (sin cambios)

acs2md space convert by-key DEVOPS --sync

📚 Converting space: DevOps (DEVOPS)
📂 Output directory: output/DEVOPS

🔄 Mode: sync — state file: output/DEVOPS/.convert-sync-state.json

🔍 Fetching page metadata for sync...
  📥 Fetched metadata for 100 pages...
  📥 Fetched metadata for 199 pages ✅

✅ All pages are up-to-date.

✅ Sync complete!
  ✅ Up-to-date (skipped): 199
  🗑️  Deleted: 0
  📂 Output: output/DEVOPS

Las 199 páginas se saltan. No se descarga ni reconvierte ningun contenido. Solo se comprueban los metadatos.

Modo --sync

--sync es el modo de mantenimiento masivo disenado para espejos activos y copias de continuidad.

• Almacena datos de seguimiento en .convert-sync-state.json en el directorio de salida
• Obtiene metadatos primero para detectar cambios de forma eficiente
• Descarga y reconvierte solo las páginas cuyas versiones han cambiado
• Elimina archivos locales de páginas borradas en Confluence
• Reescribe enlaces internos despues de la conversion cuando la reescritura de enlaces esta activada

Cuando una página se elimina

Si una página se borra en Confluence, --sync elimina el archivo .md correspondiente del directorio de salida y borra la entrada del archivo de estado. La linea de resumen muestra Deleted: N.

Cuando usar --sync

• Mantener una copia de continuidad gobernada de un espacio de documentación completo
• Alimentar un sistema que espera un espejo limpio del espacio
• Exportaciones programadas donde archivos obsoletos causarian problemas
• Archivos de recuperación ante desastres que deben reflejar el estado actual de Confluence

Ejemplo

acs2md space convert by-key DOCS \
  --output-dir ./continuity/docs \
  --sync

Modo --incremental

--incremental es el modo predeterminado, disenado para flujos de trabajo orientados a archivo y retencion conservadora.

• Usa el mismo mecanismo .convert-sync-state.json que --sync
• Descarga y reconvierte solo las páginas que han cambiado
• Mantiene los archivos locales incluso si las páginas se eliminan de Confluence
• Funciona bien cuando el directorio de exportación es también un archivo historico

Primera ejecución con --incremental

acs2md space convert by-key DEVOPS --incremental

📚 Converting space: DevOps (DEVOPS)
📂 Output directory: output/DEVOPS

🔄 Mode: incremental — state file: output/DEVOPS/.convert-sync-state.json

🔍 Fetching page metadata for sync...
  📥 Fetched metadata for 100 pages...
  📥 Fetched metadata for 199 pages ✅

📋 Found 199 page(s) to convert (0 up-to-date)


✅ Sync complete!
  ✅ Converted: 199
  ❌ Failed: 0
  ✅ Up-to-date (skipped): 0
  🗑️  Removed from tracking: 0
  🔗 Links rewritten: 39 files
  📂 Output: output/DEVOPS

Cuando una página se elimina

Si una página se borra en Confluence, --incremental mantiene el archivo .md local en disco. La entrada se elimina del seguimiento en el archivo de estado, pero el Markdown exportado se conserva. La linea de resumen muestra Removed from tracking: N en lugar de Deleted: N.

Cuando usar --incremental

• Archivos de cumplimiento y auditoria a nivel de espacio que deben retener todo el contenido exportado
• Flujos de trabajo de retencion legal donde la eliminacion de evidencia no es aceptable
• Copias historicas de documentación que deben sobrevivir a eliminaciones en el origen
• Construir un corpus que crece con el tiempo y nunca pierde documentos

Ejemplo

acs2md space convert by-key DOCS \
  --output-dir ./archive/docs \
  --incremental

Exclusividad mutua

--sync e --incremental son mutuamente excluyentes. No puedes usar ambos en el mismo comando.

# ✅ Valido
acs2md space convert by-key DOCS --sync
 
# ✅ Valido (predeterminado, igual que omitir el flag)
acs2md space convert by-key DOCS --incremental
 
# ❌ Invalido — mutuamente excluyentes
acs2md space convert by-key DOCS --sync --incremental

Estructura de salida con archivo de estado

Una exportación tipica de espacio con sync o incremental tiene este aspecto:

./output/DOCS/
├── .convert-sync-state.json
├── Home.md
├── Architecture/
│   ├── Architecture.md
│   └── Deployment.md
├── Operations/
│   ├── Runbooks.md
│   └── Disaster_Recovery.md
└── Security/
    ├── Controls.md
    └── Audit_Evidence.md

El archivo .convert-sync-state.json se ubica en la raiz del directorio de salida y rastrea todas las páginas del espacio.

Elegir el modo adecuado