DOCSEARCHbyAlgolia
Submit Docs

FVM (Flutter Version Management)

repository·main·Indexed 26 days ago

https://github.com/conceptadev/fvm

A version management tool for the Flutter SDK that enables per-project SDK configuration. FVM allows developers to manage multiple Flutter versions, maintain environment consistency across teams, and use custom SDK forks. It includes a CLI, a JSON API for automation, and fvm_mcp, an MCP server that exposes FVM CLI tools.

Tokens
18.2K
Snippets
74
Records
141
Agent score
89%

What's inside FVM

  1. Overview of FVM (Flutter Version Management)

    main

    FVM (Flutter Version Management) is a tool designed to streamline Flutter SDK management. It enables per-project SDK versioning, which ensures consistent app builds across different environments and simplifies testing of new Flutter releases.

    Key benefits include:

    • Simultaneous use of multiple Flutter SDKs.
    • Efficient testing of different Flutter channels without slow manual switching.
    • Easier management of specific SDK versions used in existing apps.
    • Prevention of development environment inconsistencies within teams.

  2. Overview of FVM features

    main

    FVM (Flutter Version Management) provides the following capabilities:

    • Per-project Flutter versions: Each project can use a different Flutter SDK.
    • Fast switching: Change versions instantly without re-downloading.
    • Team consistency: Everyone uses the same Flutter version via a .fvmrc configuration file.
    • CI/CD friendly: Simple commands designed for automation.
    • Fork support: Ability to use custom Flutter repositories.

  3. Overview of FVM

    main
    FVM (Flutter Version Management) manages Flutter SDK versions on a per-project basis. It allows you to switch between different Flutter versions instantly without needing to reinstall the SDK, which is useful for testing new Flutter releases, maintaining consistent builds across teams, and managing multiple SDKs simultaneously.

  7. Use the .fvm directory for IDE integration

    main

    The .fvm directory is created in your project root to manage the local SDK environment.

    To integrate with your IDE (like Android Studio or IntelliJ), point the IDE's Flutter SDK path to the .fvm/flutter_sdk symlink. If the symlink is missing, run fvm use <version> in the project root to recreate it.

    Note: It is recommended to add the .fvm directory to your .gitignore. If updateGitIgnore is set to true in .fvmrc, FVM will attempt to add it automatically.

  10. Manually test FVM legacy git cache migration

    main

    If you need to debug the migration process step-by-step, follow this manual procedure to migrate a non-bare git cache (pre-4.0.2) to a bare mirror.

    1. Set Environment Variables

    To avoid touching your global ~/.fvm directory, use an isolated cache path:

    export FVM_CACHE_PATH="$(pwd)/.context/tmp/fvm-migration-cache"
export FVM_USE_GIT_CACHE=true

    2. Prepare the Legacy Cache

    1. Clean slate: Ensure $FVM_CACHE_PATH is empty.
    2. Seed legacy cache: Activate an FVM version prior to 4.0.2 (e.g., 4.0.1) to create a non-bare git cache.
      dart pub global activate fvm 4.0.1
fvm install stable
fvm install <version>
fvm install beta
    3. Verify legacy state: Ensure git -C "$FVM_CACHE_PATH/cache.git" config --bool core.bare returns false.

    3. Trigger Migration

    Run the migration logic from the repository root:

    dart pub get

FVM_CACHE_PATH="$FVM_CACHE_PATH" FVM_USE_GIT_CACHE=true \
  dart run bin/main.dart install stable

    4. Verify Migration Results

    • Bare Repository: git -C "$FVM_CACHE_PATH/cache.git" config --bool core.bare should return true.
    • Alternates Files: Check that .git/objects/info/alternates files in the version directories now point to .../cache.git/objects (without the /.git/ segment in the path).
    • Integrity: Run git -C "$FVM_CACHE_PATH/cache.git" fsck --connectivity-only to ensure no errors.
    • SDK Execution: Verify that Flutter binaries in the migrated versions still execute correctly:
      "$FVM_CACHE_PATH/versions/stable/bin/flutter" --version

  11. Use custom Flutter SDK versions via the fork command

    main

    The recommended way to use modified Flutter SDKs from forked repositories is using the fvm fork command. This allows you to add a repository as a fork and then install or use specific branches/versions from that repository using the fork_name/version syntax.

    # Add a fork
fvm fork add mycompany https://github.com/mycompany/flutter.git

# Use it like any version
fvm install mycompany/stable
fvm use mycompany/3.19.0

  12. Run Flutter and Dart commands via FVM proxy commands

    main

    Use the fvm flutter and fvm dart proxy commands to ensure you are running the specific Flutter or Dart SDK version configured for your project. FVM automatically resolves the correct SDK based on your project settings.

    To make these commands easier to type, you can create shell aliases.

    # Use proxy commands
fvm flutter <command>
fvm dart <command>

# Recommended: Create aliases for convenience
alias f="fvm flutter"
alias d="fvm dart"