-
Notifications
You must be signed in to change notification settings - Fork 0
File System
Status: Proposal
The file system APIs in Brackets are a bit chaotic, and usage is inconsistent. Here are just a few issues:
- No centralized file system model. This makes it difficult to add file watchers, and update all file references in the app after operations like rename.
- Inefficient. We constantly hit the disk to read timestamps, content, etc.
- Two APIs for file i/o:
brackets.fs
andNativeFileSystem
- Incorrect creation of
FileEntry
objects (these should never be directly instantiated) - No way to use alternate storage--Dropbox, Google Drive, etc.
I'm pretty sure there are many more...
The high-level goals of the new file system are:
- Clean, consistent API.
- Unified file system model, including file watchers.
- High Performance. Only hit the disk when we need to.
- Ability to swap out low-level I/O routines (for cloud storage, etc.).
Here is a block diagram of the major parts:
Clients only interact with the blue boxes. The green boxes represent low-level file i/o implementations, which can be added as extensions. The red box replaces the old FileIndexManager
functionality, and does not have a public API (indexed files are accessed through FileSystem
).
There are a few basic rules for using the new file system.
- Persist full pathnames, but convert into
File
andDirectory
objects for in-memory use. CreatingFile
andDirectory
objects is cheap so there is no need to worry about performance. - There is a forced 1:1 relationship between
File
andDirectory
objects and their representation on disk. If two pieces of code ask theFileSystem
for the same file path, they will both be returned the sameFile
object. - When caching file (or directory) related data, you should use the file.id property as the key, and not the file.fullPath. The path of a file is subject to change if any of its parent directories are renamed.
- Listen for
"change"
events onFileSystem
to be notified if a file or directory changes.
A prototype implementation can be found in the glenn/file-system
branch.
Most functionality works. Existing unit tests pass, but there are no unit tests for the new code (yes, shame on me...). Many extensions are broken.
##API##
For a guide to converting from current Brackets file APIs to these new APIs, see File System API Migration.
This is a singleton object for registering low-level file system implementations, and creating new FileSystem
instances. Most code will never interact directly with this module.
/src/filesystem/FileSystemManager.js
The main class is FileSystem
. This is the public API for getting files and directories, showing open/save dialogs, and getting the list of all the files in the project.
There are two main FileSystem
instances:
This is the file system used for accessing application files like extensions and config files.
This is the file system for the current project, used to access any file related to the project.
###FileSystemEntry###
This is an abstract representation of a FileSystem entry, and the base class for the File
and Directory
classes. FileSystemEntry objects are never created directly by client code. Use FileSystem.getFileForPath()
, FileSystem.getDirectoryForPath()
, or Directory.getContents()
to create the entry.
/src/filesystem/FileSystemEntry.js
###File###
This class represents a file on disk (this could be a local disk or cloud storage). This is a subclass of FileSystemEntry
.
###Directory###
This class represents a directory on disk (this could be a local disk or cloud storage). This is a subclass of FileSystemEntry
.
##Performance## The main performance gains come from caching. The stats and contents of files and directories are cached in memory. This has a huge impact on i/o-intensive operations like "find in files", and generally speeds up many other parts of the system.
##File Watchers##
FileSystem
dispatches a "change"
event whenever a file or directory changes on disk. For now, the prototype refreshes the entire file tree whenever a directory changes. This is overkill, but was easy to implement. Ideally, only the directory that changed will be updated.
##Next Steps## Several core developers are working on getting this implemented. We will share a more detailed API proposal with the community soon, but in the meantime feel free to take a look at the unstable file-system dev branch.