Back to Details

flutter-worktrees

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Using Git Worktrees for Flutter Development

为Flutter开发使用Git Worktrees

Overview

概述

Git worktrees let you work on multiple branches simultaneously in separate directories. Each worktree is fully independent - you can run different Flutter versions, have different dependencies, without affecting your main workspace.
Core principle: Isolated workspace = safe experimentation + parallel development
Announce at start: "I'm using the flutter-worktrees skill to create an isolated workspace."
Git Worktrees允许你在不同目录中同时处理多个分支。每个工作区完全独立——你可以运行不同的Flutter版本、使用不同的依赖，且不会影响主工作区。
核心原则： 独立工作区 = 安全实验 + 并行开发
开始时告知： "我正在使用flutter-worktrees技能创建独立工作区。"

When to Use

使用场景

  • Starting a new feature that needs isolation
  • Working on experimental changes
  • Need to compare implementations side-by-side
  • Want to keep main workspace clean
  • Running long-running tests in background
  • 启动需要隔离的新功能开发
  • 进行实验性修改
  • 需要并排对比不同实现方案
  • 希望保持主工作区整洁
  • 在后台运行长时间的测试

The Process

操作流程

Step 1: Create Worktree

步骤1：创建工作区

bash
undefined
bash
undefined

From main repository

从主仓库执行

git worktree add ../flutter-app-feature-auth feature/auth
git worktree add ../flutter-app-feature-auth feature/auth

Or create new branch

或者创建新分支

git worktree add -b feature/auth ../flutter-app-feature-auth main

**Naming convention:** `../[project-name]-[feature-name]`
git worktree add -b feature/auth ../flutter-app-feature-auth main

**命名规范：** `../[项目名称]-[功能名称]`

Step 2: Navigate to Worktree

步骤2：进入工作区

bash
cd ../flutter-app-feature-auth
bash
cd ../flutter-app-feature-auth

Step 3: Flutter Setup (Critical for Flutter Projects!)

步骤3：Flutter配置（Flutter项目的关键步骤！）

bash
undefined
bash
undefined

Install dependencies

安装依赖

flutter pub get
flutter pub get

Verify Flutter is working

验证Flutter是否正常工作

flutter doctor
flutter doctor

If needed, run code generation

如有需要，运行代码生成

flutter pub run build_runner build --delete-conflicting-outputs
undefined
flutter pub run build_runner build --delete-conflicting-outputs
undefined

Step 4: Verify Setup

步骤4：验证配置

bash
undefined
bash
undefined

Check project state

检查项目状态

flutter analyze flutter test
flutter analyze flutter test

Should show no issues if setup is correct

如果配置正确，应该不会显示任何问题

undefined
undefined

Step 5: Work on Feature

步骤5：开发功能

Follow normal development workflow:
  • flutter-brainstorming
  • flutter-planning
  • flutter-executing
All changes stay isolated in this worktree.
遵循常规开发流程：
  • flutter-brainstorming
  • flutter-planning
  • flutter-executing
所有修改都会保留在这个独立工作区中。

Step 6: Cleanup (After Merge/Discard)

步骤6：清理（合并/废弃后）

bash
undefined
bash
undefined

From main repository

从主仓库执行

cd ../flutter-app # Back to main
cd ../flutter-app # 返回主工作区

Remove worktree

删除工作区

git worktree remove ../flutter-app-feature-auth
git worktree remove ../flutter-app-feature-auth

If branch was merged, it's already in main

如果分支已合并，它已同步到主分支

If discarded, the branch still exists and can be deleted:

如果废弃，分支仍然存在，可以删除：

git branch -D feature/auth
undefined
git branch -D feature/auth
undefined

Worktree Directory Structure

工作区目录结构

parent-directory/
├── flutter-app/                  # Main repository
│   ├── lib/
│   ├── test/
│   ├── pubspec.yaml
│   └── .git/                     # Main git directory
├── flutter-app-feature-auth/     # Worktree 1
│   ├── lib/
│   ├── test/
│   ├── pubspec.yaml
│   └── .git                      # File pointing to main .git
└── flutter-app-feature-profile/  # Worktree 2
    ├── lib/
    ├── test/
    ├── pubspec.yaml
    └── .git
parent-directory/
├── flutter-app/                  # 主仓库
│   ├── lib/
│   ├── test/
│   ├── pubspec.yaml
│   └── .git/                     # 主Git目录
├── flutter-app-feature-auth/     # 工作区1
│   ├── lib/
│   ├── test/
│   ├── pubspec.yaml
│   └── .git                      # 指向主.git的文件
└── flutter-app-feature-profile/  # 工作区2
    ├── lib/
    ├── test/
    ├── pubspec.yaml
    └── .git

