---
title: Migrations
description: How to migrate between major versions of Melos.
---

# Migrations

## 6.x.x to 7.x.x

Since the [pub workspaces](https://dart.dev/tools/pub/workspaces) feature has
been released, Melos has been updated to rely on that, instead of creating
`pubspec_overrides.yaml` files and thus some migration is needed.

The main difference is that:
1. There is no longer a `melos.yaml` file, only the root `pubspec.yaml`
2. You now have to add `resolution: workspace` to all of your packages'
   `pubspec.yaml` files.
3. You now have to add a list of all your packages to the root `pubspec.yaml`
   file.

After the migration your root `pubspec.yaml` file would now look something like this:
```yaml
name: my_workspace
publish_to: none
environment:
  sdk: ^3.9.0
workspace:
  - packages/helper
  - packages/client_package
  - packages/server_package
dev_dependencies:
  melos: ^7.0.0

melos:
  # All of the content of your previous melos.yaml file
  # (Except for the packages and name)
```


And this is what the `pubspec.yaml` file of a package would look like:
```yaml
name: my_package
environment:
  sdk: ^3.9.0
resolution: workspace
```

<Info>
You have to use Dart SDK 3.9.0 or newer to use pub workspaces reliably.
If you are using an older version of the Dart SDK, you can still use Melos
with pub workspaces, but then you have to rely on the `7.0.0-dev.x` versions.
</Info>

### 'melos analyze` no longer exists

Since `flutter/dart analyze` now runs in the full pub workspace, the
`melos analyze` command has been removed,

### Root packages

In Melos 6.x, you could include the repository root (`.`) as a package in the
workspace by listing it in the `packages` configuration. In Melos 7.x with
pub workspaces, this behavior is not supported by default.

If your project uses the repository root as a package, you have two options:

#### Option 1: Enable `useRootAsPackage`

Recommended for existing projects.

Add the `useRootAsPackage` option to maintain existing behavior:

```yaml
# pubspec.yaml
name: my_workspace
publish_to: none
environment:
  sdk: ^3.9.0
workspace:
  - packages/helper
  - packages/client_package

melos:
  useRootAsPackage: true
  categories:
    app:
      - "."
    packages:
      - "packages/**"
```

This allows the root package to participate in workspace operations such as
scripts, filtering, and categorization.

#### Option 2: Restructure (Recommended for new projects)

Move your root application into a subdirectory:

1. Create an `apps/` or `app/` directory
2. Move your main application code there
3. Update your workspace configuration accordingly

This approach provides better separation between workspace configuration and
application code.

## 3.0.0 to 4.0.0

### `--no-git-tag-version` behavior change

If you were previously using `--no-git-tag-version` and were relying on that it
didn't create a commit you now have to also pass `--no-git-commit-version` to
prevent a commit from being automatically created after versioning.

## 2.0.0 to 3.0.0

### Versioning of Melos in workspaces

From Melos 3.0.0, the version of Melos to use in any given workspace must be
specified in a `pubspec.yaml` file next to the `melos.yaml` file, in the
workspace root directory.

Different Melos workspaces might use different versions of Melos. To ensure
everyone working in the workspace (as well as CI jobs) is using the same version
of Melos, a dependency on the `melos` package has to be added to the
`pubspec.yaml` file at the workspace root directory. The globally installed
version of Melos will switch to the version specified in the `pubspec.yaml`
file, if both versions are not the same.

If you don't have a `pubspec.yaml` file at the workspace root yet, create one
now:

```yaml
name: my_project_workspace

environment:
  sdk: '>=3.0.0 <4.0.0'
```

The corresponding `pubspec.lock` file should also be committed. Make sure to
exclude it from the `.gitignore` file.

Add Melos as a development dependency by running the following command:

```bash
dart pub add melos --dev
```

### Local package linking with `pubspec_overrides.yaml`

The initial mechanism used by Melos to link local packages for development had
some issues when interacting with other tooling. An often-encountered error is
"The pubspec.yaml file has changed since the pubspec.lock file was generated"
([#117](https://github.com/invertase/melos/issues/117)).

To resolve this issue, an alternative mechanism has been implemented which
generates `pubspec_overrides.yaml` files in the root of each package, for which
dependencies need to be overridden. Before Melos 3.0.0, this mechanism had to be
opted into by setting `command/bootstrap/usePubspecOverrides` in `melos.yaml` to
`true`.

This is now the only mechanism used by Melos and the `usePubspecOverrides`
configuration option has been removed.

Typically `pubspec_overrides.yaml` files should be ignored by git. To ignore
these files, add the following to your `.gitignore` file:

```
pubspec_overrides.yaml
```

### `--since` was removed in favour of `--diff`

The `--since` flag was removed in favour of `--diff`, which is more flexible and
can be used to specify a range of commits in addition to a single commit.

To migrate from `--since` to `--diff` simply replace `--since` with `--diff`.

### Changed option defaults

The following options are now enabled by default:

- [`command/version/includeScopes`](/configuration/overview#includescopes)
- [`command/version/linkToCommits`](/configuration/overview#linktocommits), if
  [`repository`](/configuration/overview#repository) is configured
- [`command/version/workspaceChangelog`](/configuration/overview#workspacechangelog)

### Lifecycle hooks

Lifecycle hooks have been moved to the respective command configurations.
Previously, hooks were defined in `scripts`. The `pre` hook had the same name as
the command, and the `post` hook had the name of the command with `post`
appended. Now, hooks are defined in `command/<name>/hooks`.

- `bootstrap` -> `command/bootstrap/hooks/pre`
- `postbootstrap` -> `command/bootstrap/hooks/post`
- `clean` -> `command/clean/hooks/pre`
- `postclean` -> `command/clean/hooks/post`
- `version` -> `command/version/hooks/preCommit`
- `postversion` -> `command/version/hooks/post`

#### Version command hooks

The `version` hook was previously executed during versioning, before the version
commit was created. The `pre` hook is now executed before the `version` command,
like for all other commands.

The new `preCommit` hook is executed before the version commit is created and is
the equivalent of the previous `version` hook.

### Package filters

The `select-package` option for scripts has been renamed to
[`packageFilters`](/configuration/scripts#packagefilters). This brings it in
line with
[`command/version/changelogs/packageFilters`](/configuration/overview#packagefilters).

The names of filters specified in `packageFilters` are now camel cased instead
of kebab cased.

For example, take the following `test` script configuration:

```yaml
scripts:
  test:
    exec: dart test
    packageFilters:
      dirExists: test
```

This would previously have been written as:

```yaml
scripts:
  test:
    exec: dart test
    select-package:
      dir-exists: test
```