- Banner inside the editor pane for a dirty tab whose file changed (Reload (discard mine) / Keep mine / Compare) or was deleted (Keep as unsaved / Close); state in stores/diskConflicts.ts, the old notice is gone. - Save and save all ask Overwrite / Cancel when the engine refuses with disk_changed. - Diff tabs against the disk text (file.readDisk) and a Local History entry (history.read); "Revert to This" in the caption. - Show Local History dialog (history.show: tree context menu, palette, File menu) with Show Diff and an undoable Revert to This. - History failures warn once until a snapshot works again. - Docs: docs/local-history.md, G2 in gaps.md, ui-parity, architecture. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
7.3 KiB
Files changed on disk and Local History
Status: v1 (C10 A2, owner decision D29) · Last updated: 2026-11-08
Lutra never loses a text because another program, a git operation or Lutra itself changed a file. Two parts work together:
- Files changed on disk: what an open editor does when its file changes or disappears outside Lutra, and how a save avoids overwriting a newer file.
- Local History: copies of file texts that Lutra keeps by itself, per project, so you can compare with and go back to an earlier text, also for files git does not track.
Behaviour comes from Lutra's own design and the public documentation of the feature in other IDEs; wording, icons and shortcuts are Lutra's own (there is no default shortcut).
Files changed on disk
Lutra watches the folders of every open file (docs/architecture.md › VFS). Every change to a file only means "look again": what counts is the file on disk when Lutra looks.
| Situation | What Lutra does |
|---|---|
| The file changed, the tab has no unsaved changes | Reloads it silently. The editor moves onto the new text with the smallest change, so the caret and the scroll position stay where the text around them did not change. |
| The file changed, the tab has unsaved changes | Keeps your text and shows a banner in the editor: Reload (discard mine), Keep mine, Compare. |
| The file was deleted or renamed away | Keeps the text, marks the tab as unsaved and shows a banner: Keep as unsaved, Close. Closing the tab later asks as for any unsaved file; saving writes the file again. |
| The file is deleted and created again (a git checkout, an editor that saves by replacing the file) | Treated as a change, not as a loss: the tab reloads (or shows the "changed" banner if it has unsaved changes). A tab that only became unsaved because its file was gone for a moment reloads like a clean one. |
| The file comes back with exactly your text | The banner goes away and the tab is clean again. |
- Reload (discard mine) replaces your text with the file's (
file.reload). Your text goes into the Local History first. - Keep mine hides the banner. The next save asks once more before it overwrites the newer file.
- Compare opens a diff tab: the file on disk on the left, your text on the right (
file.readDisk). You can edit the right side; it is the same buffer as the tab. - Close closes the tab without saving; the text is in the Local History.
Saving never overwrites a newer file silently
Before every save the engine compares the file's modification time and size with what it recorded when it last read or wrote the file. When they differ it reads the file and compares its hash. A different text means another program changed it:
file.savefails withdisk_changed, and the editor asks "… was changed by another program since you opened it. Overwrite it with your text?" (Overwrite / Cancel, Cancel has the focus). Overwrite repeats the save withoverwrite: true.file.saveAllsaves the others and lists such files underdiskChanged; the editor asks for each.- Autosave (
file.saveAll {skipConflicts: true}) never asks and never overwrites: it leaves these files unsaved. - A file that was only touched (same text) saves without asking. A file that is gone is written again.
Local History
What is kept, and when
| Reason in the list | When |
|---|---|
| Saved | Every save (also save all and autosave) keeps the saved text. |
| Before first save | The first save of a file in a session keeps the text it overwrites, unless the history already has it. |
| Changed by another program | When Lutra sees another program's text for an open file. |
| Before reload from disk | The tab's text before a reload replaces it (silent reload or "Reload (discard mine)"). |
| Deleted on disk | The tab's text when its file disappears. |
| Before refactoring | Every file a rename (lsp.rename) changes, before it changes. |
| Before git operation | Every open file before checkout, new branch with checkout, merge, abort merge, stash, apply stash, pull and revert chunk. |
| Before revert | The tab's text before "Revert to This" replaces it. |
A text equal to the file's newest entry is not added again, so repeated saves of the same text cost nothing. Texts over 16 MiB are not kept.
Files that are not open in Lutra are not watched for the history. git protects their local changes itself: checkout, merge and pull refuse to overwrite them, and stash keeps them.
Using it
- Show Local History: in the project tree's context menu (Show Local History), the palette and File › Show Local History (
history.show {path?}; without a path, the active tab's file). The dialog lists the file's entries newest first with date, time, reason and size. - Show Diff (or Enter, or a double click) opens a diff tab: the entry on the left, the current text on the right.
- Revert to This (in the dialog and in the diff tab's caption) puts the entry's text into the editor as an ordinary unsaved change: Undo brings your text back, and nothing is written until you save. A closed file is opened first.
Storage and limits (D29)
- In Lutra's data directory, per project:
<data dir>/history/<project id>/(the project id is a hash of the project folder). Never inside the project; if the data directory lies inside the project, the Local History is off and Lutra says so. - Content-addressed: each text is stored once as
blobs/<first two hex digits>/<SHA-256>, however many entries refer to it.index.jsonllists the entries. - Kept for 14 days, at most 200 MB per project: when the project opens, older entries are dropped, then the oldest ones while the texts take more than 200 MB, and texts no entry refers to are deleted. A new entry that crosses 200 MB drops the oldest ones at once.
- A damaged index line is skipped; a text whose hash does not match is reported as damaged instead of shown. Failing to write the history never stops a save: Lutra shows one warning.
Commands
| Command | What it does |
|---|---|
file.save {id, overwrite?} |
Saves; disk_changed when the file is newer, unless overwrite. |
file.saveAll {skipConflicts?} |
Saves every unsaved buffer; diskChanged lists the ones it left alone. |
file.reload {id} |
Replaces the buffer with the file ("Reload (discard mine)"). |
file.readDisk {path} |
The file's text on disk, answered like git.show. |
buffer.get {id} |
Includes diskConflict: null, "changed" or "removed". |
history.list {path} |
The file's entries, newest first: {id, time, reason, size}. |
history.read {path, id} |
One entry's text, answered like git.show. |
history.revert {path, id} |
Puts an entry's text into the buffer (an undoable buffer.edit). |
history.show {path?} |
UI command: the dialog. |
Events: fileChangedOnDisk {path, id, removed} sets the banner, diskConflictResolved {id} removes it.
Not yet
- Labels (put a name on the current state), history of a folder or of the whole project, recently deleted files.
- History for files changed by tools while they are not open in Lutra.
- A merge view for a changed file (Compare shows both sides; you merge by editing the right side).
- Settings for the 14 days and 200 MB.
Revision history
| Date | Change | Summary |
|---|---|---|
| 2026-11-08 | major | First version (C10 A2) |