or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

ignore-handling.md index.md main-globbing.md utilities.md

tile.json

Ignore File Handling

Integration with .gitignore and custom ignore file formats for excluding files from glob results. This functionality allows globby to respect project ignore patterns and provide filtering capabilities.

Capabilities

Git Ignore Functions

Functions for creating filter functions that respect .gitignore patterns.

/**
 * Create a filter function for .gitignore patterns (async)
 * @param options - Configuration options
 * @returns Promise resolving to filter function
 */
function isGitIgnored(options?: GitignoreOptions): Promise<GlobbyFilterFunction>;

/**
 * Create a filter function for .gitignore patterns (sync)
 * @param options - Configuration options
 * @returns Filter function
 */
function isGitIgnoredSync(options?: GitignoreOptions): GlobbyFilterFunction;

Usage Examples:

import { isGitIgnored, isGitIgnoredSync } from "globby";

// Async usage
const isIgnored = await isGitIgnored();
console.log(isIgnored('node_modules/package/file.js')); // true
console.log(isIgnored('src/main.js')); // false

// With custom cwd
const isIgnoredCustom = await isGitIgnored({ cwd: '/path/to/project' });

// Sync usage
const isIgnoredSync = isGitIgnoredSync({ cwd: process.cwd() });
console.log(isIgnoredSync('dist/bundle.js')); // true (if in .gitignore)

Custom Ignore Files

More generic ignore file handling that works with any ignore file format compatible with .gitignore syntax.

/**
 * Create a filter function for custom ignore files (async)
 * @param patterns - Glob patterns to find ignore files
 * @param options - Configuration options
 * @returns Promise resolving to filter function
 */
function isIgnoredByIgnoreFiles(
  patterns: string | readonly string[],
  options?: Options
): Promise<GlobbyFilterFunction>;

/**
 * Create a filter function for custom ignore files (sync)
 * @param patterns - Glob patterns to find ignore files
 * @param options - Configuration options
 * @returns Filter function
 */
function isIgnoredByIgnoreFilesSync(
  patterns: string | readonly string[],
  options?: Options
): GlobbyFilterFunction;

Usage Examples:

import { isIgnoredByIgnoreFiles, isIgnoredByIgnoreFilesSync } from "globby";

// Check against .prettierignore files
const isPrettierIgnored = await isIgnoredByIgnoreFiles('**/.prettierignore');
console.log(isPrettierIgnored('dist/bundle.min.js')); // true

// Multiple ignore file types
const isIgnored = await isIgnoredByIgnoreFiles([
  '**/.gitignore',
  '**/.eslintignore',
  '**/.prettierignore',
]);

// Sync version
const isIgnoredSync = isIgnoredByIgnoreFilesSync('**/.dockerignore');

// With options
const isIgnoredCustom = await isIgnoredByIgnoreFiles(
  ['**/.babelignore'],
  { cwd: '/path/to/project' }
);

Integration with Main API

The ignore functionality integrates seamlessly with the main globbing functions through options:

import { globby } from "globby";

// Using gitignore option
const trackedFiles = await globby(['**/*'], { 
  gitignore: true 
});

// Using custom ignore files
const lintableFiles = await globby(['**/*.js'], {
  ignoreFiles: ['**/.eslintignore']
});

// Multiple ignore file patterns
const buildableFiles = await globby(['src/**/*'], {
  ignoreFiles: [
    '**/.gitignore',
    '**/.buildignore',
    '**/ignore.txt'
  ]
});

Ignore File Syntax

All ignore functions support the standard .gitignore syntax:

Comments: Lines starting with # are ignored
Negation: Lines starting with ! negate the pattern
Directory matching: Patterns ending with / match directories only
Relative paths: Patterns are relative to the ignore file location
Glob patterns: Standard glob syntax is supported

Example .gitignore:

# Dependencies
node_modules/
*.log

# Build outputs
dist/
build/
*.min.js

# Environment files
.env
.env.local

# But include important configs
!webpack.config.js
!.env.example

Constants

/**
 * Default pattern for finding .gitignore files
 * @example
 * import { GITIGNORE_FILES_PATTERN, isIgnoredByIgnoreFiles } from 'globby';
 * 
 * const isIgnored = await isIgnoredByIgnoreFiles(GITIGNORE_FILES_PATTERN);
 */
export const GITIGNORE_FILES_PATTERN: '**/.gitignore';

Types

/**
 * Filter function type returned by ignore functions
 */
type GlobbyFilterFunction = (path: URL | string) => boolean;

/**
 * Options for gitignore functions
 */
interface GitignoreOptions {
  /** Current working directory */
  readonly cwd?: URL | string;
}

Advanced Usage

Combining Multiple Ignore Sources

import { globby, isGitIgnored, isIgnoredByIgnoreFiles } from "globby";

// Create combined filter
const [gitIgnored, eslintIgnored] = await Promise.all([
  isGitIgnored(),
  isIgnoredByIgnoreFiles('**/.eslintignore')
]);

const allFiles = await globby(['**/*.js']);
const filteredFiles = allFiles.filter(file => 
  !gitIgnored(file) && !eslintIgnored(file)
);

Custom Ignore Processing

import { globbyStream, isGitIgnoredSync } from "globby";

const isIgnored = isGitIgnoredSync();

for await (const file of globbyStream(['**/*'])) {
  if (!isIgnored(file)) {
    console.log('Processing:', file);
    // Process non-ignored file
  }
}

Error Handling

The ignore functions handle common error scenarios gracefully:

Missing ignore files are silently skipped
Invalid ignore file syntax is logged but doesn't stop processing
Permission errors on ignore files are handled based on suppressErrors option

import { isIgnoredByIgnoreFiles } from "globby";

try {
  const isIgnored = await isIgnoredByIgnoreFiles('**/.gitignore', {
    suppressErrors: false // Will throw on errors
  });
} catch (error) {
  console.error('Failed to read ignore files:', error);
}