Virtual Files

A VirtualFile (VF) is the IntelliJ Platform's representation of a file in a Virtual File System (VFS).

Most commonly, a virtual file is a file in a local file system. However, the IntelliJ Platform supports multiple pluggable file system implementations, so virtual files can also represent classes in a JAR file, old revisions of files loaded from a version control repository, and so on.

The VFS level deals only with binary content. Contents of a VirtualFile are treated as a stream of bytes, but concepts like encodings and line separators are handled on higher system levels.

How do I get a virtual file?

Context	API
Action	`AnActionEvent.getData(PlatformDataKeys.VIRTUAL_FILE)` `AnActionEvent.getData(PlatformDataKeys.VIRTUAL_FILE_ARRAY)` for multiple selection
Document	`FileDocumentManager.getFile()`
PSI File	`PsiFile.getVirtualFile()` (may return `null` if the PSI file exists only in memory)
File Name	`FilenameIndex.getVirtualFilesByName()`
Local File System Path	`LocalFileSystem.findFileByIoFile()` `VirtualFileManager.findFileByNioPath()`/`refreshAndFindFileByNioPath()` (2020.2+)

What can I do with it?

Typical file operations are available, such as traverse the file system, get file contents, rename, move, or delete. Recursive iteration should be performed using VfsUtilCore.iterateChildrenRecursively() to prevent endless loops caused by recursive symlinks.

Where does it come from?

The VFS is built incrementally by scanning the file system up and down, starting from the project root. VFS refresh operations detect new files appearing in the file system. A refresh operation can be initiated programmatically using VirtualFileManager.syncRefresh()/asyncRefresh() or VirtualFile.refresh(). VFS refreshes are also triggered whenever file system watchers receive file system change notifications.

Invoking a VFS refresh might be necessary for accessing a file that has just been created by an external tool through the IntelliJ Platform APIs.

How long does a virtual file persist?

A particular file on disk is represented by equal VirtualFile instances for the IDE process's entire lifetime. There may be several instances corresponding to the same file, and they can be garbage-collected. The file is a UserDataHolder, and the user data is shared between those equal instances. If a file is deleted, its corresponding VirtualFile instance becomes invalid (isValid() returns false), and operations cause exceptions.

How do I create a virtual file?

Usually, you don't. As a general rule, files are created either through the PSI API or through the regular java.io.File API.

If one needs to create a file through VFS, use VirtualFile.createChildData() to create a VirtualFile instance and VirtualFile.setBinaryContent() to write some data to the file.

How do I get notified when VFS changes?

Implement BulkFileListener and subscribe to the message bus topic VirtualFileManager.VFS_CHANGES. For example:

project.getMessageBus().connect().subscribe(VirtualFileManager.VFS_CHANGES,
    new BulkFileListener() {
      @Override
      public void after(@NotNull List<? extends VFileEvent> events) {
        // handle the events
      }
    });

See Message Infrastructure and Plugin Listeners for more details.

For a non-blocking alternative, starting with version 2019.2 of the platform, see AsyncFileListener.

Are there any utilities for analyzing and manipulating virtual files?

VfsUtil and VfsUtilCore provide utility methods for analyzing files in the Virtual File System.

For storing a large set of Virtual Files, use dedicated VfsUtilCore.createCompactVirtualFileSet().

Use ProjectLocator to find the projects that contain a given virtual file.

How do I extend VFS?

To provide an alternative file system implementation (for example, an FTP file system), implement the VirtualFileSystem class (most likely you'll also need to implement VirtualFile), and register your implementation via com.intellij.virtualFileSystem extension point (2019.2 and later) or application component for earlier versions.

To hook into operations performed in the local file system (for example, when developing a version control system integration that needs custom rename/move handling), implement LocalFileOperationsHandler and register it via LocalFileSystem.registerAuxiliaryFileOperationsHandler().

What are the rules for working with VFS?

See Virtual File System for a detailed description of the VFS architecture and usage guidelines.

Last modified: 26 July 2023