Folder Analysis
Unifyl provides visual analysis tools for understanding directory contents, comparing directories, finding large files, and detecting duplicates. These tools use treemap visualizations, color coding, and AI-powered duplicate detection to help you reclaim disk space and understand your file system.
- Folder Size Heatmap
- Diff Heatmap
- Large File Finder
- Duplicate File Finder
- Feature Tier
- Screenshots
- Troubleshooting
The Folder Size Heatmap provides a treemap visualization of all files in a directory, where each file is represented as a rectangle proportional to its size. This makes it instantly obvious which files are consuming the most disk space.
- Menu: Tools > Folder Heatmap
-
Command Palette:
Cmd+Shift+P, type "Heatmap" - Context menu on a folder: Right-click > "Folder Heatmap"
The heatmap uses a squarified treemap layout algorithm:
- Each file is represented as a rectangle
- Rectangle area is proportional to file size relative to the total directory size
- Files are sorted by size (descending) before layout, so the largest files get the most prominent positions
- The layout adapts to the window size
The view shows:
- Total size of all scanned files
- File count in the current scan
- Loading indicator while scanning is in progress
Each rectangle is colored according to its FileCategory, as determined by file extension:
| Category | Typical Extensions | Color |
|---|---|---|
| Image | .jpg, .png, .gif, .heic, .tiff, .svg, .webp | Custom color |
| Video | .mp4, .mov, .avi, .mkv, .webm | Custom color |
| Audio | .mp3, .wav, .flac, .aac, .m4a | Custom color |
| Document | .pdf, .doc, .docx, .pages, .txt | Custom color |
| Code | .swift, .py, .js, .ts, .html, .css | Custom color |
| Archive | .zip, .tar, .gz, .7z, .rar | Custom color |
| System | .app, .dmg, .pkg, .dylib | Custom color |
| Other | Everything else | Default/gray |
Colors adapt to the active theme and follow the FileCategory+Color definitions in the design system.
Click on any rectangle in the treemap to:
- View the file's details (name, size, path)
- Navigate to the file's location in the file manager panel
- Select the file for further operations
The FolderHeatmapViewModel scans directories using the following process:
- Creates a
FileManager.enumeratorfor the target directory, skipping hidden files - Collects up to 2,000 files from the directory tree
- Filters out directories (only regular files are included)
- Excludes zero-byte files
- Sorts all results by size in descending order
- Takes the top 200 files for visualization to keep the treemap readable
- The scan runs on a detached task at
.userInitiatedpriority to avoid blocking the UI
Properties fetched per file:
-
fileSizeKey: The file's size in bytes -
isDirectoryKey: To filter out directories -
isHiddenKey: To skip hidden files (combined with.skipsHiddenFilesoption)
The Diff Heatmap provides a treemap visualization of directory comparison results, showing which files are identical, modified, or exist only in one side.
- Menu: Compare > Diff Heatmap
-
Command Palette:
Cmd+Shift+P, type "Diff Heatmap"
The Diff Heatmap requires two directories (typically the left and right panels) and compares them file by file.
Each block in the diff heatmap is colored according to its comparison status:
| Status | Color | Meaning |
|---|---|---|
| Identical | Green | File exists in both directories with the same content |
| Modified | Yellow | File exists in both directories but content differs |
| Only Left | Red | File exists only in the left directory |
| Only Right | Blue | File exists only in the right directory |
The view displays aggregate statistics:
| Stat | Description |
|---|---|
| Identical count | Number of files that match in both directories |
| Modified count | Number of files that differ between directories |
| Only Left count | Number of files unique to the left directory |
| Only Right count | Number of files unique to the right directory |
Each DiffBlock stores detailed comparison information:
| Property | Description |
|---|---|
relativePath |
Path relative to the compared root directory |
name |
Filename |
status |
One of: identical, modified, onlyLeft, onlyRight |
leftSize |
File size in the left directory (nil if not present) |
rightSize |
File size in the right directory (nil if not present) |
leftDate |
Modification date in the left directory |
rightDate |
Modification date in the right directory |
Clicking on a block reveals its full details and allows navigation to the file.
The DiffHeatmapViewModel compares directories by:
- Enumerating all files in both left and right directories
- Matching files by relative path
- Comparing matched files by size and content
- Classifying each file into one of the four status categories
The Large File Finder scans a directory tree and lists the largest files, helping you identify candidates for deletion or archival.
- Menu: Tools > Large File Finder
-
Command Palette:
Cmd+Shift+P, type "Large File Finder" - Context menu on a folder: Right-click > "Find Large Files"
The tool displays a sorted list of files by size (largest first), showing:
- File name and full path
- File size in human-readable format (KB, MB, GB)
- File type/category
- Last modified date
For each found file, you can:
- Click to select the file in the main file manager panel
- Delete, move, or compress the file using standard Unifyl operations
- Reveal the file in Finder
Unifyl provides two levels of duplicate detection: a standard file-hash-based finder and an AI-enhanced duplicate intelligence system.
The basic duplicate finder (DuplicateFinderView) identifies files with identical content:
- Select a directory to scan
- Files are grouped by size first (files of different sizes cannot be duplicates)
- Files of the same size are hashed to confirm identical content
- Results are displayed as groups of duplicate files
The enhanced duplicate finder (EnhancedDuplicateView) uses AI-powered analysis from the UnifylAI package:
Multi-Signal Scoring (MultiSignalScorer):
- Byte-level hash comparison for exact duplicates
- Perceptual hashing for visually similar images (different resolutions/formats of the same photo)
- Embedding comparison for semantically similar documents
- Filename similarity analysis
Duplicate Clustering (DuplicateClusterer):
- Groups related files into clusters based on similarity scores
- Each cluster represents a set of files that are duplicates or near-duplicates
- Clusters are displayed with confidence scores
Each duplicate cluster is displayed as a DuplicateClusterRow showing:
- Representative file (typically the "best" version)
- All duplicate files with their paths and sizes
- Similarity score for each file in the cluster
- A visual indicator of the total wasted space
The SpaceSavingsBar component shows:
- Total space currently used by all files in the cluster
- Space that would be recovered by keeping only the best version
- A visual progress bar representing the savings percentage
- The
SpaceSavingsCalculatorcomputes cluster-level and total savings
The KeepBestAdvisor in UnifylAI automatically recommends which file to keep based on:
- Image quality: Higher resolution, less compression
- File completeness: Larger file size (for identical formats)
- Path relevance: Files in organized directories (e.g., "Photos Library") preferred over random locations
- Recency: More recently modified versions preferred
- Naming conventions: Files with descriptive names preferred over generic names
The advisor marks one file as "Keep" and the rest as "Remove" in each cluster.
| Tool | Tier |
|---|---|
| Folder Size Heatmap | Pro |
| Diff Heatmap | Pro |
| Large File Finder | Pro |
| Duplicate File Finder (standard) | Pro |
| Enhanced Duplicates (AI) | Pro |
The Folder Size Heatmap showing a treemap visualization of a directory. Large rectangles represent big files (videos, disk images), with colors indicating file types. The total size and file count are displayed at the top. Hovering over a rectangle shows the file name and exact size.
The Diff Heatmap comparing two directories. Green blocks indicate identical files, yellow blocks show modified files, red blocks are files only in the left directory, and blue blocks are files only in the right directory. The statistics bar at the top summarizes the counts for each category.
- The heatmap scans up to 2,000 files but only visualizes the top 200 by size
- Very deep directory trees with many small files may not show all files
- Hidden files are excluded by default
- Large directories with tens of thousands of files take longer to enumerate
- The scan is limited to 2,000 files to maintain responsiveness
- Network-mounted directories will be significantly slower
- Ensure both directories are at the correct level in the hierarchy
- Files are matched by relative path, so directory structure must be comparable
- Symlinks may not be followed depending on the comparison mode
- The standard finder uses exact hash matching, so false positives should not occur
- The AI-enhanced finder may flag similar (but not identical) files -- review the similarity score
- Check the perceptual hash threshold in AI settings if image duplicates are too aggressively matched
- The savings calculator assumes you would keep exactly one copy of each file
- If a cluster contains files of different sizes (near-duplicates), the savings are based on removing all but the largest/best version