Ventoy Search Configuration

• Background

By default, Ventoy will search all the directories and subdirectories for the image files. Normally, there is not so many files in your USB stick, so the process is very quick and you can hardly feel it. But if you have huge number of files in your USB stick, the process will be extremely slow and it will take a long time to boot into the menu.
So Ventoy provides some ways to control the search process.

Attention: The methods described here may be developed in different Ventoy versions, so please use the latest Ventoy release for test.

• 1. Specify search directory

With VTOY_DEFAULT_SEARCH_ROOT option in Global Control Plugin, we can specify a directory for search. After that, Ventoy will only search this directory (and its subdirectories) for image files.
With following configuration, Ventoy will only search in ISO directory (include its subdirectories).

{
    "control": [
        { "VTOY_DEFAULT_SEARCH_ROOT": "/ISO" }
    ]
}

• 2. Set search depth for subdirectory

With VTOY_MAX_SEARCH_LEVEL option in Global Control Plugin, we can set the max depth for subdirectories when searching.
By default, Ventoy will search all the subdirectories no matter how many levels. With this option, we can set, for example only search top 3 levels of subdirectories.
If VTOY_DEFAULT_SEARCH_ROOT is set at the same time, the level will be counted from the corresponding directory (level 0).
For example, the following configuration means that only list the files in the root and will not search any subdirectory.

{
    "control": [
        { "VTOY_MAX_SEARCH_LEVEL": "0" }
    ]
}

Tthe following configuration means that search only 1 level of subdirectories from ISO directory. For example, /ISO/abc will be searched but /ISO/abc/def will not be searched.

{
    "control": [
        { "VTOY_MAX_SEARCH_LEVEL": "1" },
        { "VTOY_DEFAULT_SEARCH_ROOT": "/ISO" }
    ]
}

• 3. Skip a directory

Ventoy provides another feature. If Ventoy detects that a file with name .ventoyignore exist in a directory. Then it will skip this directory and all its subdirectories.
It only needs that the file's name must be .ventoyignore. No requirements for file content, so it even can be en empty file.
This feaure is helpful in some case. For example, you have some MS Office install medium in ISO format under a directory. These ISO files will be listed by Ventoy but obviously they are not bootable images. So here you can put a .ventoyignore file in the directory, then these ISO files will not be listed anymore.

It should be noted that, the file's name must be .ventoyignore. That is to say, it has no name part, only a suffix.In normal case, you can't create such a file with no name part and just has a suffix. This is designed to prevent misoperation. You can use cmd.exe to create such file as follows.

echo 123 > E:\ISO\test\.ventoyignore

Besides, .ventoyignore also works in F2 Browser Mode. If .ventoyignore exists in the root of a partition, then the whole partition will be skipped in F2 Browser Mode.

• 4. Specify file list

Image File List Plugin is completely custom mode.
In this mode, Ventoy will no longer search for image files. You give Ventoy the exact file list.

• 5. Filter files by suffix

By default, Ventoy will list all supported image files, for example .iso/.wim/.img/.vhd/.vtoy files.
You can use VTOY_FILE_FLT_XXX option in Global Control Plugin to filter files by their suffix.
For example, set VTOY_FILE_FLT_EFI to "1", then all the .efi files will be ignored.

• Summary

Ventoy provides some configurations for the search process. Except for the image file list plugin, all others methods can be used in combination.
For example, you set ISO as the search directory. You can also put a .ventoyignore file in ISO/abc, then this ISO/abc directory will be skiped.