v0.13.0: File Filtering with Glob Patterns

What's New in v0.13.0

🎯 File Filtering with Glob Patterns

This release adds powerful file filtering capabilities to the bake_folder macro, allowing you to selectively include or exclude files when embedding them into your binary.

New Parameters

• include_patterns: Array(String) - Include only files matching glob patterns (whitelist)
• exclude_patterns: Array(String) - Exclude files matching glob patterns (blacklist)

Pattern Syntax

• * - Matches any characters except path separator (e.g., *.cr)
• ** - Matches zero or more directory levels (e.g., **/*.cr)
• ? - Matches single character (e.g., file?.txt)

Examples

Include only Crystal source files:

class Assets
  extend BakedFileSystem
  bake_folder "./src", include_patterns: ["**/*.cr"]
end

Exclude test and spec files:

class Assets
  extend BakedFileSystem
  bake_folder "./project", exclude_patterns: ["**/test/*", "**/spec/*"]
end

Combined filtering (include source, exclude tests):

class Assets
  extend BakedFileSystem
  bake_folder "./src",
    include_patterns: ["**/*.cr", "**/*.md"],
    exclude_patterns: ["**/test/*", "**/*_spec.cr"]
end

Use Cases

• Embed only production assets (exclude dev/test files)
• Include specific file types (source code, documentation)
• Exclude large or generated files (builds, logs, cache)
• Filter by directory structure (exclude vendor, node_modules)

📦 Implementation Details

• Pattern matching happens at compile time (zero runtime overhead)
• Patterns are relative to the baked directory
• Include patterns are applied first (OR logic)
• Exclude patterns are then applied (OR logic)
• Fully backward compatible - existing code continues to work

🔗 Full Changelog

Merged PR: #59

For more details, see the updated README with comprehensive documentation and examples.

v0.12.0

⚠️ Breaking Change

This release introduces compile-time size validation with a default maximum of 50MB compressed. Builds will fail at compile-time if this limit is exceeded.

Migration Guide

If your build fails with a size limit error after upgrading:

Quick temporary fix (environment variable):

# Set to your required size in bytes (e.g., 100MB)
BAKED_FILE_SYSTEM_MAX_SIZE=104857600 crystal build your_app.cr

Recommended fix (per-folder limit):

module Assets
  extend BakedFileSystem

  # Set max_size to your required limit (in bytes)
  bake_folder "./assets", max_size: 104_857_600  # 100MB
end

What's New

Added

• Compile-time size validation and warnings for embedded files
• Stats class to track total and per-file compressed sizes
• ByteCounter IO wrapper for accurate size tracking during encoding
• Environment variable support for global size limits:
  • BAKED_FILE_SYSTEM_MAX_SIZE - Maximum total compressed size (default: 50MB)
  • BAKED_FILE_SYSTEM_WARN_THRESHOLD - Warning threshold for total size (default: 10MB)
• max_size parameter for bake_folder macro to set per-folder limits
• Automatic warnings for large individual files (>1MB compressed)
• Comprehensive examples demonstrating size validation features
• Detailed size reporting during compilation (file count, compression ratio)

Changed

• Size statistics are now always displayed during compilation

Why This Change?

This feature prevents accidental inclusion of huge files that bloat binary size. The default 50MB limit is generous for most use cases. You can configure limits per-project via environment variables or per-folder via the max_size parameter.

Error message example:

❌  ERROR: Total embedded size (75.2 MB) exceeds limit (50.0 MB)
    Reduce the number/size of embedded files or increase the limit.

Documentation

• Added "Size Management & Limits" section to README
• New examples/ directory with working demonstrations
• Comprehensive test coverage for size validation features
• Full details in CHANGELOG.md

---

Full Changelog: v0.11.0...v0.12.0

v0.11.0

• include_dotfiles to control presence of dotfiles in the loaded files. #53