or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

configuration-options.md core-operations.md index.md pattern-utilities.md task-management.md

tile.json

Configuration Options

Comprehensive configuration system controlling matching behavior, output format, performance tuning, and file system interaction. Options provide fine-grained control over glob operations to handle diverse use cases and environments.

Capabilities

Options Interface

Complete configuration interface with all available options organized by category.

interface Options {
  // Common options
  concurrency?: number;
  cwd?: string;
  deep?: number;
  followSymbolicLinks?: boolean;
  fs?: Partial<FileSystemAdapter>;
  ignore?: string[];
  suppressErrors?: boolean;
  throwErrorOnBrokenSymbolicLink?: boolean;
  
  // Output control options
  absolute?: boolean;
  markDirectories?: boolean;
  objectMode?: boolean;
  onlyDirectories?: boolean;
  onlyFiles?: boolean;
  stats?: boolean;
  unique?: boolean;
  
  // Matching control options
  braceExpansion?: boolean;
  caseSensitiveMatch?: boolean;
  dot?: boolean;
  extglob?: boolean;
  globstar?: boolean;
  baseNameMatch?: boolean;
}

Common Options

Core options controlling basic glob operation behavior and performance.

Concurrency Control

Control the number of concurrent file system operations for performance tuning.

interface Options {
  /**
   * Maximum number of concurrent requests from reader to read directories
   * @default os.cpus().length
   */
  concurrency?: number;
}

Usage Examples:

// High performance (more concurrent operations)
const files = await fg('**/*.js', { concurrency: 16 });

// Conservative (fewer concurrent operations, less system load)
const files = await fg('**/*.js', { concurrency: 2 });

// Single-threaded (minimal system impact)
const files = await fg('**/*.js', { concurrency: 1 });

Working Directory

Set the starting directory for pattern matching operations.

interface Options {
  /**
   * Current working directory in which to search
   * @default process.cwd()
   */
  cwd?: string;
}

Usage Examples:

// Search within specific directory
const srcFiles = await fg('**/*.ts', { cwd: './src' });

// Search in sibling directory
const testFiles = await fg('**/*.spec.js', { cwd: '../tests' });

// Absolute path as working directory
const libFiles = await fg('**/*.js', { cwd: '/usr/local/lib/myapp' });

Traversal Depth Limit

Control maximum directory traversal depth to prevent excessive nesting.

interface Options {
  /**
   * Maximum depth of directory traversal relative to start directory
   * @default Infinity
   */
  deep?: number;
}

Usage Examples:

// Limit to 2 levels deep: ./src/components but not ./src/components/ui/buttons
const files = await fg('**/*.js', { deep: 2 });

// Only immediate children (depth 1)
const topLevel = await fg('*/*.js', { deep: 1 });

// No depth limit (default)
const allFiles = await fg('**/*.js', { deep: Infinity });

Symbolic Link Handling

Control whether to follow symbolic links during traversal.

interface Options {
  /**
   * Whether to traverse descendants of symbolic link directories
   * @default true
   */
  followSymbolicLinks?: boolean;
  
  /**
   * Throw error when symbolic link is broken
   * @default false
   */
  throwErrorOnBrokenSymbolicLink?: boolean;
}

Usage Examples:

// Don't follow symbolic links (safer, prevents loops)
const files = await fg('**/*.js', { followSymbolicLinks: false });

// Follow symlinks but throw on broken ones
const files = await fg('**/*.js', { 
  followSymbolicLinks: true,
  throwErrorOnBrokenSymbolicLink: true 
});

Custom File System

Provide custom file system implementation for testing or special environments.

interface Options {
  /**
   * Custom implementation of file system methods
   * @default Node.js fs methods
   */
  fs?: Partial<FileSystemAdapter>;
}

interface FileSystemAdapter {
  lstat: typeof fs.lstat;
  lstatSync: typeof fs.lstatSync;
  stat: typeof fs.stat;
  statSync: typeof fs.statSync;
  readdir: typeof fs.readdir;
  readdirSync: typeof fs.readdirSync;
}

