Igor's corner

Should dart generated files be commited into VCS

Published on

So you’ve installed Riverpod, Freezed, or Drift, ran the code generation for the first time, and noticed a bunch of new files with .g.dart or .freezed.dart appearing. Now you’re wondering: Should I commit these files to version control?

Unfortunately, there is no “one size fits all” answer. The short version is: If you aren’t sure, you should commit them. However, there are specific circumstances where you might choose not to.

Why Dart is Different

Unlike some languages that generate hidden bytecode or binary files (which should always be ignored), Dart code generators produce actual .dart source code that your application relies on to compile. For your app to function, these files must exist. If you choose not to commit them, either your CI/CD pipeline or every developer who pulls your code will have to generate them manually.

The Case for Committing (The Default Path)

If you are building a Library, you must include the generated code; otherwise, users cannot use your package. For Applications, committing is generally preferred for several reasons:

  1. Reliability: It prevents “bugs” caused by version mismatches. If the build machine has a different version of Flutter or build_runner than your local machine, the generated code might differ, leading to unexpected behavior.
  2. Speed: Generating code makes pipelines slower and more expensive. Committing the files allows your CI/CD to start testing and building immediately.
  3. Environment Consistency: Some packages, like Envied, generate code based on environment variables. Committing these ensures that the code you tested is exactly what gets deployed.

The Case for Ignoring (The Exception)

There are times when you may want to exclude these files from Git or force the pipeline to regenerate them:

  • Security: If you use packages like Envied to inject production credentials via environment variables during the build process, you definitely want to regenerate that code in your secure pipeline rather than storing it in Git.
  • Repo Health: Generated files can “bloat” your VCS history.
  • Merge Conflicts: If two developers modify the same model, the generated files will often result in complex merge conflicts that cannot be resolved manually.
  • PR Noise: Generated code adds thousands of lines to Pull Requests, making it harder for reviewers to focus on the logic that actually matters.

Conclusion

As a general rule, commit your generated code unless you specifically need your pipeline to build a different version of the code (like environment-specific secrets) than what the developers use locally. If the “PR noise” bothers you, look into using a .gitattributes file to mark generated files as linguist-generated, which collapses them automatically on platforms like GitHub.