Checkpoints
A checkpoint is a named snapshot you take on purpose, of one file or of a whole folder subtree. Monofile trims automatic versions as you keep working and never trims checkpoints, so a checkpoint is the marker you can still find next month.
When to take one
Before a rewrite you are not sure about, so "start again from before" stays cheap.
Before you let an agent loose on a folder, especially with a broad instruction like "reorganise these notes".
Before a bulk shell command, a scripted rename or a large sync push.
At a point you might want to compare against later, for example the state of a draft when you sent it out.
Naming matters, because the name is what you will scan later. before auth refactor beats backup 3.
How a checkpoint differs from an automatic version
| Automatic version | Checkpoint | |
|---|---|---|
| Created by | Every content write | You, deliberately |
| Content stored | What the file looked like before that write | What the file looks like right now |
| Named | No, labelled with the run's summary | Yes, 1 to 60 characters |
| Trimmed away | Yes, only the newest 20 per file survive | Never |
| Covers a folder | No, one file at a time | Yes, the whole subtree in one snapshot |
Creating one
In the web app, open the file's History panel, type a name in the checkpoint field at the top and press Checkpoint. The command palette also has Checkpoint this file, which names it after the current date and time.
From the terminal, one command covers both a file and a folder:
monofile checkpoint /Projects/report.md "before rewrite"
monofile checkpoint /Projects "before auth refactor"From the API, the checkpoint tool takes a path and a name, and needs the files:write scope:
{"path": "/Projects", "name": "before auth refactor"}curl -X POST "https://www.monofile.ai/api/tools/checkpoint" \
-H "Authorization: Bearer $MONOFILE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"path": "/Projects", "name": "before auth refactor"}'A folder checkpoint walks the subtree and snapshots every file in it, subfolders included. The response gives the number of files it captured and an id you can restore later.
Limits
| Limit | Value | What happens at the edge |
|---|---|---|
| Checkpoints per file | 10 | The call fails with CAP_EXCEEDED; restore or move on from an old one first |
| Files per folder checkpoint | 200 | The call fails with CAP_EXCEEDED; checkpoint a narrower folder |
| Name length | 1 to 60 characters | Longer names are rejected |
A folder checkpoint covers the text files in the subtree. It skips media files, whose content lives in object storage.
Restoring one
A file checkpoint shows up in that file's history under the name you gave it. Select it, preview it, and restore it like any other version. Monofile captures your current content first, so you can undo the restore.
A folder checkpoint is one changeset, so you restore the whole subtree at once by reverting it:
monofile changesets list --limit 20
monofile changesets revert <changeset-id>Next steps
Reverting SafelyRestore a file or undo a whole run, and what happens on a conflict.
ChangesetsRuns grouped into one reviewable, revertable unit.
How Versioning WorksAutomatic version capture on every write, and how long versions last.