Usage Examples:

import { Volume } from 'memfs';

// Use in-memory file system for testing
const vol = Volume.fromJSON({
  './test.js': 'console.log("test");',
  './src/index.js': 'module.exports = {};'
});

const files = await fg('**/*.js', {
  fs: {
    lstat: vol.lstat.bind(vol),
    lstatSync: vol.lstatSync.bind(vol),
    stat: vol.stat.bind(vol),
    statSync: vol.statSync.bind(vol),
    readdir: vol.readdir.bind(vol),
    readdirSync: vol.readdirSync.bind(vol)
  }
});

Pattern Exclusions

Additional patterns to ignore during matching.

interface Options {
  /**
   * Array of glob patterns to exclude matches
   * Alternative to negative patterns in main pattern list
   * @default []
   */
  ignore?: string[];
}

Usage Examples:

// Ignore patterns via options
const files = await fg('**/*.js', {
  ignore: ['node_modules/**', '**/*.test.js', 'dist/**']
});

// Equivalent using negative patterns
const files = await fg([
  '**/*.js',
  '!node_modules/**',
  '!**/*.test.js', 
  '!dist/**'
]);

Error Handling

Control error suppression and handling behavior.

interface Options {
  /**
   * Suppress all errors during traversal
   * By default only ENOENT errors are suppressed
   * @default false
   */
  suppressErrors?: boolean;
}

Usage Examples:

// Suppress all errors (continue on permission denied, etc.)
const files = await fg('**/*.js', { suppressErrors: true });

// Default behavior (only suppress ENOENT - file not found)
const files = await fg('**/*.js', { suppressErrors: false });

Output Control Options

Options controlling the format and content of returned results.

Path Format

Control whether returned paths are absolute or relative.

interface Options {
  /**
   * Return absolute paths for entries
   * @default false
   */
  absolute?: boolean;
}

Usage Examples:

// Relative paths (default)
const relative = await fg('**/*.js');
// ['src/index.js', 'lib/utils.js']

// Absolute paths
const absolute = await fg('**/*.js', { absolute: true });
// ['/full/path/to/src/index.js', '/full/path/to/lib/utils.js']

Directory Marking

Add trailing slashes to directory entries for easy identification.

interface Options {
  /**
   * Mark directory paths with final slash
   * @default false
   */
  markDirectories?: boolean;
}

Usage Examples:

// Mark directories with trailing slash
const entries = await fg('**/*', { 
  markDirectories: true,
  onlyDirectories: false 
});
// ['src/', 'lib/', 'src/index.js', 'lib/utils.js']

Object Mode

Return detailed Entry objects instead of simple strings.

interface Options {
  /**
   * Return Entry objects instead of strings
   * @default false
   */
  objectMode?: boolean;
  
  /**
   * Include fs.Stats in Entry objects (implies objectMode: true)
   * @default false
   */
  stats?: boolean;
}

Usage Examples:

// Object mode
const entries = await fg('**/*.js', { objectMode: true });
// [{ name: 'index.js', path: '/full/path/src/index.js', dirent: Dirent }]

// With file stats
const entriesWithStats = await fg('**/*.js', { stats: true });
// [{ name: 'index.js', path: '/path', dirent: Dirent, stats: Stats }]

Entry Type Filtering

Control whether to return files, directories, or both.

interface Options {
  /**
   * Return only directories
   * @default false
   */
  onlyDirectories?: boolean;
  
  /**
   * Return only files
   * @default true
   */
  onlyFiles?: boolean;
}

Usage Examples:

// Only files (default)
const files = await fg('**/*', { onlyFiles: true });

// Only directories
const dirs = await fg('**/*', { onlyDirectories: true });

// Both files and directories
const all = await fg('**/*', { 
  onlyFiles: false, 
  onlyDirectories: false 
});

Result Deduplication

Control whether to remove duplicate entries from results.

interface Options {
  /**
   * Ensure returned entries are unique
   * @default true
   */
  unique?: boolean;
}

