Reformatting 100k+ BUILD Files at Google: The Story of Buildifier

The author, Laurent Le Brun, a developer of the Bazel build system (internally called Blaze), shares the challenges faced while creating and promoting a code‑formatting tool for BUILD files.

Key problems included handling comments, line splitting, preserving existing line breaks, ensuring the formatter does not break code, and scaling changes across a massive codebase.

Buildifier was developed to address these issues, always reformatting the entire file and providing limited line‑splitting logic. It attaches comments to nearby syntax‑tree nodes and retains certain line breaks in specific locations.

Testing involved comparing syntax trees, using Bazel Query to verify that reformatting did not affect Bazel's understanding of files, and leveraging Google's extensive test infrastructure despite the high computational cost.

The tool was integrated as a pre‑commit check, enforced uniformly across all engineers, and required no personal configuration, ensuring consistent formatting without exceptions.

Promotion efforts included defining a style guide, formalizing syntax, documenting safe list reordering, and embedding the formatter into major editors to format code on save.

Handling comments: Buildifier attaches them to nearby nodes.

Line splitting: Performed in hard‑coded cases without considering line length.

Preserving line breaks: Certain positions in the syntax tree retain original breaks.

Whole‑file reformatting: Buildifier always reformats the entire file.

Large‑scale changes were managed using a Google‑internal tool that splits massive diffs into smaller, independently commit‑able changes, with a global approver handling approvals across the repository.

The rollout was approved after a few days, and the impact was surprisingly mild—engineers largely accepted the new formatting rules without significant complaints.

Buildifier not only standardized BUILD file formatting but also enabled previously impossible enhancements in Bazel, facilitating migration from Python to Starlark and improving overall code maintenance.