glob - Find Files

Overview

The glob tool efficiently finds files matching specific glob patterns (e.g., src/**/*.ts, **/*.md), returning absolute paths sorted by modification time (newest first). Ideal for quickly locating files based on their name or path structure, especially in large codebases.

Tool Name

• Internal Name: glob
• Display Name: FindFiles
• Icon: FileSearch

Parameters

Required Parameters

Parameter	Type	Description
pattern	string	The glob pattern to match against (e.g., **/*.py, docs/*.md).

Optional Parameters

Parameter	Type	Description
path	string	The absolute path to the directory to search within. If omitted, searches the root directory.
case_sensitive	boolean	Whether the search should be case-sensitive. Defaults to false.
respect_git_ignore	boolean	Whether to respect .gitignore patterns when finding files. Only available in git repositories. Defaults to true.

Features

1. Glob Pattern Matching:

   • Supports standard glob syntax
   • Can match filenames and paths
   • Supports multi-level directory matching

2. Sorting:

   • Sorted by modification time (newest first)
   • Recently modified files appear first
   • Older files sorted alphabetically

3. Filtering:

   • Optional .gitignore respect
   • Case-sensitive/insensitive search support
   • Automatically excludes common ignore directories

4. Performance Optimization:

   • Efficient filesystem traversal
   • Suitable for large codebases
   • Fast file location

Glob Pattern Syntax

Basic Wildcards

• *: Matches any characters (excluding directory separator)
  • Example: *.js matches all JavaScript files
• **: Matches any characters (including directory separator)
  • Example: src/**/*.ts matches all TypeScript files under src
• ?: Matches a single character
  • Example: file?.txt matches file1.txt, fileA.txt, etc.
• [abc]: Matches any character in brackets
  • Example: file[123].txt matches file1.txt, file2.txt, file3.txt
• {a,b}: Matches any pattern in braces
  • Example: *.{js,ts} matches all .js and .ts files

Common Pattern Examples

**/*.ts          # All TypeScript files
src/**/*.test.js # All test files under src
docs/*.md        # Markdown files in docs directory
**/*config*.json # All JSON files containing 'config'
lib/**/*.{js,ts} # All JS and TS files under lib

Usage Examples

Find All TypeScript Files

{
  "pattern": "**/*.ts"
}

Search in Specific Directory

{
  "pattern": "*.md",
  "path": "/home/user/project/docs"
}

Case-Sensitive Search

{
  "pattern": "**/*.Test.ts",
  "case_sensitive": true
}

Ignore .gitignore Rules

{
  "pattern": "**/*.log",
  "respect_git_ignore": false
}

Find Multiple File Types

{
  "pattern": "**/*.{js,ts,jsx,tsx}"
}

Return Value

The tool returns an object containing:

• llmContent: List of absolute paths to matching files
• returnDisplay: User-friendly display information
• summary: Operation summary (e.g., "Found 25 files matching pattern")

Return Format

Found 3 file(s) matching "**/*.ts":
/home/user/project/src/main.ts (modified: 2024-01-15)
/home/user/project/src/utils.ts (modified: 2024-01-14)
/home/user/project/src/types.ts (modified: 2024-01-10)

Error Handling

Possible error scenarios:

1. Path Errors:

   • Search path does not exist
   • Search path is not a directory
   • Search path is outside project root

2. Pattern Errors:

   • Pattern is empty or invalid
   • Pattern syntax error

3. Parameter Errors:

   • Missing required parameters
   • Incorrect parameter types

Sorting Rules

Files are sorted by the following rules:

1. Recent Files First:

   • Files modified within recent threshold (default 30 days)
   • Sorted by modification time, newest to oldest

2. Older Files Alphabetically:

   • Files beyond recent threshold
   • Sorted alphabetically by path

Performance Considerations

1. Large Codebases:

   • Tool is optimized for large codebases
   • Uses efficient filesystem traversal

2. Pattern Complexity:

   • Simple patterns (like *.js) are faster than complex ones
   • ** wildcard recursively searches all subdirectories

3. Ignore Rules:

   • Respecting .gitignore can improve performance
   • Automatically skips common large directories (node_modules, etc.)

Notes

1. Path Format: Returned paths are always absolute
2. Symbolic Links: Does not follow symbolic links by default
3. Hidden Files: Includes hidden files (starting with .) by default
4. Permissions: Requires read permission for directories

Differences from Other Tools

• vs list_directory: glob supports recursive search and pattern matching, list_directory only lists a single directory
• vs search_file_content: glob searches by filename/path, search_file_content searches by file content

Related Tools

• list_directory: List directory contents
• search_file_content: Search file content
• read_file: Read file
• read_many_files: Read multiple files in batch