--sync vs --incremental: Understanding the Differences and When to Use Each

If you only remember one thing about --sync and --incremental, make it this: both modes use the same state file and the same changed-page detection. The real difference is what happens when a page disappears from Confluence.

That sounds small, but it changes the meaning of the whole output directory.

The short version

The official docs summarize the difference cleanly:

The docs also note that --incremental is the observed default on the documented release. You do not need to pass it explicitly unless you want the behavior to be obvious in scripts and runbooks.

How the state file works

When you run space convert with either mode, acs2md:

1. reads .convert-sync-state.json from the output directory
2. fetches metadata for the pages in the space
3. compares page versions against what the state file recorded earlier
4. skips unchanged pages and re-converts changed ones
5. rewrites internal links if link rewriting is enabled
6. updates the state file with the new state

That is why later runs can be dramatically cheaper than the first one.

When sync is the right decision

Use --sync when the local directory should behave like a live mirror:

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

This is the right choice when:

• a continuity copy should reflect the current state of the source space
• a downstream system expects stale local files to disappear
• a static site publish step should not keep pages that no longer exist upstream
• disaster recovery procedures depend on an accurate current mirror

If a page is deleted in Confluence, --sync deletes the corresponding Markdown file and removes it from the state file. The summary will report Deleted: N.

When incremental is the safer decision

Use --incremental when preservation matters more than exact mirroring:

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

This is the better fit for:

• archive-first exports
• compliance and audit retention
• historical documentation sets that must survive upstream deletions
• RAG or search corpora that should never lose already exported content by accident

If a page is deleted in Confluence, --incremental keeps the local Markdown file on disk and only removes the tracking entry. The summary reports Removed from tracking: N.

A useful decision rule

Ask one question before choosing a mode:

Should the local directory represent the current live state of the space, or should it preserve documentation even after the source changes?

• Current live state: choose --sync
• Preservation after deletion: choose --incremental

That is the whole decision. Do not make it harder than it is.

Common mistakes to avoid

The docs call out several details worth making explicit:

• --sync and --incremental are mutually exclusive
• --conflict-resolution=versioned disables sync and incremental behavior because the timestamped directory is not a stable place for the state file
• changing output directories between runs resets the practical value of state tracking
• link rewriting runs after successful conversion when it is enabled

In other words, state-tracked exports want a stable directory and a clear lifecycle.

Example choices by use case

That mapping is consistent across the customer docs and the guided workflows.

The compliance question hiding inside the mode choice

--sync and --incremental look like an operational decision. They are also a records-management decision under most modern frameworks.

• ISO/IEC 27001:2022 A.5.33 (protection of records) asks you to define how records are retained, protected, and disposed of. --incremental is the natural fit for records that must survive upstream deletion. --sync is appropriate when the local copy is a live mirror, not a record.
• NIS 2 Article 21 and the related implementing guidance expect operators of essential and important entities to keep evidence of incidents, configurations, and decisions for the duration required by national authorities. If the documentation is part of that evidence, --incremental is usually the correct mode.
• SOC 2 Common Criteria CC7.4 (incident response) assumes you can reconstruct what the system looked like during an incident. Deleting Markdown files because the source page was removed in Confluence can erase exactly the artifact CC7.4 expects you to retain.
• GDPR Article 5(1)(e) (storage limitation) points the other direction. Personal data should not live in a continuity copy longer than the lawful purpose requires. If a Confluence page contained personal data and was deleted for that reason, --sync is the safer mode for that estate.

In other words, the right mode depends on whether the directory is functioning as a mirror (where deletions should propagate) or as a record (where deletions should be preserved as evidence). Different spaces in the same organization may need different modes for the same reason.

Final recommendation

Choose --sync when local deletion is a feature. Choose --incremental when local retention is a feature.

Both modes give you changed-only refreshes through .convert-sync-state.json. The only question is whether removed Confluence pages should vanish from disk or remain as exported evidence. Decide that once, document it in the runbook, and your later runs become much easier to reason about.