comby

Match and rewrite templates, and print changes

$ comby '[assert_eq!(:[a], :[b])]' '[assert_eq!(:[b], :[a])]' [.rs]

$ comby '[assert_eq!(:[a], :[b])]' '[assert_eq!(:[b].Capitalize, :[a])]' [.rs]

$ comby -in-place '[match_pattern]' '[rewrite_pattern]'

$ comby -match-only '[match_pattern]' ""

comby [OPTIONS] <MATCH_PATTERN> <REWRITE_PATTERN> [PATH...]
comby [OPTIONS] -f <PATTERN_FILE> [PATH...]
STDIN | comby [OPTIONS] <MATCH_PATTERN> <REWRITE_PATTERN>

-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.

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.

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.

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.

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.

grep(1), sed(1), awk(1), find(1), rg(1), ast-grep