The File System Service is a core platform component responsible for abstracting file access across different environments (Desktop, Web, Remote). It provides a unified API for file operations, watches for changes, and integrates with the workbench's "Working Copy" system to manage dirty states, backups, and text editor models.
The file system architecture is divided into three main layers:
IFileService): A generic provider-based service that routes URI-based requests to registered IFileSystemProvider implementations src/vs/platform/files/common/fileService.ts26-50ITextFileService): Adds text-specific logic such as encoding detection, line ending normalization, and integration with the Monaco editor's ITextModel src/vs/workbench/services/textfile/browser/textFileService.ts47-84FileWorkingCopyManager src/vs/workbench/services/workingCopy/common/fileWorkingCopyManager.ts43-54The following diagram illustrates how a file request flows from the Workbench through the service layers to the actual disk.
File Access Pipeline
Sources: src/vs/platform/files/common/fileService.ts26-50 src/vs/workbench/services/textfile/browser/textFileService.ts47-84 src/vs/platform/files/node/diskFileSystemProvider.ts28-37 src/vs/base/node/pfs.ts6-18
IFileService is the entry point for all file-based operations. It manages a registry of IFileSystemProvider instances keyed by URI scheme src/vs/platform/files/common/fileService.ts50-52
Providers declare their capabilities via the FileSystemProviderCapabilities bitmask src/vs/platform/files/common/files.ts21-23
| Capability | Description |
|---|---|
FileReadWrite | Basic read/write support using buffers src/vs/platform/files/common/files.ts21-23 |
FileOpenReadWriteClose | Low-level file descriptor based access src/vs/platform/files/common/files.ts21-23 |
FileReadStream | Provider supports ReadableStream for large files src/vs/platform/files/common/files.ts21-23 |
FileAtomicWrite | Provider handles atomic writes (writing to temp file then renaming) src/vs/platform/files/common/files.ts21-23 |
PathCaseSensitive | Indicates if the underlying system respects casing src/vs/platform/files/common/files.ts21-23 |
Sources: src/vs/platform/files/common/files.ts21-23 src/vs/platform/files/common/fileService.ts52-88
The DiskFileSystemProvider is the primary provider for the desktop. It wraps Node.js fs modules and uses pfs.ts (Promisified File System) for performance src/vs/platform/files/node/diskFileSystemProvider.ts28-37
FileAtomicRead, FileAtomicWrite, and FileAtomicDelete src/vs/platform/files/node/diskFileSystemProvider.ts46-59resourceLocks (a ResourceMap<Barrier>) to prevent concurrent write operations on the same resource src/vs/platform/files/node/diskFileSystemProvider.ts169-171SymlinkSupport.stat to correctly handle symbolic links and file permissions (e.g., FilePermission.Locked, FilePermission.Executable) src/vs/platform/files/node/diskFileSystemProvider.ts73-95File watching reflects external changes in the editor. VS Code uses a multi-tiered watching strategy.
fs.watch API, typically used for watching individual files or small sets of files src/vs/platform/files/node/diskFileSystemProvider.ts26When a provider detects a change, it fires onDidChangeFile. FileService wraps these into FileChangesEvent and emits them globally src/vs/platform/files/common/fileService.ts66-76 The ParcelWatcher specifically applies a delay (FILE_CHANGES_HANDLER_DELAY = 75ms) to aggregate events before emitting src/vs/platform/files/node/watcher/parcel/parcelWatcher.ts177-178
Sources: src/vs/platform/files/common/fileService.ts66-76 src/vs/platform/files/node/diskFileSystemProvider.ts23-26 src/vs/platform/files/node/watcher/parcel/parcelWatcher.ts141-188
ITextFileService manages TextFileEditorModel, which bridges the file system and the editor's ITextModel.
TextFileEditorModel.resolve() reads the file, detects encoding, and creates a text buffer factory src/vs/workbench/services/textfile/common/textFileEditorModel.ts51-113dirty src/vs/workbench/services/textfile/common/textFileEditorModel.ts108-111TaskSequentializer to ensure only one save operation runs at a time and handles concurrent save requests src/vs/workbench/services/textfile/common/textFileEditorModel.ts106The service handles encoding via toDecodeStream and toEncodeReadable. It supports BOM detection and various encodings like UTF-8, UTF-16le, and UTF-16be src/vs/workbench/services/textfile/browser/textFileService.ts36-37 src/vs/workbench/services/textfile/common/textfiles.ts102-120
Sources: src/vs/workbench/services/textfile/common/textFileEditorModel.ts51-113 src/vs/workbench/services/textfile/common/textfiles.ts102-120 src/vs/workbench/services/textfile/browser/textFileService.ts80-84
The Working Copy system ensures that unsaved changes are never lost.
FileWorkingCopyManager coordinates between StoredFileWorkingCopy (disk files) and UntitledFileWorkingCopy (new files) src/vs/workbench/services/workingCopy/common/fileWorkingCopyManager.ts43-54 It provides a unified resolve() method to handle both stored and untitled resources src/vs/workbench/services/workingCopy/common/fileWorkingCopyManager.ts73-98
Every time a model becomes dirty, a backup is scheduled via IWorkingCopyBackupService src/vs/workbench/services/workingCopy/common/storedFileWorkingCopy.ts20-23 UntitledFileWorkingCopy specifically checks for backups during its resolution process src/vs/workbench/services/workingCopy/common/untitledFileWorkingCopy.ts184-188
Code Entity Mapping: Working Copy System
Sources: src/vs/workbench/services/workingCopy/common/workingCopy.ts23-26 src/vs/workbench/services/textfile/common/textFileEditorModel.ts51-88 src/vs/workbench/services/untitled/common/untitledTextEditorModel.ts80-116 src/vs/workbench/services/workingCopy/common/fileWorkingCopyManager.ts43-122
The save operation involves conflict detection and atomic writes.
| Step | Entity | Action |
|---|---|---|
| 1 | TextFileEditorModel | Triggers saveSequentializer to queue the save src/vs/workbench/services/textfile/common/textFileEditorModel.ts106 |
| 2 | TextFileService | Resolves encoding and BOM via toEncodeReadable src/vs/workbench/services/textfile/browser/textFileService.ts36 |
| 3 | FileService | Calls writeFile. It may check stat() for ETAG mismatches to detect out-of-sync conflicts src/vs/platform/files/common/fileService.ts165 src/vs/platform/files/common/files.ts118 |
| 4 | DiskFileSystemProvider | Performs the write. If atomic, it writes to a temp file and renames it using rimrafMove logic or native rename src/vs/platform/files/node/diskFileSystemProvider.ts46-59 src/vs/base/node/pfs.ts62-65 |
| 5 | FileService | Emits FileOperation.WRITE event src/vs/platform/files/common/fileService.ts163-165 |
Sources: src/vs/workbench/services/textfile/common/textFileEditorModel.ts106-112 src/vs/platform/files/common/fileService.ts163-167 src/vs/platform/files/node/diskFileSystemProvider.ts28-60 src/vs/base/node/pfs.ts62-65
The workbench provides services for opening and saving files via native or simple (web-based) dialogs.
AbstractFileDialogService provides the base logic for default file and folder paths based on history and environment src/vs/workbench/services/dialogs/browser/abstractFileDialogService.ts37-60 It uses IHistoryService to suggest the lastActiveFile or lastActiveWorkspaceRoot as a starting point src/vs/workbench/services/dialogs/browser/abstractFileDialogService.ts62-90
In environments where native dialogs are unavailable (e.g., Web), the SimpleFileDialog uses IQuickInputService to provide a file picker UI src/vs/workbench/services/dialogs/browser/simpleFileDialog.ts112-146 It allows navigating the remote or local file system via a quick pick interface src/vs/workbench/services/dialogs/browser/simpleFileDialog.ts92-95
Dialog Interaction Flow
Sources: src/vs/workbench/services/dialogs/browser/simpleFileDialog.ts43-112 src/vs/workbench/services/dialogs/browser/abstractFileDialogService.ts37-90 src/vs/platform/files/common/fileService.ts26-50
Refresh this wiki
This wiki was recently refreshed. Please wait 7 days to refresh again.