qdr.app.tools/qfu

QFU - Quadarax Filesystem Utility

A command-line utility for filesystem operations and file manipulations built on .NET 9.0.

Overview

QFU is a powerful filesystem utility that provides efficient file operations through a modular command-based architecture. The tool is designed for developers and system administrators who need reliable file manipulation capabilities with robust error handling and flexible input options.

Key Features

• File Cloning: Clone source files to multiple destinations with various options
• Directory Cleaning: Remove files or directories with pattern matching and recursive options
• Image Analysis: List image files with detailed metadata including dimensions, resolution, and file size
• Flexible Input Methods: Support for direct file specification or file list input
• Path Management: Automatic directory creation when needed
• Force Operations: Override existing files when necessary
• Robust Error Handling: Comprehensive validation and error reporting
• Modular Architecture: Extensible command and aspect-based design

Architecture

The application follows a clean modular architecture:

• Commands: Core operations (clone, cleardir, img_list)
• Aspects: Reusable functionality components (Source, Files, List, Force, Filter, Exclude, etc.)
• Base Classes: Shared functionality and abstractions
• Dependency Injection: Uses System.IO.Abstractions for testable file operations

Installation

Prerequisites

• .NET 9.0 Runtime
• Windows, Linux, or macOS

Build from Source

git clone <repository-url>
cd qfu
dotnet build --configuration Release
dotnet publish --configuration Release --self-contained

Usage

Basic Syntax

qfu <command> [arguments] [options]

Commands

Clone Command

Clone a source file to one or more destination files.

Syntax:

qfu clone <source_file> <target_files> [options]

Arguments:

• source_file: Path to the source file to clone
• target_files: Pipe-separated list of target file paths (file1.txt|file2.txt|file3.txt)

Options:

• -pe or -path_ensure: Create destination directories if they don't exist
• -force: Overwrite existing destination files
• -list: Treat the first target file as a text file containing a list of destination paths (one per line)
• -n <count>: Generate N numbered copies instead of using target files list

Clear Directory Command

Remove files or directories from a specified directory with optional pattern matching.

Syntax:

qfu cleardir <scope> <directory> [options]

Arguments:

• scope: Either files or directories - what to clean
• directory: Path to the directory to clean

Options:

• -s: Include subdirectories in the operation
• -f <patterns>: Filter patterns (pipe-separated, e.g., *.txt|*.log)
• -dry: Dry run - show what would be deleted without actually deleting
• -empty: Only delete empty files or directories

Image List Command

List all image files from a directory with their dimensions, resolution, and size information.

Syntax:

qfu img_list <source> [options]

Arguments:

• source: Path to directory to scan for image files

Options:

• -s: Include subdirectories in the scan
• -exclude <patterns>: Exclude files matching patterns (pipe-separated, e.g., *.tmp|backup*)

Output Format:

Dimensions   Resolution      Size      File Path
------------ --------------- --------- --------------------------------------------------
1920x1080    72x72 DPI       2.5 MB    photos/vacation.jpg
800x600      96x96 DPI       145.2 KB  thumbnails/small.png

Examples

Basic File Cloning

# Clone a file to multiple destinations
qfu clone source.txt "backup1.txt|backup2.txt|backup3.txt"

# Generate 5 numbered copies
qfu clone template.txt dummy -n 5
# Creates: template_1.txt, template_2.txt, template_3.txt, template_4.txt, template_5.txt

Directory Cleaning

# Remove all .log and .tmp files from current directory
qfu cleardir files . -f "*.log|*.tmp"

# Remove empty directories recursively (dry run first)
qfu cleardir directories ./temp -s -empty -dry

# Remove all files from subdirectories
qfu cleardir files ./cache -s -force

Image Analysis

# List all images in current directory
qfu img_list .

# List images recursively, excluding thumbnails and temporary files
qfu img_list ./photos -s -exclude "thumb*|*.tmp|backup*"

# Scan project directory but exclude build artifacts
qfu img_list ./src -s -exclude "bin/*|obj/*|*.cache"

Complex Examples

# Clone with all options
qfu clone template.cs "src/Class1.cs|src/Class2.cs|tests/TestClass.cs" -force -pe

# Clean directories with complex patterns
qfu cleardir files ./downloads -s -f "*.tmp|temp*|cache*" -dry

# Comprehensive image analysis
qfu img_list ./media -s -exclude "*.psd|raw/*|backup*"

Return Codes

• 0: Success - all operations completed successfully
• Non-zero: Failure - check console output for specific error details

Output Format

QFU provides detailed progress information:

• Operation summary at start
• Individual file operation status
• Final success/failure count
• Detailed error messages for failed operations

Supported Image Formats

The img_list command supports the following image formats:

• JPEG (.jpg, .jpeg)
• PNG (.png)
• GIF (.gif)
• BMP (.bmp)
• TIFF (.tiff, .tif)
• WebP (.webp)
• ICO (.ico)
• SVG (.svg)
• PSD (.psd)
• RAW formats (.raw, .cr2, .nef, .arw)

Note: Some formats may show "N/A" for dimensions/resolution if they cannot be processed by the image library.

Error Handling

QFU provides comprehensive error handling:

• Source Validation: Verifies source files/directories exist before operation
• Destination Validation: Checks for existing files (unless --force used)
• Path Validation: Ensures destination paths are valid
• Permission Checking: Reports access denied errors
• Image Processing: Graceful handling of unsupported or corrupted image files
• Pattern Validation: Validates search and exclude patterns

Development

Project Structure

qfu/
├── Commands/
│   ├── BaseCmd.cs          # Base command functionality
│   ├── CloneCmd.cs         # Clone command implementation
│   ├── ClearDirCmd.cs      # Directory cleaning command
│   ├── ImgListCmd.cs       # Image listing command
│   └── Aspects/
│       ├── FilesAspect.cs      # File handling logic
│       ├── ForceAspect.cs      # Force operation logic
│       ├── ListAspect.cs       # List file processing
│       ├── SourceAspect.cs     # Source file validation
│       ├── FilterAspect.cs     # Pattern filtering
│       ├── ExcludeAspect.cs    # Exclusion patterns
│       ├── ScopeAspect.cs      # Operation scope (files/dirs)
│       ├── SubdirsAspect.cs    # Subdirectory inclusion
│       ├── DryAspect.cs        # Dry run functionality
│       └── EmptyAspect.cs      # Empty file/directory handling
├── QfuCommandContext.cs    # Command execution context
├── QfuEngineContext.cs     # Engine context
└── Program.cs              # Application entry point

Adding New Commands

1. Create a new command class inheriting from BaseCmd
2. Implement required abstract members
3. Add [CommandDefinition] attribute
4. Define command-specific aspects if needed

Testing

The project uses System.IO.Abstractions for testable file operations. Mock the IFileSystem interface for unit testing.

Dependencies

• .NET 9.0: Core runtime
• qdr.fnd.core.qconsole: Command-line framework
• System.Drawing.Common: Image processing capabilities
• System.IO.Abstractions: File system abstraction for testing

License

Copyright © 2025 Quadarax

Support

For issues and feature requests, please visit: https://quadarax.com/qfu

---

Version: 1.0.0
Target Framework: .NET 9.0
Package Tags: FILE, UTILITY