Mark generated files with @generated marker

The problem

Sometimes we store generated files in source folders. For example, Java sources generated with Protocol Buffers can be committed to the repository for convenience. Another example is Cargo.lock or yarn.lock files which contain resolved versions of dependencies.

There is a variety of tools which work with files:

• Linters
• Code formatters
• IDEs
• Source code viewers and commit viewers

These tools need to handle generated files differently, for example:

• Linters and code formatters should ignore these files
• IDEs may give a warning if such files are edited
• Code viewers may collapse these files by default

The solution

Let's invent a standard how to mark files generated.

We did not find any common conventions, so we picked

@generated

marker. Place it anywhere in the beginning of the file, and the file is considered generated:

# This file is @generated by ./gen.sh.
# Do not edit.

Who is using @generated

• Facebook uses @generated marker internally
• GitHub super-linter supports @generated opt-in
• MegaLinter can ignore files marked as @generated as well
• rustfmt has an option to ignore @generated
• Cargo marks Cargo.lock files with @generated marker
• PHP FIG proposes to use @generated tag (which is accidentally compatible with @generated marker)
• Phabricator tool which was spawned from Facebook internal tool also uses @generated marker
• More to come...