What is .metadata file in Flutter Project?
Tags: flutter, dart, metadata, study
Published: 2022-12-28 03:51:52

## 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](https://github.com/invertase/flutterfire_desktop/blob/main/.gitignore)
2. [.gitignore file for Dart language provided by github](https://github.com/github/gitignore/blob/main/Dart.gitignore)
3. [Recommended .gitignore file for Flutter project provided by Toptal](https://www.toptal.com/developers/gitignore)

## 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](https://github.com/flutter/flutter/blob/master/packages/flutter_tools/lib/src/commands/create.dart#L348-L370))
	1. Note that, in below code, there's a `generateMetadata` option. ![runCommand code](https://github.com/swimmingkiim/blog-comments/blob/main/assets/images/code-flutter-create-command.png?raw=true)
2. `generateApp`([View this code in github](https://github.com/flutter/flutter/blob/master/packages/flutter_tools/lib/src/commands/create_base.dart#L500-L510))
	1. You can see that, by default, `flutter create` command creates `.metadata` file. ![generateApp](https://github.com/swimmingkiim/blog-comments/blob/main/assets/images/code-flutter-create-generate-app.png?raw=true)
   3. when `generateMetadata` option is true([View this code in github](https://github.com/flutter/flutter/blob/master/packages/flutter_tools/lib/src/commands/create_base.dart#L577-L596))
	   1. You can see that the code generates `.metadata` file using `FlutterProjectMetadata` class. ![when generateMetadata option is true](https://github.com/swimmingkiim/blog-comments/blob/main/assets/images/code-flutter-create-generate-app-generate-metadata.png?raw=true)

The question was "Why some Flutter project does not have `.metadata` file in their code base?" .
![runCommand code](https://github.com/swimmingkiim/blog-comments/blob/main/assets/images/code-flutter-create-command.png?raw=true)

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.
![.metadata file exists](https://github.com/swimmingkiim/blog-comments/blob/main/assets/images/%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202022-12-20%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%205.07.36.png?raw=true)

When you run `flutter create -t skeleton`, you can't find `.metadata` file.
![no .metadata file](https://github.com/swimmingkiim/blog-comments/blob/main/assets/images/%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202022-12-20%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%205.08.20.png?raw=true)

## 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](https://github.com/flutter/flutter/blob/master/packages/flutter_tools/lib/src/commands/upgrade.dart#L128-L131))
![flutter upgrade use revision data in .metadata file](https://github.com/swimmingkiim/blog-comments/blob/main/assets/images/code-revision.png?raw=true)

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)
``` text
# 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 :-)

<a href="https://www.buymeacoffee.com/swimmingkiim" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/arial-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>