microsoft/vscode
1
0
Fork 0
mirror of https://github.com/microsoft/vscode.git synced 2025-12-11 02:08:52 -06:00
Code Issues Packages Projects Releases 177 Wiki Activity

Updated Working Copies (markdown)

Benjamin Pasero 2022-09-11 07:26:18 +02:00
parent 83eb79a6e8
commit 66b43b0df8
1 changed files with 21 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
Working-Copies.md

@ -10,8 +10,28 @@ The API shape of a working copy provides the minimal structure for participating
* dirty tracking
The fundamental pieces of a working copy are:
* `resource`: to identify the working copy among others
* `typeId`: to tell apart your working copy from others with the same resource
* `capabilities`: to tell if a working copy is untitled or not (e.g. untitled working copies are never auto saved)
* events (`onDidChangeDirty`, `onDidChangeContent`, `onDidSave`): to provide dirty tracking and backup support
* methods (`backup`, `save`, `revert`): to actually provide the necessary implementation for the workbench to call on
## Lifecycle
## Lifecycle
As soon as your working copy comes to existence, call `IWorkingCopyService.registerWorkingCopy`. From that moment on, the workbench will observe the working copy for changes using its events.
As soon as your working copy becomes void, dispose the registration again!
**Note:** it is an error to register the same working copy more than once. The combination of `resource` and `typeId` is used for comparing working copies with each other.
### Providing Backups
As soon as the working copy reports a content change, the workbench will call the `backup` method to store a backup of the unsaved state in the backup location. You can:
* provide the `content` to backup as raw buffer
* provide some `meta` information as object associated with the backup
**Note:** backups are automatically deleted once the working copy is saved and no longer reports as dirty.
### Restoring Backups
The workbench is not in charge of resolving your working copy, it is up to you as provider. In order to restore potential backups that might be present from a previous session, you have to use `IWorkingCopyBackupService.resolve` with the identifier (`resource` and `typeId`) and set the contents of the working copy to that when resolving. In addition, you should mark your working copy as dirty.
### Save/Revert
The contract of these methods is that after the operation succeeded, the working copy is no longer dirty. In addition, the `onDidSave` and `onDidChangeDirty` should have fired.