File System API Migration

Here are the API changes that will result from the [File System Evolution](File System) plan:

"Compatibility" column:

• Drop-in compatible - code using the API probably does not need to change at all, though it's possible there are subtle differences in edge cases
• Deprecated & shimmed - the API will temporarily continue to behave as before, but will be removed in the near future (under the hood, the old API has been reimplemented in terns of the new APIs, so there may be minor, subtle differences)
• Removed - the API is completely gone; code using it will throw exceptions

Old API	New API	Compatibility	Usage
FileEntry DirectoryEntry	File Directory	Drop-in compatible (same fields/members)	(lots)
entry.fullPath, entry.isFile, entry.isDirectory	(unchanged)	(unchanged) Properties are now read-only	fullPath: many isFile/Directory: 9
FileUtils.readAsText(fileEntry)	FileUtils.readAsText(file)	Drop-in compatible	13
FileUtils.writeText(fileEntry)	FileUtils.writeText(file)	Drop-in compatible	5
new NativeFileSystem.FileEntry(fullPath) new NativeFileSystem.DirectoryEntry(fullPath)	filesystem.getFileForPath(fullPath) filesystem.getDirectoryForPath(fullPath)	Deprecated & shimmed (constructors return a File/Directory object instead)	19
DirectoryEntry.getFile(relpath)	filesystem.resolve(dirFullPath + relpath)	Deprecated & shimmed	4
NativeFileSystem.resolveNativeFileSystemPath(fullPath)	filesystem.resolve(path)	Deprecated & shimmed	4
NativeFileSystem.requestNativeFileSystem(fullPath)... fs.root	filesystem.resolve(fullPath)	Deprecated & shimmed	6
Concatenation: folderPath + "/" + filename	(unchanged)	(unchanged) Doubled "/"es are normalized out by fs APIs
Concatenation: folderPath + filename	(unchanged)	(unchanged) Directory.fullPath always ends in "/", just like DirectoryEntry.fullPath	Several
Substrings: relpath = fullPath.slice(dirFullPath.length)	(unchanged)	(unchanged) Directory.fullPath always ends in "/", just like DirectoryEntry.fullPath
NativeFileSystem.showOpenDialog() NativeFileSystem.showSaveDialog()	filesystem.showOpenDialog() filesystem.showSaveDialog()	Deprecated & shimmed	4
fileEntry.createWriter()... writer.write(text)	file.write(text)	Removed	5 (unused in 3)
fileEntry.file()... new NativeFileSystem.FileReader().readAsText(fileObj)	file.readAsText()	Removed	None
directoryEntry.createReader().readEntries()	directory.getContents() ???	Removed	5
DirectoryEntry.getFile(relpath, {create:true})	filesystem.getFileForPath(fullPath).write("")	Removed	2
DirectoryEntry.getDirectory(relpath, {create:true})	filesystem.getDirectoryForPath(fullPath).create()	Removed	2
FileIndexManager.getFileInfoList("all") FileIndexManager.getFileInfoList("...")	ProjectManager.getAllFiles() ProjectManager.getAllFiles(filter) (Returns an array of Files, but they provide same properties as the old FileInfos)	Deprecated & shimmed	7
FileIndexManager.getFilenameMatches("...", filename)	ProjectManager.getAllFiles(filter)	Deprecated & shimmed	None
ProjectManager "projectFilesChange" event	FileSystem "change" event	Removed	2
Less common APIs
fileEntry.getMetadata()	file.stat()	Removed	1
NativeFileError.*	FileSystemError.*	Removed	1
instanceof NativeFileSystem.InaccessibleFileEntry	instanceof InMemoryFile	Removed	1
entry.remove()	entry.moveToTrash()	Removed	None
entry.filesystem	n/a	Removed	None
NativeFileSystem.Encodings.*	(none)	Removed	None
NativeFileSystem.isRelativePath()	(none)	Removed	None
brackets.fs.*()	(various)	These low-level APIs continue to exist, but have never been officially supported. They may break at any time.	Several

"Usage" = how many extensions currently use the API

Extensions that will break

The following 7 extensions use at least one API on the "Removed" list:

• angularui.angularjs -- (FileEntry.getMetadata())
• bsirlinger.github-access -- (DirectoryEntry.getFile({create}), DirectoryEntry.getDirectory({create}), FileEntry.createWriter())
• xunit -- (DirectoryEntry.getFile({create}), DirectoryEntry.getDirectory({create})
• zaggino.brackets-git (won't crash, but notable bug) -- ("projectFilesChange" event)
• variousimprovements (won't crash, minor bug) -- ("projectFilesChange" event)
• pflynn.brackets.editor.nav (won't crash, very minor bug) -- (InaccessibleFileEntry)
• interactive-linter (no effect on behavior) -- (NativeFileError)

We will file bugs with all extensions that are using removed APIs to make sure authors are aware of the change.