Skip to main content
Beta
// Basic pattern search
const results = await repo.grep({
  query: { pattern: "TODO" },
});

console.log(`Found ${results.matches.length} files with matches`);
results.matches.forEach((match) => {
  console.log(`${match.path}:`);
  match.lines.forEach((line) => {
    if (line.type === "match") {
      console.log(`  ${line.lineNumber}: ${line.text}`);
    }
  });
});

// Advanced search with filtering and context
const advancedResults = await repo.grep({
  ref: "main",
  query: {
    pattern: "function\\s+\\w+Error",
    caseSensitive: true,
  },
  paths: ["src/"],
  fileFilters: {
    includeGlobs: ["**/*.js", "**/*.ts"],
    excludeGlobs: ["**/node_modules/**", "**/*.test.js"],
  },
  context: { before: 2, after: 2 },
  limits: { maxLines: 200, maxMatchesPerFile: 10 },
  pagination: { limit: 50 },
});

// Handle pagination
let cursor = advancedResults.nextCursor;
while (cursor && advancedResults.hasMore) {
  const moreResults = await repo.grep({
    query: { pattern: "TODO" },
    pagination: { cursor, limit: 50 },
  });
  console.log("Next page:", moreResults.matches);
  cursor = moreResults.nextCursor;
}

Options

Parameter (TS) / Parameter (Python)TypeDescription
query.pattern / patternRequiredRegular expression pattern to search for
query.caseSensitive / case_sensitiveOptionalWhether search should be case sensitive (default: true)
ref / refOptionalGit reference to search in (defaults to repository’s default branch)
paths / pathsOptionalArray/List of Git pathspecs to limit search scope
fileFilters.includeGlobs / file_filters.include_globsOptionalGlob patterns for files to include
fileFilters.excludeGlobs / file_filters.exclude_globsOptionalGlob patterns for files to exclude
fileFilters.extensionFilters / file_filters.extension_filtersOptionalFile extensions to filter by (e.g., ['.js', '.py'])
context.before / context.beforeOptionalNumber of lines to include before each match
context.after / context.afterOptionalNumber of lines to include after each match
limits.maxLines / limits.max_linesOptionalMaximum total lines to return (default: 2000, max: 2000)
limits.maxMatchesPerFile / limits.max_matches_per_fileOptionalMaximum matches per file (default: 200)
pagination.cursor / pagination.cursorOptionalPagination cursor from previous response
pagination.limit / pagination.limitOptionalMaximum results per page (default: 200)
N/A / ttlOptionalToken TTL in seconds (Python only)

Response

The grep response includes:
  • query: Echo of search parameters with resolved defaults
  • repo: Information about the searched ref and commit
  • matches: Array of files with matching lines
    • Each match contains path and lines array
    • TypeScript: Lines include lineNumber, text, and type ('match' or 'context')
    • Python: Lines include line_number, text, and type ('match' or 'context')
  • TypeScript: hasMore and nextCursor for pagination
  • Python: has_more and next_cursor for pagination