--sync vs --incremental: diferencias y cuando usar cada modo

Si solo vas a recordar una cosa sobre --sync y --incremental, que sea esta: ambos usan el mismo state file y el mismo mecanismo de deteccion de cambios. La diferencia real es lo que ocurre cuando una pagina desaparece de Confluence.

Suena pequeno, pero cambia por completo el significado del directorio de salida.

La version corta

La documentacion oficial resume la diferencia de forma bastante limpia:

La documentacion tambien indica que --incremental es el comportamiento por defecto en la release documentada. No hace falta pasarlo de forma explicita salvo que quieras dejar la intencion clarisima en scripts y runbooks.

Como funciona el state file

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

1. lee .convert-sync-state.json del directorio de salida
2. obtiene metadatos de las paginas del espacio
3. compara versiones de pagina con lo registrado anteriormente
4. omite paginas sin cambios y reconvierte las que cambiaron
5. reescribe enlaces internos si esa opcion esta activa
6. actualiza el state file con el nuevo estado

Por eso las siguientes ejecuciones pueden ser mucho mas baratas que la primera.

Cuando sync es la decision correcta

Usa --sync cuando el directorio local deba comportarse como un espejo vivo:

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

Es la opcion correcta cuando:

• una copia de continuidad debe reflejar el estado actual del espacio fuente
• un sistema aguas abajo espera que los archivos obsoletos desaparezcan
• un publish hacia sitio estatico no debe conservar paginas que ya no existen arriba
• un procedimiento de recuperacion depende de un espejo actualizado

Si una pagina se elimina en Confluence, --sync borra el archivo Markdown correspondiente y limpia su entrada del state file. El resumen mostrara Deleted: N.

Cuando incremental es la opcion mas segura

Usa --incremental cuando la preservacion importe mas que el espejo exacto:

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

Encaja mejor en:

• exportaciones orientadas a archivo
• retencion para cumplimiento y auditoria
• conjuntos historicos que deben sobrevivir a borrados aguas arriba
• corpus para RAG o busqueda que no deberian perder contenido ya exportado por accidente

Si una pagina se elimina en Confluence, --incremental conserva el archivo Markdown local y solo retira la entrada de seguimiento. El resumen mostrara Removed from tracking: N.

Una regla de decision util

Hazte una sola pregunta antes de elegir modo:

El directorio local debe representar el estado actual del espacio, o debe preservar documentacion aunque el origen cambie?

• Estado actual del origen: elige --sync
• Preservacion tras borrados: elige --incremental

Esa es toda la decision. No hace falta complicarla mas.

Errores comunes que conviene evitar

La documentacion subraya varios detalles que merece la pena explicitar:

• --sync y --incremental son mutuamente excluyentes
• --conflict-resolution=versioned desactiva el comportamiento sync/incremental porque un directorio con timestamp no es una ubicacion estable para el state file
• cambiar el directorio de salida entre ejecuciones reinicia en la practica el valor del seguimiento de estado
• la reescritura de enlaces corre despues de una conversion correcta cuando esta activada

Dicho de otra forma: las exportaciones con estado necesitan un directorio estable y un ciclo de vida claro.

Ejemplos segun caso de uso

Ese mapeo es consistente entre la documentacion de producto y las recetas guiadas.

La pregunta de cumplimiento que se esconde en la eleccion de modo

--sync y --incremental parecen una decision operativa. Tambien son una decision de gestion de registros bajo la mayoria de los marcos modernos.

• ISO/IEC 27001:2022 A.5.33 (proteccion de registros) te pide definir como se retienen, protegen y eliminan los registros. --incremental encaja con registros que deben sobrevivir a borrados aguas arriba. --sync es apropiado cuando la copia local es un espejo vivo, no un registro.
• NIS 2 Articulo 21 y la guia de transposicion esperan que los operadores de servicios esenciales e importantes conserven evidencia de incidentes, configuraciones y decisiones durante el plazo que indique la autoridad nacional. Si la documentacion forma parte de esa evidencia, --incremental suele ser el modo correcto.
• SOC 2 Common Criteria CC7.4 (respuesta a incidentes) asume que puedes reconstruir como estaba el sistema durante un incidente. Borrar archivos Markdown porque la pagina origen se quito de Confluence puede eliminar justo el artefacto que CC7.4 espera que conserves.
• RGPD Articulo 5(1)(e) (limitacion del plazo de conservacion) apunta en sentido contrario. Los datos personales no deberian permanecer en una copia de continuidad mas alla de lo necesario para la finalidad lawful. Si una pagina de Confluence contenia datos personales y se elimino por ese motivo, --sync es el modo mas seguro para ese patrimonio.

En resumen: el modo correcto depende de si el directorio funciona como espejo (donde los borrados deben propagarse) o como registro (donde los borrados deben preservarse como evidencia). Distintos espacios de la misma organizacion pueden necesitar modos distintos por esa misma razon.

Recomendacion final

Elige --sync cuando el borrado local sea una caracteristica deseable. Elige --incremental cuando la retencion local sea la caracteristica deseable.

Ambos modos te dan refrescos solo sobre cambios gracias a .convert-sync-state.json. La unica pregunta importante es si las paginas eliminadas en Confluence deben desaparecer del disco o permanecer como evidencia exportada. Decide eso una vez, documentalo en el runbook y las siguientes ejecuciones seran mucho mas faciles de razonar.