Sync and Incremental

acs2md maintains a local state file named .convert-sync-state.json in the output directory when you use space convert with --sync or --incremental. This makes bulk exports efficient by only re-converting pages whose content has changed since the last run.

Both modes use the same state file and the same change-detection mechanism. The only difference is what happens when a page is removed from Confluence.

At a glance

How the state file works

When you run space convert with either flag, acs2md:

1. Reads .convert-sync-state.json from the output directory
2. Fetches metadata for all pages in the space to detect changes efficiently
3. Compares each page version against the version recorded in the state file
4. Skips pages that have not changed, downloads and re-converts pages that have
5. Rewrites internal links after conversion when link rewriting is enabled
6. Updates the state file with the new version information

First run with --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

Second run (nothing changed)

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

All 199 pages are skipped. No page content is downloaded or re-converted. Only the metadata is checked.

--sync mode

--sync is the bulk-maintenance mode designed for live mirrors and continuity copies.

• Stores tracking data in .convert-sync-state.json in the output directory
• Fetches metadata first to detect changes efficiently
• Downloads and re-converts only pages whose versions changed
• Removes local files for pages deleted from Confluence
• Rewrites internal links after conversion when link rewriting is enabled

When a page is removed

If a page is deleted in Confluence, --sync deletes the corresponding .md file from the output directory and removes the entry from the state file. The summary line shows Deleted: N.

When to use --sync

• Maintain a governed continuity copy of a full documentation space
• Feed a downstream system that expects a clean mirror of the space
• Scheduled exports where stale files would cause problems
• Disaster recovery archives that must reflect the current Confluence state

Example

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

--incremental mode

--incremental is the default mode, designed for archive-oriented and conservative retention workflows.

• Uses the same .convert-sync-state.json mechanism as --sync
• Downloads and re-converts only changed pages
• Keeps local files even if pages were removed from Confluence
• Works well when the export directory is also a historical archive

First run with --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

When a page is removed

If a page is deleted in Confluence, --incremental keeps the local .md file on disk. The entry is removed from the state file tracking, but the exported Markdown is preserved. The summary line shows Removed from tracking: N instead of Deleted: N.

When to use --incremental

• Space-wide compliance and audit archives that must retain all exported content
• Legal hold workflows where deletion of evidence is not acceptable
• Historical documentation snapshots that must survive upstream deletions
• Building a corpus that grows over time and never loses documents

Example

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

Mutual exclusivity

--sync and --incremental are mutually exclusive. You cannot use both in the same command.

# ✅ Valid
acs2md space convert by-key DOCS --sync
 
# ✅ Valid (default, same as omitting the flag)
acs2md space convert by-key DOCS --incremental
 
# ❌ Invalid — mutually exclusive
acs2md space convert by-key DOCS --sync --incremental

Output structure with state file

A typical space export with sync or incremental looks like this:

./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

The .convert-sync-state.json file lives at the root of the output directory and tracks all pages in the space.

Choosing the right mode