sync_directory
Synchronize a local folder with an Overleaf project by uploading new or changed files and, in mirror mode, deleting project-only files after a confirmed plan.
Instructions
Make a project folder match a local folder: upload new and changed files, and in mirror mode also delete what exists only in the project. Call plan_sync first, confirm the plan with the user, and pass its planToken; if the project or the folder changed since, REMOTE_DRIFT is returned and nothing changes. A planToken is required: without one the call is refused with CONFIRMATION_MISMATCH before anything is read, unless an additive sync passes unplanned: true to run without a plan on purpose (planned is then false); a mirror sync always needs one. Changed text documents are replaced through revision-checked write_file edits, recorded as tracked changes when writeMode is tracked, so a concurrent edit fails that file with REVISION_CONFLICT rather than being overwritten. Binaries and new files are uploaded, and one whose path changed since the plan fails with REMOTE_DRIFT; with writeMode tracked, new .tex, .bib, and similar text files are created with tracked content instead. Missing folders are created. Uploads and writes run first. Deletes run only in mirror mode, only when confirmDeleteCount equals the number of remoteOnly entries, else CONFIRMATION_MISMATCH, and never after any upload or write failed. Failures are per file and nothing is retried: the call continues unless stopOnError, then returns status, completed, failed, remaining, and a planToken to resume with. Each failed entry carries the step's error details, and kind: applied_untracked when a tracked step applied without being recorded as tracked changes (it is live, not reverted); a create that failed with details.created left its document behind, and resuming with the planToken writes it while it is still empty or holds the local text. On a ShareJS (legacy editor) document, text that adds an emoji or another character outside the Basic Multilingual Plane, or reorders existing ones, fails that file with INVALID_ARGUMENT. It saves tool calls, not time.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"projectId": "<projectId>",
"localFolderPath": "<localFolderPath>",
"mode": "<mode>"
},
"name": "sync_directory"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | additive only uploads and writes; mirror also deletes what exists only in the project | |
| ignore | No | Extra gitignore-style patterns, applied after the defaults (hidden files and folders, __MACOSX/, and LaTeX build output: *.aux, *.log, *.bbl, *.blg, *.out, *.toc, *.synctex.gz, *.fdb_latexmk, *.fls) and after any .olignore file in the folder; "!pattern" re-includes, for example "!.latexmkrc". Ignored paths are never uploaded, compared, or deleted, on either side. | |
| planToken | No | From plan_sync, or from a partial sync_directory to resume it; required unless an additive sync passes unplanned | |
| projectId | Yes | Overleaf project ID | |
| unplanned | No | Run an additive sync without a planToken on purpose; never with a planToken or in mirror mode | |
| writeMode | No | Use tracked to record inserted and deleted text as Overleaf tracked changes; defaults to untracked | untracked |
| stopOnError | No | Stop at the first failure instead of continuing | |
| localFolderPath | Yes | Local folder on the server's own disk, synced as a whole | |
| confirmDeleteCount | No | Required in mirror mode: the number of entries in plan_sync's remoteOnly, each folder counting once | |
| destinationFolderPath | No | Project folder the local folder corresponds to; "" (the default) is the project root |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | ||
| failed | Yes | ||
| status | Yes | ||
| planned | Yes | ||
| completed | Yes | ||
| planToken | No | ||
| remaining | Yes | ||
| identicalCount | Yes |