comby

Find and replace code patterns

TLDR

Match and rewrite templates, and print changes

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

Match and rewrite with rewrite properties

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

Match and rewrite in-place

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

Only perform matching and print matches

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

SYNOPSIS

comby [options] -- match-template rewrite-template [path...]
or comby -r 'rule' [path...]

    Rewrite files recursively in directory

--dry-run
    Show diffs without writing changes

-i, --in-place
    Rewrite files in place (implies backup)

-l, --language
    Specify parser language (auto-detects otherwise)

--limit
    Limit matches/rewrites per file to n

--match-all
    Match all occurrences (default is first)

--match-first
    Match only first occurrence per function/top-level

--null
    Use null delimiter for paths (for xargs)

--only
    Rewrite only matching paths

-p, --prefix
    Prepend directory to paths

-r, --rule
    Single rule string: match:rewrite

--read-stdin-from-filename
    Filename for stdin parsing

--regex
    Treat templates as regex (less safe)

-s, --selector
    File selector expression

--stdin
    Read input from stdin

--timeout
    Timeout per file in seconds

-v, --verbose
    Verbose output

--unsafe
    Disable safety checks (dangerous)

DESCRIPTION

Comby is a fast, precise tool for searching and refactoring code using structural patterns rather than plain text. It supports over 50 programming languages via tree-sitter parsers or custom matchers, enabling syntax-aware matches that respect code structure. Define patterns with holes like id for identifiers or exp for expressions, capture groups, and rewrite using captures for safe transformations.

Ideal for large-scale refactors like API updates, style fixes, or migrations. Unlike sed or grep, comby avoids false positives by parsing ASTs. Process files, directories, or stdin with dry-run previews. Patterns are concise: e.g., 'fun _ -> ' matches functions ignoring names.

Output shows unified diffs; apply with -i. Verbose mode and limits aid debugging. Open-source, lightweight binary.

CAVEATS

Not in standard repos; install via brew/opam/cargo. Patterns require learning syntax. Large files may timeout without --timeout. Unsafe mode risks syntax errors.

PATTERN SYNTAX

Holes: id (identifier), exp (expression), ... (multi-hole). Captures: (name: hole). Literals in single-quotes. See comby -h template.

EXAMPLE

comby --dry-run 'let = ' 'let () = ()' *.ml
Replaces let-bindings with unit functions, showing diff.

HISTORY

Created by rgrinberg in 2020 as comby-tools/comby on GitHub. Evolved from OCaml prototype to Rust-based with tree-sitter (v1.2+). Gained popularity for OCaml refactors; now widely used for JS/Rust/Python. Active development with v1.9+ adding selectors and safety.