Flutter-Specific Considerations

Flutter专属注意事项

Dependencies

依赖管理

Each worktree has its own:
  • .dart_tool/
    directory
  • pubspec.lock
    (can differ if experimenting with versions)
  • Build cache
Always run 
flutter pub get
after creating worktree!
每个工作区都有自己的：
  • .dart_tool/
    目录
  • pubspec.lock
    （如果实验不同版本，内容可能不同）
  • 构建缓存
创建工作区后务必运行
flutter pub get
！

Code Generation

代码生成

If project uses code generation (freezed, json_serializable, etc.):
bash
flutter pub run build_runner build --delete-conflicting-outputs
如果项目使用代码生成（freezed、json_serializable等）：
bash
flutter pub run build_runner build --delete-conflicting-outputs

IDE Setup

IDE配置

VS Code: Open worktree folder as new workspace Android Studio: Open worktree folder as new project
VS Code: 将工作区文件夹作为新工作区打开 Android Studio: 将工作区文件夹作为新项目打开

Platform-Specific Builds

平台特定构建

Each worktree can have different:
  • iOS simulator running
  • Android emulator connected
  • Web server running
No conflicts between worktrees!
每个工作区可以有不同的：
  • 运行中的iOS模拟器
  • 连接的Android模拟器
  • 运行中的Web服务器
工作区之间不会有冲突！

Example Workflow

示例流程

bash
undefined
bash
undefined

1. Create isolated workspace for auth feature

1. 为认证功能创建独立工作区

git worktree add -b feature/auth ../flutter-app-auth main
git worktree add -b feature/auth ../flutter-app-auth main

2. Navigate and setup

2. 进入并配置工作区

cd ../flutter-app-auth flutter pub get flutter pub run build_runner build --delete-conflicting-outputs
cd ../flutter-app-auth flutter pub get flutter pub run build_runner build --delete-conflicting-outputs

3. Verify

3. 验证配置

flutter analyze flutter test
flutter analyze flutter test

4. Work on feature (using flutter-craft skills)

4. 开发功能（使用flutter-craft技能）

... implement auth feature ...

... 实现认证功能 ...

5. When done, back to main

5. 完成后返回主工作区

cd ../flutter-app
cd ../flutter-app

6. Merge if ready

6. 准备好后合并

git merge feature/auth
git merge feature/auth

7. Cleanup

7. 清理工作区

git worktree remove ../flutter-app-auth
undefined
git worktree remove ../flutter-app-auth
undefined

Red Flags

注意事项

Never:
  • Forget 
    flutter pub get
    in new worktree
  • Edit main repository while expecting changes in worktree
  • Delete worktree directory manually (use 
    git worktree remove
    )
  • Have same file open in IDE from both main and worktree
If worktree has issues:
bash
undefined
绝对不要：
  • 在新工作区中忘记运行
    flutter pub get
  • 期望修改主仓库会同步到工作区
  • 手动删除工作区目录（请使用
    git worktree remove
    ）
  • 在IDE中同时打开主工作区和子工作区的同一文件
如果工作区出现问题：
bash
undefined

List all worktrees

列出所有工作区

git worktree list
git worktree list

Prune stale worktree references

清理失效的工作区引用

git worktree prune
undefined
git worktree prune
undefined

Integration with Other Skills

与其他技能的集成

After creating worktree:
  • Use flutter-brainstorming to design feature
  • Use flutter-planning to create implementation plan
  • Use flutter-executing or flutter-subagent-dev to implement
After feature complete:
  • Use flutter-finishing to decide merge/PR/keep/discard
  • Cleanup worktree after merge
创建工作区后：
  • 使用flutter-brainstorming设计功能
  • 使用flutter-planning制定实现计划
  • 使用flutter-executing或flutter-subagent-dev进行开发
功能完成后：
  • 使用flutter-finishing决定合并/提交PR/保留/废弃
  • 合并后清理工作区

Quick Reference

快速参考

CommandPurpose
git worktree add <path> <branch>
Create worktree
git worktree add -b <new-branch> <path> <base>
Create with new branch
git worktree list
List all worktrees
git worktree remove <path>
Remove worktree
git worktree prune
Clean stale references
flutter pub get
Required after creating!
命令用途
git worktree add <path> <branch>
创建工作区
git worktree add -b <new-branch> <path> <base>
创建工作区并新建分支
git worktree list
列出所有工作区
git worktree remove <path>
删除工作区
git worktree prune
清理失效引用
flutter pub get
创建工作区后必须执行！