A high-performance GUI tool for creating and editing Perforce (P4) virtual stream specifications with an intuitive file tree interface.
The Virtual Stream Spec Creator simplifies the process of defining which files and folders should be included in a Perforce virtual stream. It provides a visual tree interface where users can check/uncheck items to build their stream specification, with automatic optimization of paths and support for large repositories.
After installing the tool as a custom tool in P4V (see below), create a new virtual stream, then right click on it and select the Virtual Stream Utility. It will open a GUI view where you can view the available folders and files and select which ones you want to include in the virtual stream.
Once selected, click the "Update Stream" button to apply the new view to the virtual stream.
You can also run the tool from the command line with a virtual stream path:
.\virt-stream-util.exe //depot/my_virtual_stream- Visual Tree Interface: Browse and select files/folders with checkboxes
- Lazy Loading: Efficiently handles large repositories with thousands of files
- Smart Path Optimization: Automatically uses
folder/...notation instead of listing individual files - Real-time Spec Preview: See your stream specification update as you make selections
- Space-aware Paths: Automatically quotes paths containing spaces
- P4Ignore Support: Automatically includes p4ignore files by default
- Python 3.12+
- PySide6
- P4Python
- Perforce client configured and connected
Download a precompiled executable from the Releases page or build from source and put it in it's own directory. (Usually a subfolder under your user home directory is best)
This is a humble open-source project so the exe is not signed and you may need to tell Windows Defender or other antivirus software to trust it. Feel free to compile from source yourself or run it as python (see below) if you are concerned.
-
In P4V, go to Tools > Manage Tools > Custom Tools...
-
Create a new tool
-
Enter settings:
- Name: Virtual Stream Utility
- Add to applicable context menus
- Application <Path to the executable you downloaded>
- Arguments:
%t - Start In: <Directory where you want log file to be generated>
- Refresh P4V upon completion
-
Click OK
Now you can run the tool by right clicking on a virtual stream and selecting "Virtual Stream Utility" from the bottom of the menu.
If you see an alert like this:
It means windows defender has blocked the executable because it is not signed.
- Open Windows Security (Windows key + I → Privacy & Security → Windows Security)
- Go to "Virus & threat protection"
- Click "Manage settings" under "Virus & threat protection settings"
- Scroll down to "Exclusions" and click "Add or remove exclusions"
- Click "Add an exclusion" → "Folder" → Browse to the folder where you put the downloaded exe and add an exception for it.
If you would prefer not to use the precompiled binaries or you wish to customize the code, there are a couple additional steps.
-
You will need to have Python 3.12 or higher (may work with older versions).
-
After cloning the repository, cd to the repo directory and install requirements (Pyside6 and P4Python)
pip install -r requirements.txt -
Verify that it runs.
python src/main.py -
Follow the steps above for adding a custom tool to P4V but Application and Arguments will be different.
- Application: Here, enter the path to your python installation.
- Arguments: For arguments, enter the path to the
app/main.pyscript inside the repository followed by%t
The interface is divided into two panels:
-
Left Panel: File tree with checkboxes
- Click checkboxes to include/exclude items
- Click arrows to expand folders (lazy-loaded on demand)
- Folders can be selected without expanding them
-
Right Panel: Generated stream specification
- Shows the P4 stream spec syntax
- Updates in real-time as you make selections
- Uses optimized
folder/...notation
- Check a folder: Includes all contents (even if not expanded)
- Partially check: Some but not all children are selected
- Expand folders: Click the arrow to load children on-demand
- Update Stream: Click button to save changes to Perforce
share "DCC/Blender/..."
share "DCC/Photoshop/placeholder.txt"
share "Engine/Code Goes Here.txt"
share "Game/Imports/..."
share p4ignore.txt
- Ensure you're passing a virtual stream path, not a regular stream
- Check your P4 connection:
p4 info - Verify you have access to the parent stream
- Check log file for error messages (will be generated in the "Start In" directory)
FileTreeBuilder: Background worker for building tree structureStreamSpecCreator: Main window and UI logicLoadingDialog: Progress indicator during initial load- Tree uses Qt's model-view architecture with custom check handling
This project is licensed under the MIT License. You can find the full license text in the LICENSE file.
This application is built using several third-party libraries, which are governed by their own licenses. A full list of these libraries and pointers to their license texts can be found in the NOTICE.md file.
This application uses PySide6, which is licensed under the GNU Lesser General Public License, version 3 (LGPLv3).
A key requirement of the LGPLv3 is that the user must be able to run the application with a modified version of the LGPL-licensed library. Since this is a standard Python application, this requirement is met by allowing you to manage your own Python environment. You can freely upgrade, downgrade, or install a modified version of PySide6 using pip.
For example, to install a specific version of PySide6, you can use:
pip install PySide6==6.7.0