File System Implementations

The front-end client-facing filesystem API is decoupled from the back-end filesystem implementation in order to accommodate completely different kinds of filesystems. For example, with this API, clients can uniformly access filesystems for accessing local files based on Brackets shell or Node.JS, or for accessing remove files stored on Dropbox or SkyDrive. This page describes the requirements for implementing a filesystem back-end implementation.

FileSystemImpl

The client-facing filesystem API is provided by a singleton FileSystem object. This object has a single method, FileSystem.init, to initialize the filesystem with a particular filesystem implementation, which is responsible for core functionality like reading and writing files, and providing file and directory change notifications. The implementation object should satisfy a FileSystemImpl interface, as described below.

init(callback)

• @param {function(?string)=} callback
• Initialize the implementation object, and optionally call back asynchronously when the initialization is complete. The callback takes a single, nullable error parameter, as given by the properties of FileSystemError, described below.

showOpenDialog(allowMultipleSelection, chooseDirectories, title, initialPath, fileTypes, callback)

• @param {boolean} allowMultipleSelection
• @param {boolean} chooseDirectories
• @param {string} title
• @param {string} initialPath
• @param {Array.<string>=} fileTypes
• @param {function(?string, Array.<string>=)} callback
• Display an open-files dialog to the user and call back asynchronously with either an error string or an array of path strings, which indicate the file or files chosen by the user.

showSaveDialog(title, initialPath, proposedNewFilename, callback)

• @param {string} title
• @param {string} initialPath
• @param {string} proposedNewFilename
• @param {function(?string, string=)} callback
• Display a save-file dialog to the user and call back asynchronously with either an error or the path to which the user has chosen to save the file.

optional isNetworkDrive(path, callback)

• @param {string} path
• @param {function(?string, boolean=)} callback
• Determine whether the given path resides on a high-latency network-mounted drive by calling back asynchronously either with an error or a boolean, which is true if the drive is network mounted and false otherwise.

exists(path, callback)

• @param {string} path
• @param {function(boolean)} callback
• Determine whether a file or directory exists at the given path by calling back asynchronously with a boolean, which is true if the file exists and false otherwise.

readdir(path, callback)

• @param {string} path
• @param {function(?string, Array.<FileSystemEntry>=, Array.<FileSystemStats=>=)} callback
• Read the contents of the directory at the given path, calling back asynchronously either with an error or an array of FileSystemEntry objects. The callback may also include an array of FileSystemStats objects, which correspond to the FileSystemEntry objects. Neither the array of stats objects, nor the individual stats themselves are guaranteed to exist.

mkdir(path, mode, callback)

• @param {string} path
• @param {number=} mode
• @param {function(?string, FileSystemStats=)=} callback
• Create a directory at the given path, and optionally call back asynchronously with either an error or a stats object for the newly created directory. The mode parameter is optional; if unspecified, the mode of the created directory is implementation dependent.

rename(oldPath, newPath, callback)

• @param {string} oldPath
• @param {string} newPath
• @param {function(?string)=} callback
• Rename the file or directory at oldPath to newPath, and optionally call back asynchronously with a possibly null error.

stat(path, callback)

• @param {string} path
• @param {function(?string, FileSystemStats=)} callback
• Stat the file or directory at the given path, calling back asynchronously with either an error or the entry's associated FileSystemStats object.

readFile(path, options, callback)

• @param {string} path
• @param {{encoding : string=}=} options
• @param {function(?error, string=, FileSystemStats=)} callback
• Read the contents of the file at the given path, calling back asynchronously with either an error or the data and, optionally, the FileSystemStats object associated with the read file. The optional options parameter can be used to specify an encoding (default "utf8").

writeFile(path, data, [options], callback)

• @param {string} path
• @param {string} data
• @param {{encoding : string=, mode : number=}=} options
• @param {function(?error, FileSystemStats=)} callback
• Write the given data to the file at the given path, calling back asynchronously with either an error or, optionally, the FileSystemStats object associated with the written file. The optional options parameter can be used to specify an encoding (default "utf8") and a mode (default unspecified and implementation dependent). If no file exists at the given path, a new file will be created.

chmod(path, mode, callback)

• @param {string} path
• @param {number} mode
• @param {function(err)=} callback
• Change the mode of the file or directory at the given path, optionally calling back asynchronously with an possibly null error.

unlink(path, callback)

• @param {string} path
• @param {number} mode
• @param {function(err)=} callback
• Delete the file or directory at the given path, optionally calling back asynchronously with an possibly null error.

optional moveToTrash(path, callback)

initWatchers(callback)

watchPath(path, callback)

unwatchPath(path, callback)

unwatchAll(callback)