Usage Examples:

// Unique results (default) - duplicates removed
const unique = await fg(['**/*.js', 'src/**/*.js']);

// Allow duplicates
const withDupes = await fg(['**/*.js', 'src/**/*.js'], { unique: false });

Matching Control Options

Options controlling pattern matching behavior and glob feature support.

Brace Expansion

Enable or disable brace expansion in patterns.

interface Options {
  /**
   * Enable Bash-like brace expansion
   * @default true
   */
  braceExpansion?: boolean;
}

Usage Examples:

// Brace expansion enabled (default)
const files = await fg('*.{js,ts,json}'); // Expands to *.js, *.ts, *.json

// Brace expansion disabled
const literal = await fg('*.{js,ts,json}', { braceExpansion: false });
// Searches for literal filename "*.{js,ts,json}"

Case Sensitivity

Control case-sensitive pattern matching.

interface Options {
  /**
   * Enable case-sensitive mode for matching files
   * @default true
   */
  caseSensitiveMatch?: boolean;
}

Usage Examples:

// Case sensitive (default)
const files = await fg('*.JS'); // Only matches *.JS, not *.js

// Case insensitive
const files = await fg('*.JS', { caseSensitiveMatch: false });
// Matches *.js, *.JS, *.Js, etc.

Dotfile Matching

Control whether patterns match files beginning with dots.

interface Options {
  /**
   * Allow patterns to match entries beginning with period (.)
   * @default false
   */
  dot?: boolean;
}

Usage Examples:

// Exclude dotfiles (default)
const files = await fg('*'); // Doesn't match .gitignore, .env

// Include dotfiles
const files = await fg('*', { dot: true }); // Matches .gitignore, .env

Extended Glob Support

Enable extended glob patterns like !(pattern), @(pattern), etc.

interface Options {
  /**
   * Enable Bash-like extended glob functionality
   * @default true
   */
  extglob?: boolean;
}

Usage Examples:

// Extended globs enabled (default)
const files = await fg('!(node_modules)/**/*.js'); // Everything except node_modules

// Extended globs disabled
const files = await fg('!(node_modules)/**/*.js', { extglob: false });
// Treats !(...) as literal characters

Globstar Support

Control whether ** behaves as globstar or regular *.

interface Options {
  /**
   * Enable recursive repeats of pattern containing **
   * If false, ** behaves exactly like *
   * @default true
   */
  globstar?: boolean;
}

Usage Examples:

// Globstar enabled (default)
const files = await fg('**/*.js'); // Recursively searches all subdirectories

// Globstar disabled
const files = await fg('**/*.js', { globstar: false });
// ** behaves like *, searches only immediate subdirectories

Base Name Matching

Enable matching against file basename for patterns without slashes.

interface Options {
  /**
   * Match patterns without slashes against basename if path contains slashes
   * @default false
   */
  baseNameMatch?: boolean;
}

Usage Examples:

// Base name matching disabled (default)
const files = await fg('index.js'); // Only matches ./index.js

// Base name matching enabled
const files = await fg('index.js', { baseNameMatch: true });
// Matches ./index.js, ./src/index.js, ./lib/components/index.js

Option Combinations

Common Configuration Patterns

// Development build file gathering
const devFiles = await fg(['src/**/*.{js,ts}', '!**/*.test.*'], {
  absolute: true,
  dot: false,
  onlyFiles: true
});

// Production file analysis with stats
const prodFiles = await fg('dist/**/*', {
  stats: true,
  onlyFiles: true,
  suppressErrors: true
});

// Directory structure analysis
const structure = await fg('**/*', {
  objectMode: true,
  markDirectories: true,
  onlyFiles: false,
  deep: 3
});

// Safe user input handling
function findUserFiles(userPattern: string, userDir: string) {
  return fg(userPattern, {
    cwd: userDir,
    dot: false,
    followSymbolicLinks: false,
    suppressErrors: true,
    deep: 10
  });
}

Version

Tile

Files