comby
Find and replace code patterns
TLDR
Match and rewrite templates, and print changes
Match and rewrite with rewrite properties
Match and rewrite in-place
Only perform matching and print matches
SYNOPSIS
comby [OPTIONS] <MATCH_PATTERN> <REWRITE_PATTERN> [PATH...]
comby [OPTIONS] -f <PATTERN_FILE> [PATH...]
STDIN | comby [OPTIONS] <MATCH_PATTERN> <REWRITE_PATTERN>
PARAMETERS
-r, --recursive
Process files in directories recursively.
-f, --file <PATH>
Specify a file containing the MATCH_PATTERN and REWRITE_PATTERN.
--in-place
Modify files in place. Use with caution and version control.
--json
Output results as JSON, providing structured data for programmatic use.
-d, --directories <LIST>
A comma-separated list of directories to search within.
-e, --extensions <LIST>
A comma-separated list of file extensions to include (e.g., .js,.ts,.go).
-s, --stdin
Read input from standard input (stdin).
--match-only
Only show matched regions; do not perform rewriting.
--diff
Show a diff of the proposed changes without applying them.
--review
Interactively review and approve each change before applying.
--count
Print the number of matches found.
DESCRIPTION
comby is a powerful, syntax-aware code search and rewrite tool designed for large-scale refactoring and code transformations. Unlike traditional regular expression tools like grep or sed, comby understands code structure, allowing it to match and rewrite code based on its abstract syntax rather than just raw text. This makes it highly effective for performing complex, language-agnostic code modifications. It uses a flexible pattern-matching language that supports "holes" (e.g., :[_]
, :[x]
) to capture arbitrary code fragments, which can then be reused in the rewrite pattern. comby can process multiple files and directories, supports in-place modifications, and can output structured JSON results. Its primary use cases include refactoring codebases, applying codemods, migrating APIs, and enforcing coding standards across projects.
CAVEATS
While comby offers powerful structural matching, its syntax-aware capabilities are heuristic and do not rely on full, formal AST parsers for every language. This means it might occasionally misinterpret highly complex or ambiguous code constructs. Learning the comby pattern syntax, especially the nuances of "holes," requires a slight learning curve compared to basic regex. For very large codebases or extremely intricate patterns, performance can be a consideration, although it is generally highly optimized. Always test changes on a version-controlled codebase and consider using the --diff or --review flags before applying --in-place modifications.
<I>HOLES SYNTAX</I>
comby employs a specific syntax for "holes" in its patterns to capture arbitrary code fragments. Common hole types include :[_]
(any single expression or statement), :[x]
(a named hole that can be reused in the rewrite pattern), :[*]
(zero or more expressions/statements), and :[*x]
(zero or more named expressions/statements). This flexible mechanism allows for highly powerful and precise structural matching and rewriting.
HISTORY
comby was developed by Rémy Goldschmidt and first released around 2018. It emerged as a response to the limitations of traditional regex-based tools when refactoring large codebases, where changes often need to respect code structure rather than just raw text. Its design prioritizes speed and the ability to operate across multiple programming languages without requiring specific language parsers, instead relying on robust heuristic parsing. Its development was driven by the need for a practical, fast tool for applying "codemods" and performing structural transformations efficiently.