Separating Tangled Changes into Clean PRs

Problem

A working tree accumulates uncommitted changes from multiple features over time. When you need to create focused PRs, the changes are tangled together — some files have changes from multiple features, generated files (like .mocks.dart) reflect all features combined, and pre-commit hooks fail on unrelated WIP code.

Context / Trigger Conditions

• Working tree has 50+ modified/untracked files spanning multiple features
• git diff --name-only shows files from clearly different features
• You need to create a PR for Feature A but Feature B's files cause analysis errors
• Pre-commit hooks run dart analyze / eslint / etc. on ALL files (not just staged), so untracked WIP files block commits
• Some files have changes from BOTH features (mixed-change files)

Solution

Step 1: Stash Everything Safely

git stash -u -m "descriptive-name-for-safety"

The -u flag includes untracked files. This is your safety net.

Step 2: Create Clean Feature Branch

git checkout main  # or the appropriate base
git pull
git checkout -b feature/clean-branch

Step 3: Pop Stash and Handle Conflicts

git stash pop

Common issue: "already exists, no checkout" — happens when untracked files from the stash already exist in the working tree. The tracked file changes still apply, but the stash is preserved (not dropped). This is safe; the files you need are already there.

Merge conflicts: Resolve each one. For files belonging to OTHER features, take the base version:

git checkout --theirs path/to/other-feature-file.dart

For files belonging to THIS feature, take the stash version or resolve manually.

Step 4: Handle Mixed-Change Files

Some files have changes from BOTH features. For these:

1. Restore to the base version: git checkout main -- path/to/file.dart
2. Re-apply ONLY your feature's changes manually (usually just import changes or a few lines)

Step 5: Deal with Pre-Commit Hooks That Check All Files

If your pre-commit hook analyzes ALL files (not just staged), untracked WIP files from other features will block your commit.

Workaround: Temporarily move problematic untracked files:

mkdir -p /tmp/other-features-backup
mv lib/unrelated_feature/ /tmp/other-features-backup/
mv test/unrelated_feature/ /tmp/other-features-backup/

Commit, then restore:

cp -r /tmp/other-features-backup/* .

Step 6: Regenerate Generated Files

If the project uses code generation (Mockito, Riverpod, Freezed, etc.), restore generated files to base and regenerate:

git checkout main -- **/*.mocks.dart **/*.g.dart
dart run build_runner build --delete-conflicting-outputs

This ensures generated files only reflect YOUR feature's changes.

Step 7: Fix Interface Break Cascades

When Feature A changes an interface (renames a method, changes parameter types), consumer files that weren't modified by Feature A will break. The analyzer catches these. Fix them before committing.

Common pattern:

• Provider state changed CompleteParameters? to Map<String, dynamic>
• Canvas widget still calls .colorFilters on what's now a Map
• Fix: Update the consumer to use the new interface

Step 8: Do NOT Stack PRs — Combine Dependent Features Into One PR

Never create a PR that targets another PR's branch instead of main. Stacked PRs cause real problems in this project: rebases cascade, reviewer context fragments, merge order becomes load-bearing, CI runs against the wrong base, and "fix on parent" forces a re-review of the child.

If Feature B depends on Feature A, ship them as ONE combined PR.

# Both features live on a single branch, targeting main
git checkout main && git pull
git checkout -b feature-a-and-b
# ... commit Feature A changes ...
# ... commit Feature B changes (separate commits are fine) ...
gh pr create --base main  # one PR, both features

Write the PR description so the two features are clearly delineated — separate sections, separate test plans. Reviewers can read it as a single unit, and the merge story is one click. This is the default when changes are interdependent.

The only time to split is when the features are truly independent — in which case they each get their own PR targeting main, in any order. If you find yourself wanting "B based on A," that's the signal to combine them, not to stack.

Verification

1. git diff main...HEAD --stat shows only files for YOUR feature
2. dart analyze (or equivalent) passes
3. Tests pass
4. Original stash still exists as safety net (if pop failed partially): git stash list

Example

Session where model-dedup changes and collaborator/watermark feature changes were tangled in 140+ modified files. The model-dedup work was independent of the collab/watermark feature, so they split cleanly:

1. Stashed everything from fix/profile-copy-shares-url
2. Created chore/model-deduplication from main, popped stash
3. Separated model-dedup files, moved 16 untracked feature files to /tmp/
4. Committed, pushed, created PR #1411 (target: main)
5. Created feat/collabs-watermark-inspired-by from main, popped stash
6. Fixed 3 interface breaks in video_editor_canvas.dart and video_metadata_preview_thumbnail.dart
7. Committed, pushed, created PR #1412 (target: main — independent of #1411)

If the two features had been interdependent, they would have shipped as one combined PR — never stacked.

Alternative: Cherry-Pick Commits + Selective Stash Apply

When changes are split between commits AND stash (not just stash), use this approach instead:

# 1. Create branches from origin/main
git branch feature-a origin/main
git branch feature-b origin/main

# 2. Cherry-pick commits to appropriate branches
git checkout feature-a
git cherry-pick <commit-hash-for-feature-a>

# 3. Apply stashed files selectively (see gotchas below)

GOTCHA: Deleted Files in Stash

git checkout stash@{0} -- <path> FAILS for files that were DELETED in the stash — they don't exist in the stash tree. Handle deletions separately:

# For MODIFIED files — checkout from stash works
git checkout stash@{0} -- path/to/modified_file.dart

# For DELETED files — must use git rm instead
git rm path/to/deleted_file.dart

# Check which are deletions vs modifications first:
git stash show stash@{0} --name-status
# D = deleted (use git rm), M = modified (use checkout)

GOTCHA: Mono-Repo Stash Path Prefixes

When git root is a parent directory but you work in a subdirectory, stash paths include the subdirectory prefix:

# Working in: /project/mobile/
# Git root:   /project/
# Stash shows: mobile/lib/file.dart (NOT lib/file.dart)

# Must run checkout from repo root:
cd $(git rev-parse --show-toplevel)
git checkout stash@{0} -- mobile/lib/file.dart

GOTCHA: Cherry-Pick Produces Empty Commit

If a commit was already merged to main via a different PR (different hash), cherry-pick will produce an empty commit:

# "The previous cherry-pick is now empty"
git cherry-pick --skip  # Skip it, it's already on main

GOTCHA: Pre-Commit Hooks on Cherry-Picked Branches

When cherry-picking onto branches from origin/main, the analyzer may find pre-existing errors on main unrelated to your changes. Use --no-verify only when you've confirmed the errors aren't yours:

git commit --no-verify -m "feat: your changes"

Verify Completeness

Compare stash contents against all branch diffs:

git stash show stash@{0} --name-only | sort > /tmp/stash_files.txt
git diff --name-only origin/main..feature-a
git diff --name-only origin/main..feature-b
# Every stash file should appear in exactly one branch

Notes

• Always stash with -u to capture untracked files
• Never force-drop a stash until you've verified everything is safe
• Mixed-change files are the hardest part — identify them early by checking which files have changes from multiple features
• Pre-commit hooks that check all files (not just staged) are the biggest blocker. Know your project's hook behavior before starting.
• Never stack PRs. Always target main. If features depend on each other, combine them into one bigger PR — see Step 8.
• The stash is preserved when pop fails on untracked files — don't panic, your data is safe