Anurag’s Read

Formatting an entire 25 million line codebase overnight: the rubyfmt story.

A long, honest story of building a zero-config formatter, with real performance limits, a Ruby-to-Rust rewrite, and a careful big-bang rollout. Engineers learn how to prepare for a change that touches every file.
Score
8.5
Verdict
Must read
Blog and date
Stripe,
Original length and level
13 min, advanced
Topics
developer tooling, rust, ruby, migrations
Read the original

Context

Stripe has a very large Ruby monorepo, 25 million lines in 2024. No true Ruby autoformatter existed. The rubocop tool is a linter with many settings that move style debates into config files. The prettier-ruby tool was slow and crashed on large files. The goal was a zero-configuration tool like gofmt that runs fast enough for format on save.

Architecture

The rubyfmt tool parses Ruby source and prints formatted code. The first version was a Ruby program built on ripper, the parser API based on parse.y. A large dispatch table mapped each expression type to a handler lambda. The current version is a Rust binary. It embeds Ruby source with include_str and eval_str, and it links the Ruby VM to call ripper. Rust walks the parse tree through a serde Deserializer and builds typed structs.

In 2025 the team moved to Prism, which builds trees without the VM.

Mechanisms

M1

Speed budget

Plain Ruby started in about 158ms, and about 345ms under bundler. The budget was 100ms for most files. The first fix was a hand-written C program compiled against libruby. The pure Ruby version shipped as one concatenated file with gems disabled, but it still passed 100ms on moderate files.

M2

Rust tree reader

The first Rust draft turned the ripper tree into JSON and read it with serde. JSON was too slow. The author wrote a serde Deserializer that walks Ruby VALUEs in memory. It checks type tags such as symbol, string, array, nil, and fixnum, and calls the visitor. A def_tag macro built the node structs, so the schema stayed the same.

M3

Safe rollout

A bug in 0.01% of lines would still touch tens of thousands of files. Files first opted in one by one. A tool compared ripper trees before and after formatting and allowed expected changes such as quote style. Stripe's test suite ran too. Then the team excluded only files that rubyfmt could not handle. They formatted all 62,213 files on one Saturday to avoid merge conflicts.

M4

Prism migration

The toolchain became switchable between parsers. The full test suite ran on both, with Prism tests first marked as expected failures. The team fixed failures until both parsers gave identical output. Then it deleted the serde code, which made the binary smaller and faster.

Design decisions

No.ChoseInstead ofWhy
D1No configuration at allrubocopIt is a linter with many settings, and the goal was one style decided by the tool.
D2Rewrite in RustPure Ruby on ripperRuby missed the 100ms budget for moderately complex files.
D3Read Ruby VALUEs directly in memoryJSON through serdeJSON serialization cost dominated the run time.
D4Format the whole repo in one Saturday after an opt-in phaseA gradual per-file rollout to the endOne change avoids long merge conflicts.

Key numbers

  • The 2024 rollout covered 25 million lines. Today 42 million lines of Ruby are formatted.
  • The rollout touched 62,213 files.
  • Ruby startup took 158ms plain and 345ms under bundler, against a 100ms budget.
  • A 0.01% bug rate would still affect tens of thousands of files.

Failures and limits

  • No Rust Ruby parser existed without the VM, so the build compiled and linked Ruby, which made builds complex. Walking VALUEs was unusual and fragile.
  • The diff was too large for GitHub to render. The post gives no speed figure for Prism.

Lessons you can use

  • Set a latency budget first and measure each rewrite against it. Use a tree diff to check that a formatter keeps program meaning.
  • Start with opt-in, then flip the default once few exceptions remain. Remove native dependencies when an official parser makes them unneeded.

Glossary

ripperThe Ruby standard library parser API that returns syntax trees.
PrismThe official Ruby parser that runs without the Ruby VM.
serdeA Rust library that maps data formats to typed structs.
VALUEThe C type that represents any Ruby object in memory.