schedule Published: October 17, 2024
update Last updated: October 17, 2024

Overview

FileBrowser Quantum v0.8.9 introduces a new, simplified conditional rules format. The old exclude/include configuration has been replaced with a unified conditionals structure that is more flexible and easier to maintain.

Quick Comparison

Here’s a side-by-side comparison of the old and new formats:

❌ Old Format (Pre v0.8.9)

sources:
  - path: "/data"
    config:
      exclude:
        folderPaths:
          - "excluded"
          - "backup"
        fileNames:
          - ".DS_Store"

✅ New Format (v0.8.9+)

sources:
  - path: "/data"
    config:
      conditionals:
        rules:
          - folderPath: "excluded"
          - folderPath: "backup"
          - fileNames: ".DS_Store"

Key Difference: Instead of arrays of strings grouped by type, each rule is now an individual object with specific properties.

What Changed?

Old Structure (Pre v0.8.9)

The old format used separate arrays for different exclusion/inclusion types:

server:
  sources:
    - path: "/data"
      config:
        exclude:
          hidden: true
          ignoreZeroSizeFolders: false
          filePaths:
            - "folder1/file.txt"
          folderPaths:
            - "excluded"
            - "backup"
          fileNames:
            - ".DS_Store"
          folderNames:
            - "@eadir"
          fileEndsWith:
            - ".tmp"

New Structure (v0.8.9+)

The new format uses a single rules array where each rule is an object:

server:
  sources:
    - path: "/data"
      config:
        conditionals:
          hidden: true
          ignoreZeroSizeFolders: false
          rules:
            - filePath: "folder1/file.txt"
            - folderPath: "excluded"
            - folderPath: "backup"
            - fileNames: ".DS_Store"
            - folderNames: "@eadir"
            - fileEndsWith: ".tmp"

Migration Examples

Example 1: Basic Folder Exclusion 

sources:
  - path: "/data"
    name: "storage"
    config:
      defaultEnabled: true
      exclude:
        folderPaths:
          - "excluded"
          - "temp"
          - "cache"
sources:
  - path: "/data"
    name: "storage"
    config:
      defaultEnabled: true
      conditionals:
        rules:
          - folderPath: "excluded"
          - folderPath: "temp"
          - folderPath: "cache"

Example 2: Hidden Files and Global Exclusions 

sources:
  - path: "/media"
    config:
      exclude:
        hidden: true
        fileNames:
          - ".DS_Store"
          - "Thumbs.db"
        folderNames:
          - "@eadir"
          - ".thumbnails"
sources:
  - path: "/media"
    config:
      conditionals:
        hidden: true
        rules:
          - fileNames: ".DS_Store"
          - fileNames: "Thumbs.db"
          - folderNames: "@eadir"
          - folderNames: ".thumbnails"

Example 3: Pattern-Based Exclusions 

sources:
  - path: "/documents"
    config:
      exclude:
        fileStartsWith:
          - "archive-"
          - "backup-"
        fileEndsWith:
          - ".tmp"
          - ".bak"
        folderEndsWith:
          - ".git"
          - ".cache"
sources:
  - path: "/documents"
    config:
      conditionals:
        rules:
          - fileStartsWith: "archive-"
          - fileStartsWith: "backup-"
          - fileEndsWith: ".tmp"
          - fileEndsWith: ".bak"
          - folderEndsWith: ".git"
          - folderEndsWith: ".cache"

Example 4: Include Rules (Root Items Only) 

sources:
  - path: "/shared"
    config:
      include:
        rootFolders:
          - "public"
          - "downloads"
        rootFiles:
          - "README.md"
sources:
  - path: "/shared"
    config:
      conditionals:
        rules:
          - includeRootItem: "public"
          - includeRootItem: "downloads"
          - includeRootItem: "README.md"

Example 5: Advanced Configuration 

sources:
  - path: "/projects"
    config:
      neverWatchPaths:
        - "large-archive"
        - "readonly-data"
      exclude:
        hidden: true
        ignoreZeroSizeFolders: true
        folderPaths:
          - "node_modules"
          - "build"
        fileEndsWith:
          - ".log"
sources:
  - path: "/projects"
    config:
      conditionals:
        hidden: true
        ignoreZeroSizeFolders: true
        rules:
          - neverWatchPath: "large-archive"
          - neverWatchPath: "readonly-data"
          - folderPath: "node_modules"
          - folderPath: "build"
          - fileEndsWith: ".log"

Example 6: Viewable but Not Indexed

The new format introduces the viewable property, which allows items to be visible in the UI but excluded from search indexing:

sources:
  - path: "/data"
    config:
      conditionals:
        rules:
          - folderPath: "excludedButVisible"
            viewable: true
          - folderPath: "/subfolders/archived"
            viewable: true

Complete Migration Reference

Old Format Properties → New Format Equivalents

Old PropertyNew PropertyNotes
exclude.filePaths[]rules[].filePathOne rule per path
exclude.folderPaths[]rules[].folderPathOne rule per path
exclude.fileNames[]rules[].fileNamesOne rule per name
exclude.folderNames[]rules[].folderNamesOne rule per name
exclude.fileEndsWith[]rules[].fileEndsWithOne rule per suffix
exclude.folderEndsWith[]rules[].folderEndsWithOne rule per suffix
exclude.fileStartsWith[]rules[].fileStartsWithOne rule per prefix
exclude.folderStartsWith[]rules[].folderStartsWithOne rule per prefix
exclude.hiddenconditionals.hiddenMoved up one level
exclude.ignoreZeroSizeFoldersconditionals.ignoreZeroSizeFoldersMoved up one level
neverWatchPaths[]rules[].neverWatchPathMoved into rules
include.rootFolders[]rules[].includeRootItemCombined with rootFiles
include.rootFiles[]rules[].includeRootItemCombined with rootFolders
(not available)rules[].viewableNew property

Migration Steps

Follow these steps to migrate your configuration:

  1. Backup your config file

    cp config.yaml config.yaml.backup

  2. Locate your sources in the config file

  3. For each source with exclude or include:

    • Replace exclude: or include: with conditionals:
    • Move hidden and ignoreZeroSizeFolders up one level (if present)
    • Create a rules: array
    • Convert each array entry into an individual rule object

  4. Convert neverWatchPaths:

    • Move from source-level to inside rules array
    • Create one neverWatchPath rule per entry

  5. Convert include.rootFolders and include.rootFiles:

    • Combine into single includeRootItem rules

  6. Test your configuration

    ./filebrowser config check config.yaml

Next Steps