---
type: Contributor Doc
title: Git & Git Worktree Workflow Guide for Flutter Development
description: How to efficiently manage multiple concurrent branches and pull requests using Git worktrees.
resource: A practical guide to leveraging Git worktrees in Flutter development for tracking multiple release channels (master, beta, stable), managing concurrent feature branches, and conducting PR reviews without duplicating repository clones or managing git stashes.
tags: [git, worktrees, contributing, branches, PR review, feature development]
timestamp: 2026-07-23T15:26:31-0700
---

# Git & Worktree Workflow Guide for Flutter Development

Traditional `git` development follows a simple pattern for smaller projects: clone, commit, push, update. Medium projects tend to add branching and release workflows. Flutter is a large project with many moving parts and engineers wearing different hats at different times: framework, engine, infrastructure, release, android, iOS, gardener, sheriff, triage.

This document covers a recommended workflow that should be flexible for all engineers contributing to Flutter, reduce cloned repository size and wasted space, and provide guidance for common tasks.

## Setup

Having one [flutter development environment](https://github.com/flutter/flutter/blob/main/docs/contributing/Setting-up-the-Framework-development-environment.md#set-up-your-environment) incurs a cost when changing branches between master, stable, and feature development - triggering a redownload of flutter artifacts, recompiling the flutter tool, and oftentimes requiring stashing of work. Running third party tools (vscode, dart analyzer, or agent) can also run into trouble when the local branch is changed. Having multiple git clones requires duplication of the `.git` folder for the same source code, juggling environment path changes or using OS aliasing techniques to call the correct version of flutter.

Instead, we use git worktrees: a way to manage multiple working directories, each with a different branch checked out, all linked to the same Git repository. Using [flutter_worktree](https://github.com/jtmcdole/flutter_worktree#installation) we can end up with a flutter tree setup to track upstream/origin correctly, and have master/stable already checked out.

```shell
~/flutter/
    ├── .bare/         (The bare repo or main tracking folder)
    ├── .git           (pointer to .bare/)
    ├── fswitch.sh     ("fswitch" command line with tab completion - win32:.ps1)
    ├── master/        (Always clean, main development branch)
    ├── stable/        (Locked to latest stable release for repros)
    ├── review-179637/ (Temporary folder for reviewing PR #1234)
    └── feature/new-widget/    (Long-running feature work)
```

This has the benefit of sharing the `.bare` git repository amongst all trees. The source files for each branch must be *unpacked* from `.bare` and the `<tree>/bin/cached` binaries are downloaded to the tree if you run the flutter tool.  The install script for flutter_worktree will create the `fswitch.sh` file which you can use in your bash/zsh/windows profile to quickly `fswitch <branch>` and update your environment's path without re-downloading (on Windows, Linux, and macOS).

With the following directory structure; and with `fswitch.sh` sourced in your profile (e.g. `~/.zshrc`), you can now have multiple terminals open and dedicated to master and stable with a simple `fswitch master` / `fswitch stable`. This updates the current shell session’s OS PATH search to point to `master/bin` or `stable/bin`, allowing for VsCode, Antigravity, and other tooling to find the right version of Flutter for tooling.

```shell
--- /Users/codefu/src/flutter ---
    1.9 GiB [#############################] /master
  932.7 MiB [##############               ] /stable
  738.2 MiB [###########                  ] /pr-review
  487.0 MiB [#######                      ] /.bare
    8.0 KiB [                             ]  fswitch.sh
    4.0 KiB [                             ]  .git
```

> [!WARNING]
> Do not run tools like vscode from the root folder as this can cause them to stall trying to index all of the worktrees.

### Common Scenarios

> [!NOTE]
> This document follows the Flutter conventions for naming remotes:
>
> * **upstream**: `git@github.com:flutter/flutter.git` (Fetch target for master/beta/stable)
> * **origin**: `git@github.com:<your-username>/flutter.git` (Push target for feature PRs)

#### Code Reviews

Instead of doing code reviews on [github.com](https://github.com) and lacking the feature rich dart analyzer, or being able to use an agent and other advanced tooling; check out the PR locally.

Without the `gh` tool:
```shell
# 1. Fetch the PR HEAD
git fetch upstream pull/189954/head:pr-189954

# 2. Checkout the PR - automatically follows pull/189954/head
git worktree add pr-189954

# 3. Perform the review
cd pr-189954

# git log HEAD -n1
# commit d277b8d7652b1baaf5844dc70040c60914b9eb5c (HEAD -> pr-189954)
# Author: engine-flutter-autoroll <engine-flutter-autoroll@skia.org>
# Date:   Thu Jul 23 21:35:02 2026 +0000

# ... vscode, vim, antigravity.

# 4. Delete the worktree when done. Remember to change to any other worktree or the root (with the `.bare` folder)
git worktree remove pr-189954
```

With the `gh` tool it's easier:

```shell
git worktree add prreview
cd prreview
gh pr checkout 189954
```

#### New Feature Development

You picked up a feature to implement a new widget, assign yourself the issue, and start work:

```shell
# Start a new worktree branched from latest HEAD
git worktree add feature/new-widget

# Switch and start work
cd feature/new-widget
code .

# Push it upstream
git push --set-upstream origin $(git branch --show-current)

# ... get reviews, make changes, pass tests

# Delete the tree when done
git worktree remove feature/new-widget
```

There's no need to stash or upload changes until you are ready. You can update master / stable / other feature branches without losing context in `feature/new-widget`.

#### Bug Investigation (Stable)

If you've picked up a well documented  issue to investigate; you can simply `fswitch stable` and test against stable.

```shell
# Switch to stable branch
fswitch stable
# Or if you want to bisect starting at some baseref
git worktree add bugHunt baseref
fswitch bugHunt # updates the binaries in the environment PATH
cd bugHunt # changes to the bugHunt worktree
# ... git bisect
# Get the reprocode from the issue
mkdir repro_code && ....

# Debug however you need to
flutter run

# Alternate to master and see if its already fixed?
fswitch master
flutter clean
flutter run

# You could even check out an old stable
cd ~/src/flutter
git worktree add beta upstream/beta
fswitch beta
flutter clean
flutter run
```

If you verify the bug and want to start a new PR; you can just create a worktree like a feature rather than juggling changes in your stable/master branch.

## Modern Git Commands

Git commands you should be using (and why).

### Git Switch

`git branch` is for managing branches (creating, listing, deleting) - while `git switch` is for **navigating** **between** them.  Prior to 2019, we would use `git checkout` to switch between branches, but this is an overloaded command and leads to confusion…. E.g.  `switch` operates on branches whereas `checkout` can operate on files (`git checkout -- file.txt`)

```shell
# Create and change to new feature
git switch -c new-feature

# Just switch
git switch master

# House keeping
git branch -d new-feature
```

> [!NOTE]
> If `branch` is already checked out in another worktree, git will refuse to switch to it with a message like:
>
> ```shell
> fatal: 'master' is already used by worktree at '/Users/codefu/src/flutter/master'
> ```

### Git Restore

Instead of using `git checkout` as a swiss army knife; use `git restore`:

If you edit a file but realize you made a mess and just want it back to how it was in the last commit:

```shell
git restore config.json
```

If you added a file too early, i.e. the file is in **staging**:

```shell
git restore --staged secret_keys.env
```

### Git Reset

This is for time traveling in your tree and has three modes: soft, mixed, and hard.

#### Oops, I made a typo in the commit (soft)

You committed your work, but realized you forgot to include one file, or you messed up the commit message.

```shell
# The commit is gone, but the files are currently green (staged).
# You can fix the file/message and run git commit again.
git reset --soft HEAD~1
```

#### I want to split a big commit into two smaller ones (--mixed)

This is the default mode when running `git reset`

```shell
# The commit is gone. The files are there but red (unstaged).
# You can now git add file A, commit it, then git add file B,
# and commit that separately.
git reset HEAD~1
```

#### Throwing in the Towel

You've tried fixing a bug, spent 3 hours on it, and realized everything is borked. You just want to go back to when the code worked.

```shell
# All work since the last commit is erased
# Yar, there be dragons.

git reset --hard HEAD~1
```

## Other Git Topics

### Rebase vs Merge

There are two ways to update a Pull Request (PR) branch with upstream changes: **merging** and **rebasing**. Because Flutter is a large-scale project with automated infrastructure, specific assumptions are made regarding a PR's history, diffing, baseline compatibility, and engine artifacts. Flutter runs best with a rebase workflow.

**Technical reasoning:**

* `git merge master` (*discouraged*): Creates a non-linear history by generating a new "merge commit" at the tip of your branch. While a merge does shift the local `git merge-base` forward to include the latest `master` commits, it introduces a diamond-shaped commit graph. Automated tooling or metrics scripts checking chronological commit age or topological order can misinterpret the branch history, leading to flaky CI/CD evaluations.
* `git rebase upstream/master` (*encouraged*): Rewrites your branch history by picking up your unique commits and planting them directly on top of the latest `master` commit. This maintains a perfectly **linear history**. The base of your branch becomes the absolute tip of `master`, ensuring that content hashes, tests, and build artifacts are validated against a clean codebase rather than a mixed history.

**Social reasoning:**

* **Merge**: If you merge `master` into your branch multiple times over a long development cycle, your PR history becomes cluttered with "Merge branch 'master' into..." commits. This noise obscures your actual work, making it difficult for maintainers to review your specific changes.
* **Rebase**: It presents a clean, chronological  story: *"Here is my work, applied directly to the latest codebase."* It signals to the reviewer that you have verified your code works cleanly alongside the most recent upstream changes.

**Conflict Reasoning:**
Given the high velocity of the Flutter repository, conflicts with `master` are common.

* **With a merge**, you resolve conflicts inside a noisy, standalone "merge commit."
* **With a rebase**, you resolve conflicts **within your own individual commits**. This keeps the final code clean and ensures your discrete commits remain atomic and functional if they ever need to be cherry-picked later.

**Force Pushing Safely**

Because a `rebase` rewrites your branch's commit **history**, a standard `git push` will be rejected by GitHub. You must force push.

**Never use** `git push -f`. Instead, always use a lease. This instructs Git to check if anyone else has pushed to your remote branch since you last fetched, preventing you from accidentally overwriting a coworker's or maintainer's work.

```shell
git push --force-with-lease
```

> [!TIP]
> Always git rebase on `upstream/master` on Flutter PRs.

### Interactive Rebase Workflow

Follow this sequence to cleanly update your feature branch and squash minor commits before requesting a review:

```shell
# Update your upstream master references and clean up deleted branches
git fetch upstream --tags --prune

# Or optionally fetch everything. Will take longer.
git fetch --all --tags --prune

# Start an interactive rebase on top of the fresh upstream master
git rebase -i upstream/master
```

**What this does:**

1. Opens your preferred editor with a list of your commits.
2. Allows you to `squash` (combine commits) or `fixup` (combine commits and discard the message). Use this to merge "typo fix" or "wip" commits into meaningful units of work.
3. Re-applies your newly cleaned, atomic commits sequentially directly on top of the latest upstream master

### Stacked PRs

What's better than one giant PR that might be expensive to review? Multiple small PRs that build on top of each other - each building successfully on their own.  GitHub doesn't properly support / render stacked PRs like GitLab / Graphite / others; but we can still achieve a happy path.

Let's say you have broken down a feature into two smaller ones, `feature-1a` and `feature-1b`.

**Base-feature**
Merge-Base: `master`
Head: `feature-1a`
GitHub UI: Shows only changes in `feature-1a`

**Stacked PR**
Merge-Base: `feature-1a`
Head: `feature-1b`
GitHub UI: Shows changes in `feature-1b`  - **only for branches on flutter/flutter**
Clean-diff: https://github.com/<GITHUB_USER>/flutter/compare/<feature-1a>...<feature-1b>

```shell
# 1. Start on latest HEAD
git worktree add feature-1a

# 2. Create Feature 1
cd feature-1a

# ... work, test, commit ...

# 3. Create the second part (Stacking on Feature 1)
git switch -c feature-1b

# ... work, test, commit ...

# Push both PRs
git push origin feature-1a
git push origin feature-1b

# Feedback comes in: changes requested in feature-1a; you are currently in feature 1b
# If its simple; you can interactive rebase and edit
git rebase -i --update-refs upstream/master

# If its not simple; you can checkout feature-1a, do some work, and rebase feature 1b
###
  git switch feature-1a

  # hack hack
  git add <files>
  git commit -m "Fix review comments"

  # Update feature-1b
  git switch feature-1b
  git rebase feature-1a
###

# Once done - update the PRs with lease
git push origin feature-1a # assumes you only made commits to feature-1a
git push --force-with-lease origin feature-1b
```

If you find yourself rebasing this stacked set of features on top of master; you can set the following to have git automatically move tracked branches:

```shell
git config --global rebase.updateRefs true
```

Example:

```shell
(Base)      A --- B --- C  [master]
                   \
(Stack 1)           D  [feature-1a]
                     \
(Stack 2)             E  [feature-1b] (HEAD) <- feature-1b is checked out

git rebase upstream/master

(Base)      A --- B --- C  [master]
                         \
(Stack 1)                 D' [feature-1a]  <-- MOVED AUTOMATICALLY!
                           \
(Stack 2)                   E' [feature-1b] (HEAD)
```

#### Landing feature-1a / updating feature-1b

Since Flutter squashes PRs before merging them to master, the history at master is NOT the same as the history in your stacked changes. If you were to rebase feature-1b onto master, you'll hit conflicts.  To get around this trap, you simply need to:

```shell
# 1. Update to get the new squash commit with feature-1a.
git fetch upstream --tags --prune

# 2. Rebase feature-1b onto master, ignoring the old feature-1a commits
# --onto <new-base> <old-base> <branch-to-move>
git rebase --onto upstream/master feature-1a feature-1b

# 3. Push the update.
git push --force-with-lease origin feature-1b
```