gosimilarity

README

gosimilarity

gosimilarity is a Go code similarity tool inspired by mizchi/similarity. It finds structurally similar functions, methods, and type declarations to help identify refactoring opportunities, even when local variable names differ.

Use readable terminal reports to explore matches, or JSON output for scripts and agents.

Installation

Install with Homebrew on macOS or Linux:

brew install Songmu/tap/gosimilarity

Install with Go using the version required by go.mod or later:

go install github.com/Songmu/gosimilarity/cmd/gosimilarity@latest

Or download a prebuilt binary from GitHub Releases. The installer selects the appropriate binary for your platform and installs it into ./bin by default:

curl -sfL https://raw.githubusercontent.com/Songmu/gosimilarity/main/install.sh | sh -s
./bin/gosimilarity --version

To choose an installation directory, pass -b; append a release tag to select a specific version:

curl -sfL https://raw.githubusercontent.com/Songmu/gosimilarity/main/install.sh | sh -s -- -b "$HOME/.local/bin"

Make sure your installation directory is on PATH when using the commands below.

Quick start

Scan the current directory for similar functions and methods:

gosimilarity .

Matches include their similarity, ranking score, and source locations:

Similarity: 100.00%, Score: 3.0 points [function]
  first.go:3-5 Load
  second.go:3-5 Read
  nodes: 5 / 5

The default similarity threshold is 0.87 (87%), and functions must span at least three lines. Narrow the search or inspect the matching source:

gosimilarity ./cmd ./internal --cross-file-only
gosimilarity . --threshold 0.95 --min-lines 10 --print
gosimilarity . --exclude 'internal/legacy/**' --include-tests

To inspect only files selected by Go's build constraints, use package patterns:

gosimilarity --packages ./...
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 gosimilarity --packages --tags=netgo ./...

Package mode requires Go on PATH. Use . for one package or ./... for recursive selection; see package selection for details.

Type declarations are opt-in:

gosimilarity . --types         # Functions, methods, and types
gosimilarity . --no-functions  # Types only

Scripts and CI

Write a single JSON report to stdout; diagnostics go to stderr:

gosimilarity . --format json > similarity.json

To fail CI when matches are found:

gosimilarity . --fail-on-duplicates

By default, matches do not cause failure. Exit codes are 0 for a complete inspection, 1 for matches with --fail-on-duplicates, and 2 for invalid arguments or an incomplete inspection. See the CLI reference for all options, file selection rules, and the JSON format.

Interpreting results

• A 100% match means identical normalized syntax, not equivalent behavior or a guarantee that the code can safely be merged. Review matches before refactoring.
• Analysis does not build the project or perform type checking. Default file discovery does not fetch dependencies and inspects source regardless of build tags; --packages delegates file selection to the Go command.
• Directory scans skip tests, generated files, vendor, and symlinks by default, and respect Git ignores in Git working trees. Use --include-tests to include tests, or name individual files explicitly.
• Large scans can produce many comparisons and matches. Restrict paths, raise --min-lines, or use --exclude to focus on useful candidates.

Contributing

See CONTRIBUTING.md for build, test, and development commands.

License

MIT

Author

Songmu

Documentation

Index

• func Run(ctx context.Context, argv []string, outStream, errStream io.Writer) error

Functions

func Run

func Run(ctx context.Context, argv []string, outStream, errStream io.Writer) error

Run finds structurally similar Go declarations and writes text or JSON. Errors expose ExitCode() int: 1 for requested duplicate failure, 2 for invalid arguments or an incomplete inspection. Help returns flag.ErrHelp.