# Two-way folder sync

A folder on Share can stay in step with a folder of Markdown on disk. New notes, edits, renames, and moves go both ways. Deletes only happen if you ask.

## The index

Sync does not download every note to find out what changed. One request is the snapshot:

```http
GET /api/v1/documents?view=index&folder=Work
```

You get each note's id, path, and content hash, plus tombstones for notes that were deleted. Only a tombstone means deleted. An id you knew about that is missing from both lists was moved to another folder. It is still on Share.

New local files go up in batches, up to 200 at a time. Edits use `PATCH` with `If-Match` and the last hash you saw. If the note changed on Share since then, you get a 409 instead of a silent overwrite. Notes that are new or changed on Share come down with `GET /documents/:id`.

Imports store the Markdown immediately and render HTML in the background. Open a note before that job runs and it renders on the spot.

## The example client

`script/share_sync` in the Marked Share repo is a single Ruby file, standard library only, that does the whole loop:

- Push new and edited local files
- Pull edits and new notes from Share
- Follow renames and moves
- Keep the Share version when both sides changed, and upload your local edits as a new note titled "(conflicted)"
- Delete in either direction only with `--delete`, and never throw away local edits that have not synced yet

```bash
export MARKED_SHARE_TOKEN="your-token"
export MARKED_SHARE_DEVICE_KEY="your-device-key"

./script/share_sync sync ~/Notes/Work --folder "Work" --dry-run --verbose
./script/share_sync sync ~/Notes/Work --folder "Work"
```

Point it at a locked folder if the notes are personal. Create the folder, lock it, then sync into it. A locked folder rejects a public upload, including one from a sync client.

Limits for now: 200 notes per import request, 500 KB per note, and 5,000 notes in one synced folder. Past that, split them across folders. Empty folders are not synced. If a move leaves an empty directory on disk, remove it yourself.

The [API docs](https://share.markedapp.com/docs/api) have the endpoints. The script is the walkthrough.