What is .metadata file in Flutter Project?

Intro

One day, my boss wanted to add .metadata file in .gitignore file. I wondered, should we really need to do that? Is that OK to do that?

Definition of .metadata file in a Flutter project

In Flutter official website, they describe .metadata file like below.

.metadata A hidden file used by IDEs to track the properties of the Flutter project.

Should you add this to .gitignore file?

The answer is No.

Reason 1 : Comment inside .metadata file

This file tracks properties of this Flutter project.
Used by Flutter tool to assess capabilities and perform upgrades etc.

This file should be version controlled.

As mention in above comment, the .metadata file should be version controlled which means git version controll.

Reason 2 : Other references also doesn't include .metadata file in .gitignore file

References of .gitignore that doesn't include .metadata

1. .gitignore file in invertase/flutterfire_desktop
2. .gitignore file for Dart language provided by github
3. Recommended .gitignore file for Flutter project provided by Toptal

Why some Flutter project have .metadata file, and some does not?

In order to understand this reasons behind this, first, we need to understand when and how .metadata file is created.

.metadata file is created when you run flutter create command

As of now(2022.12.28), when you run flutter create command, process below will be executed in order.

1. runCommand (View this code in github)
   1. Note that, in below code, there's a generateMetadata option.
2. generateApp(View this code in github)
   1. You can see that, by default, flutter create command creates .metadata file.
   2. when generateMetadata option is true(View this code in github)
      1. You can see that the code generates .metadata file using FlutterProjectMetadata class.

The question was "Why some Flutter project does not have .metadata file in their code base?" .

In above code, line 20 tells us that, when you give skeleton option in flutter create command, generateMetadata option is set to false. If you test to run flutter create -t skeleton , it really does not have .metadata file.

When you run flutter create, there is .metadata file.

When you run flutter create -t skeleton, you can't find .metadata file.

Where this .metadata file used in Flutter Project?

This file tracks properties of this Flutter project.
Used by Flutter tool to assess capabilities and perform upgrades etc.

This file should be version controlled.

Flutter use internally. Such as, when you run flutter upgrade.
(View this code in github)

In above code is part of code inside flutter upgrade command. You can see revision is being used which is noted on .metadata file.
(BTW, revision in Git world means any git object expression that can specify, such as main, commit id etc)

# This file tracks properties of this Flutter project.
# Used by Flutter tool to assess capabilities and perform upgrades etc.
#
# This file should be version controlled.

version:
  revision: b8f7f1f9869bb2d116aa6a70dbeac61000b52849
  channel: stable

project_type: app

# Tracks metadata for the flutter migrate command
migration:
  platforms:
    - platform: root
      create_revision: b8f7f1f9869bb2d116aa6a70dbeac61000b52849
      base_revision: b8f7f1f9869bb2d116aa6a70dbeac61000b52849
    - platform: android
      create_revision: b8f7f1f9869bb2d116aa6a70dbeac61000b52849
      base_revision: b8f7f1f9869bb2d116aa6a70dbeac61000b52849
    - platform: ios
      create_revision: b8f7f1f9869bb2d116aa6a70dbeac61000b52849
      base_revision: b8f7f1f9869bb2d116aa6a70dbeac61000b52849
    - platform: linux
      create_revision: b8f7f1f9869bb2d116aa6a70dbeac61000b52849
      base_revision: b8f7f1f9869bb2d116aa6a70dbeac61000b52849
    - platform: macos
      create_revision: b8f7f1f9869bb2d116aa6a70dbeac61000b52849
      base_revision: b8f7f1f9869bb2d116aa6a70dbeac61000b52849
    - platform: web
      create_revision: b8f7f1f9869bb2d116aa6a70dbeac61000b52849
      base_revision: b8f7f1f9869bb2d116aa6a70dbeac61000b52849
    - platform: windows
      create_revision: b8f7f1f9869bb2d116aa6a70dbeac61000b52849
      base_revision: b8f7f1f9869bb2d116aa6a70dbeac61000b52849

  # User provided section

  # List of Local paths (relative to this file) that should be
  # ignored by the migrate tool.
  #
  # Files that are not part of the templates will be ignored by default.
  unmanaged_files:
    - 'lib/main.dart'
    - 'ios/Runner.xcodeproj/project.pbxproj'

Is .metadata file is necessary for build Flutter project?

I've tested with flutter run -d chrome and flutter build web without .metadata file. Both are fine without .metadata file. When I mean fine, no error displayed.

What if I want to create or update .metadata file?

Well, if you created your Flutter project without skeleton option, which is in most cases, you already have .metadata file.

When it comes to update, I don't think you need to keep track and update manually. When you run flutter upgrade command and revision for Flutter changes, flutter upgrade does not update all previous local Flutter project's .metadata . And it runs just fine.

But, in some reason, if you want to update .metadata file, you can run flutter create . to do that. When you don't have .metadata file, this command will create one.

Conclusion

I'm not sure if anyone want this much information about .metadata file in Flutter project. Before this research, I didn't even noticed that .metadata file exists in Flutter project.

Hope you find interesting :-)