worktree-flash 0.1.0__tar.gz

worktree_flash-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,21 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v4
+
+      - run: uv build
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

worktree_flash-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+dist/
+*.egg-info/
+.flash/

worktree_flash-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Will Twait
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

worktree_flash-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: worktree-flash
+Version: 0.1.0
+Summary: Preview worktree branches from your main checkout while safely stashing your working state.
+Project-URL: Homepage, https://github.com/WillTwait/flash
+Project-URL: Repository, https://github.com/WillTwait/flash
+Author: Will Twait
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,git,stash,worktree
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Requires-Dist: typer>=0.15.0
+Description-Content-Type: text/markdown
+
+<h1 align="center">⚡ flash</h1>
+
+<p align="center">
+  Preview worktree branches from your main checkout while safely stashing your working state.
+</p>
+
+<p align="center">
+  <img src="assets/cli.png" alt="flash cli" width="700">
+</p>
+
+## Why
+
+Worktrees are great for parallelizing work, but your dev environment — backend servers, locally running frontend, etc — lives in your main checkout. When you need to test changes on a worktree, you're stuck doing a manual stash-checkout-test-restore dance, carefully tracking not to throw away diffs on either branch.
+
+`flash` does the whole dance in one command and tracks every step so nothing gets lost.
+
+Inspired by [Conductor's Spotlight](https://docs.conductor.build/guides/spotlight-testing).
+
+## Install
+
+```bash
+uv tool install worktree-flash        # or pipx install worktree-flash
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/WillTwait/flash.git
+uv tool install ./flash
+```
+
+Requires Python 3.10+.
+
+## Commands
+
+| Command               | Alias      | Description                                        |
+| --------------------- | ---------- | -------------------------------------------------- |
+| `flash into [name]`   | `flash i`  | Switch to a worktree's branch (or open fzf picker) |
+| `flash out`           | `flash o`  | End flash, restore original branch + stash         |
+| `flash out --apply`   |            | End flash, send changes to worktree first          |
+| `flash out --discard` |            | End flash, throw away changes                      |
+| `flash apply`         | `flash a`  | Send changes to worktree without ending flash      |
+| `flash status`        | `flash st` | Show current flash state                           |
+
+## Typical workflow
+
+<img src="assets/demo.gif" alt="flash workflow demo" width="700">
+
+```bash
+flash into my-worktree    # stash, checkout worktree branch
+# run server, test, poke around, fix things, commit
+flash apply                # cherry-pick commits + sync files back to worktree
+# keep testing
+flash out                  # restore original branch, pop stash, clean up
+```
+
+## Details
+
+`flash into` — switch your checkout to a worktree's branch
+
+1. Stash uncommitted changes (tracked by SHA)
+2. Create and checkout a temp branch at the worktree's HEAD
+3. Copy the worktree's uncommitted changes into your checkout
+4. Write `.flash/state.json` to track everything
+
+Pass a worktree name or branch, or omit for an fzf picker.
+
+`flash apply` — send your changes back to the worktree
+
+1. Back up the worktree's state via `git stash create`
+2. Clean the worktree for a conflict-free cherry-pick
+3. Cherry-pick new commits into the worktree's history
+4. Copy uncommitted file changes to the worktree
+
+Safe to run multiple times. If anything fails, the backup stash SHA is printed for recovery.
+
+`flash out` — restore your original branch
+
+1. Prompt `[a]pply / [d]iscard` if you have unsent changes
+2. Checkout your original branch
+3. Delete the temp branch
+4. Pop your stash by SHA
+5. Remove `.flash/` entirely
+
+## Usage with Claude Code
+
+Add this to your project's `CLAUDE.md` so Claude understands how to use flash:
+
+```markdown
+## Flash (worktree previewing)
+
+`flash` is installed and available for previewing worktree branches from the main checkout.
+
+- `flash into <name>` — switch to a worktree branch (stashes current work automatically)
+- `flash out --discard` — restore original branch (use `--apply` to send changes back to worktree)
+- `flash apply` — send commits + uncommitted changes to the worktree without ending the flash
+- `flash status` — check current flash state
+
+When you need to test or review code from a worktree, use `flash into` instead of manually
+checking out branches. Always `flash out` when done.
+```
+
+## Safety
+
+| Risk                           | Mitigation                                           |
+| ------------------------------ | ---------------------------------------------------- |
+| Losing stashed changes         | Tracked by SHA, not index position                   |
+| Losing worktree state on apply | `git stash create` backup before any destructive op  |
+| Double flash                   | Refused if already flashed in                        |
+| Branch conflict with worktree  | Uses `flash/<branch>` temp branch                    |
+| Interrupted mid-operation      | State file has everything needed for manual recovery |
+| Non-interactive (CI/agents)    | Defaults to `--discard` with a warning               |

worktree_flash-0.1.0/README.md

@@ -0,0 +1,112 @@
+<h1 align="center">⚡ flash</h1>
+
+<p align="center">
+  Preview worktree branches from your main checkout while safely stashing your working state.
+</p>
+
+<p align="center">
+  <img src="assets/cli.png" alt="flash cli" width="700">
+</p>
+
+## Why
+
+Worktrees are great for parallelizing work, but your dev environment — backend servers, locally running frontend, etc — lives in your main checkout. When you need to test changes on a worktree, you're stuck doing a manual stash-checkout-test-restore dance, carefully tracking not to throw away diffs on either branch.
+
+`flash` does the whole dance in one command and tracks every step so nothing gets lost.
+
+Inspired by [Conductor's Spotlight](https://docs.conductor.build/guides/spotlight-testing).
+
+## Install
+
+```bash
+uv tool install worktree-flash        # or pipx install worktree-flash
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/WillTwait/flash.git
+uv tool install ./flash
+```
+
+Requires Python 3.10+.
+
+## Commands
+
+| Command               | Alias      | Description                                        |
+| --------------------- | ---------- | -------------------------------------------------- |
+| `flash into [name]`   | `flash i`  | Switch to a worktree's branch (or open fzf picker) |
+| `flash out`           | `flash o`  | End flash, restore original branch + stash         |
+| `flash out --apply`   |            | End flash, send changes to worktree first          |
+| `flash out --discard` |            | End flash, throw away changes                      |
+| `flash apply`         | `flash a`  | Send changes to worktree without ending flash      |
+| `flash status`        | `flash st` | Show current flash state                           |
+
+## Typical workflow
+
+<img src="assets/demo.gif" alt="flash workflow demo" width="700">
+
+```bash
+flash into my-worktree    # stash, checkout worktree branch
+# run server, test, poke around, fix things, commit
+flash apply                # cherry-pick commits + sync files back to worktree
+# keep testing
+flash out                  # restore original branch, pop stash, clean up
+```
+
+## Details
+
+`flash into` — switch your checkout to a worktree's branch
+
+1. Stash uncommitted changes (tracked by SHA)
+2. Create and checkout a temp branch at the worktree's HEAD
+3. Copy the worktree's uncommitted changes into your checkout
+4. Write `.flash/state.json` to track everything
+
+Pass a worktree name or branch, or omit for an fzf picker.
+
+`flash apply` — send your changes back to the worktree
+
+1. Back up the worktree's state via `git stash create`
+2. Clean the worktree for a conflict-free cherry-pick
+3. Cherry-pick new commits into the worktree's history
+4. Copy uncommitted file changes to the worktree
+
+Safe to run multiple times. If anything fails, the backup stash SHA is printed for recovery.
+
+`flash out` — restore your original branch
+
+1. Prompt `[a]pply / [d]iscard` if you have unsent changes
+2. Checkout your original branch
+3. Delete the temp branch
+4. Pop your stash by SHA
+5. Remove `.flash/` entirely
+
+## Usage with Claude Code
+
+Add this to your project's `CLAUDE.md` so Claude understands how to use flash:
+
+```markdown
+## Flash (worktree previewing)
+
+`flash` is installed and available for previewing worktree branches from the main checkout.
+
+- `flash into <name>` — switch to a worktree branch (stashes current work automatically)
+- `flash out --discard` — restore original branch (use `--apply` to send changes back to worktree)
+- `flash apply` — send commits + uncommitted changes to the worktree without ending the flash
+- `flash status` — check current flash state
+
+When you need to test or review code from a worktree, use `flash into` instead of manually
+checking out branches. Always `flash out` when done.
+```
+
+## Safety
+
+| Risk                           | Mitigation                                           |
+| ------------------------------ | ---------------------------------------------------- |
+| Losing stashed changes         | Tracked by SHA, not index position                   |
+| Losing worktree state on apply | `git stash create` backup before any destructive op  |
+| Double flash                   | Refused if already flashed in                        |
+| Branch conflict with worktree  | Uses `flash/<branch>` temp branch                    |
+| Interrupted mid-operation      | State file has everything needed for manual recovery |
+| Non-interactive (CI/agents)    | Defaults to `--discard` with a warning               |

worktree_flash-0.1.0/assets/demo.tape

@@ -0,0 +1,38 @@
+Output assets/demo.gif
+Set Width 800
+Set Height 500
+Set FontSize 14
+Set Padding 20
+Set Shell "zsh"
+
+Hide
+Type "cd ~/Developer/flash-demo"
+Enter
+Sleep 1s
+Show
+
+# Flash into — fzf picker
+Type "flash into"
+Enter
+Sleep 1s
+Up
+Sleep 500ms
+Up
+Sleep 500ms
+Enter
+Sleep 2s
+
+# Check status
+Type "flash status"
+Enter
+Sleep 2s
+
+# Apply changes to worktree
+Type "flash apply"
+Enter
+Sleep 2s
+
+# Flash out
+Type "flash out --discard"
+Enter
+Sleep 2s

worktree_flash-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "worktree-flash"
+version = "0.1.0"
+description = "Preview worktree branches from your main checkout while safely stashing your working state."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Will Twait" }]
+keywords = ["git", "worktree", "cli", "stash"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Software Development :: Version Control :: Git",
+]
+dependencies = [
+    "typer>=0.15.0",
+]
+
+[project.scripts]
+flash = "flash.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/WillTwait/flash"
+Repository = "https://github.com/WillTwait/flash"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/flash"]

worktree_flash-0.1.0/src/flash/cli.py

@@ -0,0 +1,356 @@
+"""Typer CLI entry point for flash."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import typer
+
+from flash.core import (
+    FlashError,
+    checkout_branch,
+    cherry_pick_to_worktree,
+    clean_working_tree,
+    create_and_checkout_temp_branch,
+    delete_branch,
+    ensure_git_exclude,
+    fzf_pick_worktree,
+    get_canonical_root,
+    get_commits_since,
+    get_current_branch,
+    get_head_sha,
+    is_dirty,
+    list_worktrees,
+    pop_stash_by_sha,
+    resolve_worktree,
+    stash_changes,
+    stash_create,
+    sync_changes,
+)
+from flash.state import FlashState, clear_state, now_iso, read_state, write_state
+
+app = typer.Typer(
+    help="Safely swap your main checkout to a worktree branch and back.",
+    no_args_is_help=True,
+)
+
+
+def _err(msg: str) -> None:
+    typer.secho(msg, fg=typer.colors.RED, err=True)
+
+
+def _ok(msg: str) -> None:
+    typer.secho(msg, fg=typer.colors.GREEN)
+
+
+def _info(msg: str) -> None:
+    typer.secho(msg, fg=typer.colors.YELLOW)
+
+
+def _apply_to_worktree(state: FlashState, canonical_root: str) -> None:
+    """Cherry-pick commits and sync unstaged files to the worktree.
+
+    Strategy:
+    1. Safety backup: `git stash create` in worktree (read-only)
+    2. Clean the worktree so cherry-pick can't conflict
+    3. Cherry-pick new commits onto clean worktree
+    4. Copy uncommitted files from canonical → worktree
+    5. Update state so next apply only picks new commits
+    """
+
+    commits = get_commits_since(state.flash_base_sha, cwd=canonical_root)
+    has_uncommitted = is_dirty(cwd=canonical_root)
+
+    if not commits and not has_uncommitted:
+        _info("No changes to apply.")
+        return
+
+    # Safety backup of worktree state (read-only, no side effects)
+    safety_sha = stash_create(cwd=state.worktree_path)
+
+    try:
+        if commits:
+            # Clean worktree for conflict-free cherry-pick
+            clean_working_tree(cwd=state.worktree_path)
+            cherry_pick_to_worktree(commits, state.worktree_path)
+            _ok(f"Cherry-picked {len(commits)} commit(s) to worktree.")
+
+            # Update base SHA so next apply only picks new commits
+            new_base = get_head_sha(cwd=canonical_root)
+            state.flash_base_sha = new_base
+            write_state(state)
+
+        if has_uncommitted:
+            synced = sync_changes("HEAD", canonical_root, state.worktree_path)
+            if synced:
+                _ok(f"Synced {len(synced)} uncommitted file(s) to worktree:")
+                for f in synced:
+                    typer.echo(f"  {f}")
+
+    except FlashError:
+        if safety_sha:
+            _err(f"Worktree state backed up as stash {safety_sha}")
+            _err(
+                f"  Recover with: cd {state.worktree_path} && git stash apply {safety_sha}"
+            )
+        raise
+
+
+def _complete_worktree_name(incomplete: str) -> list[str]:
+    """Tab-completion for worktree names."""
+    try:
+        canonical_root = get_canonical_root()
+    except FlashError:
+        return []
+    worktrees = list_worktrees(cwd=canonical_root)
+    names = []
+    for wt in worktrees:
+        if wt.is_bare or wt.path == canonical_root:
+            continue
+        dir_name = Path(wt.path).name
+        if incomplete in dir_name:
+            names.append(dir_name)
+        elif incomplete in wt.branch:
+            names.append(wt.branch)
+    return names
+
+
+@app.command()
+def into(
+    name: str | None = typer.Argument(
+        None,
+        help="Worktree directory name or branch name",
+        autocompletion=_complete_worktree_name,
+    ),
+) -> None:
+    """Flash into a worktree branch on the canonical checkout. [magenta]\\[alias: i][/magenta]"""
+    try:
+        canonical_root = get_canonical_root()
+    except FlashError as e:
+        _err(str(e))
+        raise typer.Exit(1)
+
+    # Check if already flashed in
+    existing = read_state(canonical_root)
+    if existing is not None:
+        _err(f"Already flashed into '{existing.flash_branch}'. Run 'flash out' first.")
+        raise typer.Exit(1)
+
+    # Resolve the target worktree
+    if name is None:
+        wt = fzf_pick_worktree(canonical_root)
+        if wt is None:
+            _err("No worktree selected.")
+            raise typer.Exit(1)
+    else:
+        wt = resolve_worktree(name, cwd=canonical_root)
+        if wt is None:
+            # Show available worktrees
+            worktrees = list_worktrees(cwd=canonical_root)
+            _err(f"Could not resolve '{name}' to a worktree.")
+            _info("Available worktrees:")
+            for w in worktrees:
+                if not w.is_bare and w.path != canonical_root:
+                    typer.echo(f"  {w.branch}  ({w.path})")
+            raise typer.Exit(1)
+
+    # Don't flash into the canonical root itself
+    if wt.path == canonical_root:
+        _err("Cannot flash into the canonical checkout itself.")
+        raise typer.Exit(1)
+
+    try:
+        # Record current state
+        original_branch = get_current_branch(cwd=canonical_root)
+        original_head_sha = get_head_sha(cwd=canonical_root)
+
+        # Stash if dirty
+        stash_sha = None
+        if is_dirty(cwd=canonical_root):
+            _info("Stashing uncommitted changes...")
+            stash_sha = stash_changes(f"flash: before {wt.branch}", cwd=canonical_root)
+
+        # Create and checkout temp branch at worktree branch's HEAD
+        temp_branch = f"flash/{wt.branch}"
+        _info(f"Creating temp branch '{temp_branch}' at {wt.head[:8]}...")
+        create_and_checkout_temp_branch(temp_branch, wt.head, cwd=canonical_root)
+
+        # Copy uncommitted changes from worktree into canonical checkout
+        wt_synced = sync_changes("HEAD", wt.path, canonical_root)
+        if wt_synced:
+            _info(f"Copied {len(wt_synced)} uncommitted file(s) from worktree.")
+
+        # Ensure .flash/ is excluded from git
+        ensure_git_exclude(canonical_root)
+
+        # Write state — flash_base_sha is the worktree's HEAD (temp branch start)
+        state = FlashState(
+            original_branch=original_branch,
+            flash_branch=wt.branch,
+            temp_branch=temp_branch,
+            worktree_path=wt.path,
+            canonical_root=canonical_root,
+            original_head_sha=original_head_sha,
+            flash_base_sha=wt.head,
+            stash_sha=stash_sha,
+            started_at=now_iso(),
+        )
+        write_state(state)
+
+        _ok(f"Flashed into '{wt.branch}'. Run 'flash out' when done.")
+
+    except FlashError as e:
+        _err(str(e))
+        raise typer.Exit(1)
+
+
+@app.command()
+def out(
+    apply: bool = typer.Option(
+        False, "--apply", help="Apply changes to worktree before exiting"
+    ),
+    discard: bool = typer.Option(
+        False, "--discard", help="Discard changes made during flash"
+    ),
+) -> None:
+    """End flash session and restore original state. [magenta]\\[alias: o][/magenta]"""
+    try:
+        canonical_root = get_canonical_root()
+    except FlashError as e:
+        _err(str(e))
+        raise typer.Exit(1)
+
+    state = read_state(canonical_root)
+    if state is None:
+        _err("Not currently flashed in.")
+        raise typer.Exit(1)
+
+    try:
+        # Check for any changes (commits or unstaged)
+        commits = get_commits_since(state.flash_base_sha, cwd=canonical_root)
+        has_unstaged = is_dirty(cwd=canonical_root)
+        has_changes = bool(commits) or has_unstaged
+
+        if has_changes:
+            if apply and discard:
+                _err("Cannot use both --apply and --discard.")
+                raise typer.Exit(1)
+
+            if not apply and not discard:
+                # Interactive: prompt user
+                if sys.stdin.isatty():
+                    _info("You have changes during this flash.")
+                    if commits:
+                        _info(f"  {len(commits)} commit(s)")
+                    if has_unstaged:
+                        _info("  Uncommitted file changes")
+                    choice = (
+                        typer.prompt(
+                            "[a]pply to worktree / [d]iscard",
+                            default="d",
+                        )
+                        .strip()
+                        .lower()
+                    )
+                    apply = choice in ("a", "apply")
+                    discard = not apply
+                else:
+                    _info("Non-interactive mode: discarding changes.")
+                    discard = True
+
+            if apply:
+                _apply_to_worktree(state, canonical_root)
+
+        # Discard any local changes before switching branches
+        if is_dirty(cwd=canonical_root):
+            clean_working_tree(cwd=canonical_root)
+
+        # Restore original branch
+        _info(f"Checking out '{state.original_branch}'...")
+        checkout_branch(state.original_branch, cwd=canonical_root)
+
+        # Delete temp branch
+        delete_branch(state.temp_branch, cwd=canonical_root)
+
+        # Pop stash if we stashed
+        if state.stash_sha:
+            _info("Restoring stashed changes...")
+            if not pop_stash_by_sha(state.stash_sha, cwd=canonical_root):
+                _err(
+                    f"Warning: Could not find stash with SHA {state.stash_sha}. "
+                    f"Your changes may still be in the stash list."
+                )
+
+        # Clean up state
+        clear_state(canonical_root)
+
+        _ok(f"Back on '{state.original_branch}'.")
+
+    except FlashError as e:
+        _err(str(e))
+        _err("State file preserved for manual recovery.")
+        raise typer.Exit(1)
+
+
+@app.command()
+def status() -> None:
+    """Show current flash state. [magenta]\\[alias: st][/magenta]"""
+    try:
+        canonical_root = get_canonical_root()
+    except FlashError as e:
+        _err(str(e))
+        raise typer.Exit(1)
+
+    state = read_state(canonical_root)
+    if state is None:
+        typer.echo("Not flashed in.")
+        raise typer.Exit(0)
+
+    typer.echo(f"Flashed into: {state.flash_branch}")
+    typer.echo(f"Original branch: {state.original_branch}")
+    typer.echo(f"Temp branch: {state.temp_branch}")
+    typer.echo(f"Worktree: {state.worktree_path}")
+    typer.echo(f"Started: {state.started_at}")
+    if state.stash_sha:
+        typer.echo(f"Stash SHA: {state.stash_sha}")
+
+    # Show if there are current changes
+    commits = get_commits_since(state.flash_base_sha, cwd=canonical_root)
+    has_unstaged = is_dirty(cwd=canonical_root)
+    if commits:
+        _info(f"{len(commits)} new commit(s) since flash.")
+    if has_unstaged:
+        _info("Uncommitted file changes.")
+
+
+@app.command("apply")
+def apply_changes() -> None:
+    """Push current changes to the worktree without ending the flash. [magenta]\\[alias: a][/magenta]"""
+    try:
+        canonical_root = get_canonical_root()
+    except FlashError as e:
+        _err(str(e))
+        raise typer.Exit(1)
+
+    state = read_state(canonical_root)
+    if state is None:
+        _err("Not currently flashed in.")
+        raise typer.Exit(1)
+
+    try:
+        _apply_to_worktree(state, canonical_root)
+    except FlashError as e:
+        _err(str(e))
+        raise typer.Exit(1)
+
+
+# Hidden short aliases
+app.command("i", hidden=True)(into)
+app.command("o", hidden=True)(out)
+app.command("st", hidden=True)(status)
+app.command("a", hidden=True)(apply_changes)
+
+
+if __name__ == "__main__":
+    app()

worktree_flash-0.1.0/src/flash/core.py

@@ -0,0 +1,362 @@
+"""Git operations for flash: stash, checkout, diff, apply."""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+
+class FlashError(Exception):
+    """Raised when a flash operation fails."""
+
+
+@dataclass
+class Worktree:
+    path: str
+    branch: str
+    head: str
+    is_bare: bool = False
+
+
+def run_git(
+    *args: str,
+    cwd: str | Path | None = None,
+    check: bool = True,
+    capture: bool = True,
+) -> subprocess.CompletedProcess[str]:
+    """Run a git command and return the result."""
+    cmd = ["git", *args]
+    result = subprocess.run(
+        cmd,
+        cwd=cwd,
+        capture_output=capture,
+        text=True,
+        check=False,
+    )
+    if check and result.returncode != 0:
+        raise FlashError(f"git {' '.join(args)} failed:\n{result.stderr.strip()}")
+    return result
+
+
+def get_canonical_root(cwd: str | Path | None = None) -> str:
+    """Get the canonical (non-worktree) repo root.
+
+    If we're in a worktree, resolve via .git commondir to find the main checkout.
+    """
+    cwd = cwd or Path.cwd()
+    # Get the git dir for current location
+    git_dir = run_git("rev-parse", "--git-dir", cwd=cwd).stdout.strip()
+    git_dir_path = Path(git_dir) if Path(git_dir).is_absolute() else Path(cwd) / git_dir
+    git_dir_path = git_dir_path.resolve()
+
+    # If this is a worktree, .git is a file pointing to the main repo's worktrees dir
+    # Use --git-common-dir to find the main repo's .git directory
+    common_dir = run_git("rev-parse", "--git-common-dir", cwd=cwd).stdout.strip()
+    common_dir_path = (
+        Path(common_dir) if Path(common_dir).is_absolute() else Path(cwd) / common_dir
+    )
+    common_dir_path = common_dir_path.resolve()
+
+    # The canonical root is the parent of the common .git dir
+    return str(common_dir_path.parent)
+
+
+def get_current_branch(cwd: str | Path | None = None) -> str:
+    """Get the current branch name."""
+    result = run_git("symbolic-ref", "--short", "HEAD", cwd=cwd, check=False)
+    if result.returncode != 0:
+        # Detached HEAD — return the SHA
+        return run_git("rev-parse", "HEAD", cwd=cwd).stdout.strip()
+    return result.stdout.strip()
+
+
+def get_head_sha(cwd: str | Path | None = None) -> str:
+    """Get the current HEAD SHA."""
+    return run_git("rev-parse", "HEAD", cwd=cwd).stdout.strip()
+
+
+def is_dirty(cwd: str | Path | None = None) -> bool:
+    """Check if the working tree has uncommitted changes."""
+    result = run_git("status", "--porcelain", cwd=cwd)
+    return bool(result.stdout.strip())
+
+
+def list_worktrees(cwd: str | Path | None = None) -> list[Worktree]:
+    """List all git worktrees."""
+    result = run_git("worktree", "list", "--porcelain", cwd=cwd)
+    worktrees: list[Worktree] = []
+    current: dict[str, str] = {}
+
+    for line in result.stdout.splitlines():
+        if not line.strip():
+            if current:
+                worktrees.append(
+                    Worktree(
+                        path=current["worktree"],
+                        branch=current.get("branch", "").removeprefix("refs/heads/"),
+                        head=current.get("HEAD", ""),
+                        is_bare="bare" in current,
+                    )
+                )
+                current = {}
+            continue
+        if line.startswith("worktree "):
+            current["worktree"] = line.split(" ", 1)[1]
+        elif line.startswith("HEAD "):
+            current["HEAD"] = line.split(" ", 1)[1]
+        elif line.startswith("branch "):
+            current["branch"] = line.split(" ", 1)[1]
+        elif line == "bare":
+            current["bare"] = "true"
+        elif line == "detached":
+            pass  # skip detached marker
+
+    # Handle last entry
+    if current:
+        worktrees.append(
+            Worktree(
+                path=current["worktree"],
+                branch=current.get("branch", "").removeprefix("refs/heads/"),
+                head=current.get("HEAD", ""),
+                is_bare="bare" in current,
+            )
+        )
+
+    return worktrees
+
+
+def resolve_worktree(name: str, cwd: str | Path | None = None) -> Worktree | None:
+    """Resolve a name to a worktree by matching directory name or branch name."""
+    worktrees = list_worktrees(cwd=cwd)
+
+    for wt in worktrees:
+        if wt.is_bare:
+            continue
+        dir_name = Path(wt.path).name
+        if dir_name == name or wt.branch == name:
+            return wt
+
+    # Partial match on directory name or branch name
+    matches = []
+    for wt in worktrees:
+        if wt.is_bare:
+            continue
+        dir_name = Path(wt.path).name
+        if name in dir_name or name in wt.branch:
+            matches.append(wt)
+
+    if len(matches) == 1:
+        return matches[0]
+
+    return None
+
+
+def fzf_pick_worktree(canonical_root: str) -> Worktree | None:
+    """Use fzf to interactively pick a worktree."""
+    worktrees = list_worktrees(cwd=canonical_root)
+    # Filter out bare and the canonical root itself
+    candidates = [
+        wt for wt in worktrees if not wt.is_bare and wt.path != canonical_root
+    ]
+
+    if not candidates:
+        return None
+
+    # Format for fzf: "dir_name  (branch)  path"
+    lines = []
+    for wt in candidates:
+        dir_name = Path(wt.path).name
+        lines.append(f"{dir_name}\t{wt.branch}\t{wt.path}")
+
+    fzf_input = "\n".join(lines)
+
+    try:
+        result = subprocess.run(
+            [
+                "fzf",
+                "--header=Select a worktree",
+                "--delimiter=\t",
+                "--with-nth=1,2",
+                "--tabstop=4",
+            ],
+            input=fzf_input,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except FileNotFoundError:
+        raise FlashError("fzf not found. Install fzf or pass a worktree name.")
+
+    if result.returncode != 0:
+        return None  # User cancelled
+
+    selected = result.stdout.strip()
+    if not selected:
+        return None
+
+    parts = selected.split("\t")
+    selected_path = parts[2] if len(parts) >= 3 else parts[0]
+
+    for wt in candidates:
+        if wt.path == selected_path:
+            return wt
+
+    return None
+
+
+def stash_changes(message: str, cwd: str | Path | None = None) -> str | None:
+    """Stash changes and return the stash SHA, or None if nothing to stash."""
+    # Get stash list before
+    before = run_git("stash", "list", cwd=cwd).stdout.strip()
+
+    run_git("stash", "push", "-m", message, "--include-untracked", cwd=cwd)
+
+    # Get stash list after
+    after = run_git("stash", "list", cwd=cwd).stdout.strip()
+
+    if before == after:
+        return None  # Nothing was stashed
+
+    # Get the SHA of the most recent stash
+    return run_git("rev-parse", "stash@{0}", cwd=cwd).stdout.strip()
+
+
+def find_stash_by_sha(sha: str, cwd: str | Path | None = None) -> str | None:
+    """Find a stash entry by its SHA. Returns the stash ref (e.g., stash@{2})."""
+    result = run_git("stash", "list", "--format=%H", cwd=cwd)
+    for i, line in enumerate(result.stdout.strip().splitlines()):
+        if line.strip() == sha:
+            return f"stash@{{{i}}}"
+    return None
+
+
+def pop_stash_by_sha(sha: str, cwd: str | Path | None = None) -> bool:
+    """Pop a specific stash entry identified by SHA. Returns True if successful."""
+    ref = find_stash_by_sha(sha, cwd=cwd)
+    if ref is None:
+        return False
+    run_git("stash", "pop", ref, cwd=cwd)
+    return True
+
+
+def create_and_checkout_temp_branch(
+    temp_branch: str, target_sha: str, cwd: str | Path | None = None
+) -> None:
+    """Create a temporary branch at target_sha and check it out."""
+    # Delete if it already exists (leftover from a crashed session)
+    result = run_git("branch", "--list", temp_branch, cwd=cwd)
+    if result.stdout.strip():
+        run_git("branch", "-D", temp_branch, cwd=cwd)
+
+    run_git("checkout", "-b", temp_branch, target_sha, cwd=cwd)
+
+
+def checkout_branch(branch: str, cwd: str | Path | None = None) -> None:
+    """Check out a branch."""
+    run_git("checkout", branch, cwd=cwd)
+
+
+def delete_branch(branch: str, cwd: str | Path | None = None) -> None:
+    """Delete a branch."""
+    run_git("branch", "-D", branch, cwd=cwd, check=False)
+
+
+def get_changed_files(ref: str, cwd: str | Path | None = None) -> list[str]:
+    """Get list of files changed between ref and working tree, including untracked."""
+    run_git("add", "-A", cwd=cwd)
+    result = run_git("diff", "--cached", "--name-only", ref, cwd=cwd)
+    run_git("reset", "HEAD", cwd=cwd, check=False)
+    return [f for f in result.stdout.strip().splitlines() if f.strip()]
+
+
+def has_changes_against(ref: str, cwd: str | Path | None = None) -> bool:
+    """Check if there are any changes between ref and working tree."""
+    return bool(get_changed_files(ref, cwd=cwd))
+
+
+def sync_changes(ref: str, src_dir: str | Path, dst_dir: str | Path) -> list[str]:
+    """Copy changed files from src_dir to dst_dir.
+
+    Compares src_dir's working tree against ref to find changed files,
+    then copies each one to dst_dir. This is more reliable than patching
+    because it handles repeated applies correctly — the target always gets
+    the current state of each changed file.
+
+    Returns list of file paths synced.
+    """
+    import shutil
+
+    src = Path(src_dir)
+    dst = Path(dst_dir)
+    changed = get_changed_files(ref, cwd=src_dir)
+
+    synced: list[str] = []
+    for filepath in changed:
+        src_file = src / filepath
+        dst_file = dst / filepath
+
+        if src_file.is_file():
+            dst_file.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(str(src_file), str(dst_file))
+            synced.append(filepath)
+        elif dst_file.is_file():
+            # File was deleted in source
+            dst_file.unlink()
+            synced.append(filepath)
+
+    return synced
+
+
+def get_commits_since(base_sha: str, cwd: str | Path | None = None) -> list[str]:
+    """Get list of commit SHAs on current branch since base_sha (oldest first)."""
+    result = run_git("log", "--format=%H", "--reverse", f"{base_sha}..HEAD", cwd=cwd)
+    return [sha for sha in result.stdout.strip().splitlines() if sha.strip()]
+
+
+def stash_create(cwd: str | Path | None = None) -> str | None:
+    """Create a stash commit without modifying working tree or stash list.
+
+    This is a read-only safety backup. Returns the stash SHA, or None
+    if the working tree is clean.
+    """
+    result = run_git("stash", "create", cwd=cwd)
+    sha = result.stdout.strip()
+    return sha if sha else None
+
+
+def clean_working_tree(cwd: str | Path | None = None) -> None:
+    """Reset working tree to HEAD — discard all changes and untracked files."""
+    run_git("checkout", ".", cwd=cwd)
+    run_git("clean", "-fd", cwd=cwd)
+
+
+def cherry_pick_to_worktree(commits: list[str], worktree_path: str | Path) -> int:
+    """Cherry-pick commits onto a clean worktree. Returns count picked.
+
+    The worktree MUST be clean before calling this — the caller is
+    responsible for saving and restoring any uncommitted state.
+    """
+    if not commits:
+        return 0
+    for sha in commits:
+        run_git("cherry-pick", sha, cwd=worktree_path)
+    return len(commits)
+
+
+def ensure_git_exclude(canonical_root: str | Path) -> None:
+    """Add .flash/ to .git/info/exclude if not already there."""
+    exclude_file = Path(canonical_root) / ".git" / "info" / "exclude"
+    exclude_file.parent.mkdir(parents=True, exist_ok=True)
+
+    entry = ".flash/"
+    if exclude_file.exists():
+        content = exclude_file.read_text()
+        if entry in content:
+            return
+        if not content.endswith("\n"):
+            content += "\n"
+        content += entry + "\n"
+        exclude_file.write_text(content)
+    else:
+        exclude_file.write_text(entry + "\n")

worktree_flash-0.1.0/src/flash/state.py

@@ -0,0 +1,64 @@
+"""State file read/write/clear for flash sessions."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+STATE_DIR = ".flash"
+STATE_FILE = "state.json"
+
+
+@dataclass
+class FlashState:
+    original_branch: str
+    flash_branch: str
+    temp_branch: str
+    worktree_path: str
+    canonical_root: str
+    original_head_sha: str
+    flash_base_sha: str
+    started_at: str
+    stash_sha: str | None = None
+
+
+def state_dir(canonical_root: str | Path) -> Path:
+    return Path(canonical_root) / STATE_DIR
+
+
+def state_path(canonical_root: str | Path) -> Path:
+    return state_dir(canonical_root) / STATE_FILE
+
+
+def read_state(canonical_root: str | Path) -> FlashState | None:
+    """Read the current flash state, or None if not flashed in."""
+    path = state_path(canonical_root)
+    if not path.exists():
+        return None
+    data = json.loads(path.read_text())
+    # Filter to known fields so old state files with removed fields still load
+    known = {f.name for f in FlashState.__dataclass_fields__.values()}
+    return FlashState(**{k: v for k, v in data.items() if k in known})
+
+
+def write_state(state: FlashState) -> None:
+    """Write flash state to disk."""
+    directory = state_dir(state.canonical_root)
+    directory.mkdir(parents=True, exist_ok=True)
+    path = directory / STATE_FILE
+    path.write_text(json.dumps(asdict(state), indent=2) + "\n")
+
+
+def clear_state(canonical_root: str | Path) -> None:
+    """Remove the .flash directory entirely."""
+    import shutil
+
+    directory = state_dir(canonical_root)
+    if directory.exists():
+        shutil.rmtree(directory)
+
+
+def now_iso() -> str:
+    return datetime.now(UTC).isoformat()

worktree_flash-0.1.0/test_flash.sh

@@ -0,0 +1,155 @@
+#!/usr/bin/env bash
+# Integration test for flash CLI.
+# Creates a temp repo with a worktree, runs all commands, and verifies results.
+set -euo pipefail
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+NC='\033[0m'
+PASS=0
+FAIL=0
+
+assert_eq() {
+    local desc="$1" expected="$2" actual="$3"
+    if [ "$expected" = "$actual" ]; then
+        echo -e "${GREEN}PASS${NC}: $desc"
+        PASS=$((PASS + 1))
+    else
+        echo -e "${RED}FAIL${NC}: $desc"
+        echo "  expected: $expected"
+        echo "  actual:   $actual"
+        FAIL=$((FAIL + 1))
+    fi
+}
+
+assert_contains() {
+    local desc="$1" needle="$2" haystack="$3"
+    if echo "$haystack" | grep -q "$needle"; then
+        echo -e "${GREEN}PASS${NC}: $desc"
+        PASS=$((PASS + 1))
+    else
+        echo -e "${RED}FAIL${NC}: $desc"
+        echo "  expected to contain: $needle"
+        echo "  actual: $haystack"
+        FAIL=$((FAIL + 1))
+    fi
+}
+
+assert_file_content() {
+    local desc="$1" file="$2" expected="$3"
+    local actual
+    actual=$(cat "$file")
+    assert_eq "$desc" "$expected" "$actual"
+}
+
+# --- Setup ---
+TMPDIR=$(mktemp -d)
+REPO="$TMPDIR/repo"
+WT="$TMPDIR/worktree"
+trap "rm -rf $TMPDIR" EXIT
+
+mkdir "$REPO"
+cd "$REPO"
+git init -q
+echo "original" > file.txt
+git add . && git commit -q -m "initial"
+
+git worktree add -q "$WT" -b test-branch
+echo "committed-change" > "$WT/new-file.txt"
+(cd "$WT" && git add . && git commit -q -m "worktree commit")
+# Add uncommitted change in worktree
+echo "uncommitted-change" > "$WT/uncommitted.txt"
+echo "committed-change
+extra-line" > "$WT/new-file.txt"
+
+# Dirty the main checkout
+echo "dirty" > "$REPO/dirty.txt"
+
+echo ""
+echo "=== Test 1: flash into ==="
+cd "$REPO"
+output=$(flash into test-branch 2>&1)
+assert_contains "stash message" "Stashing" "$output"
+assert_contains "flash message" "Flashed into" "$output"
+
+echo ""
+echo "=== Test 2: flash status ==="
+output=$(flash status 2>&1)
+assert_contains "shows branch" "test-branch" "$output"
+assert_contains "shows original" "main" "$output"
+
+echo ""
+echo "=== Test 3: uncommitted changes copied in ==="
+assert_file_content "uncommitted file present" "$REPO/uncommitted.txt" "uncommitted-change"
+assert_file_content "modified file has worktree state" "$REPO/new-file.txt" "committed-change
+extra-line"
+
+echo ""
+echo "=== Test 4: double flash refused ==="
+output=$(flash into test-branch 2>&1 || true)
+assert_contains "refuses double flash" "Already flashed" "$output"
+
+echo ""
+echo "=== Test 5: flash apply (unstaged files) ==="
+echo "flash-fix" >> "$REPO/new-file.txt"
+output=$(flash apply 2>&1)
+assert_contains "apply syncs files" "Synced" "$output"
+assert_file_content "worktree gets unstaged fix" "$WT/new-file.txt" "committed-change
+extra-line
+flash-fix"
+
+echo ""
+echo "=== Test 6: flash apply (commits) ==="
+echo "committed-fix" > "$REPO/committed-file.txt"
+(cd "$REPO" && git add . && git commit -q -m "fix during flash")
+output=$(flash apply 2>&1)
+assert_contains "cherry-pick message" "Cherry-picked 1 commit" "$output"
+# The committed file should now be in the worktree's git history
+wt_has_commit=$(cd "$WT" && git log --oneline | grep -c "fix during flash" || true)
+assert_eq "commit landed in worktree" "1" "$wt_has_commit"
+
+echo ""
+echo "=== Test 7: flash out --apply (commits + unstaged) ==="
+echo "second-committed" > "$REPO/second.txt"
+(cd "$REPO" && git add . && git commit -q -m "second fix")
+echo "loose-change" > "$REPO/loose.txt"
+output=$(flash out --apply 2>&1)
+assert_contains "cherry-pick on exit" "Cherry-picked 1 commit" "$output"
+assert_contains "sync on exit" "Synced" "$output"
+assert_contains "back on main" "Back on" "$output"
+
+# Verify commit landed in worktree
+wt_has_second=$(cd "$WT" && git log --oneline | grep -c "second fix" || true)
+assert_eq "second commit in worktree" "1" "$wt_has_second"
+# Verify unstaged file synced
+assert_file_content "loose file in worktree" "$WT/loose.txt" "loose-change"
+
+# Verify restoration
+assert_eq "back on main" "main" "$(git branch --show-current)"
+assert_file_content "stash restored" "$REPO/dirty.txt" "dirty"
+assert_eq "no .flash dir" "false" "$([ -d "$REPO/.flash" ] && echo true || echo false)"
+assert_eq "temp branch deleted" "" "$(git branch --list 'flash/*')"
+
+echo ""
+echo "=== Test 8: flash out --discard ==="
+flash into test-branch >/dev/null 2>&1
+echo "throwaway" >> "$REPO/new-file.txt"
+wt_before=$(cd "$WT" && git log --oneline | wc -l | tr -d ' ')
+flash out --discard >/dev/null 2>&1
+wt_after=$(cd "$WT" && git log --oneline | wc -l | tr -d ' ')
+assert_eq "discard doesn't touch worktree" "$wt_before" "$wt_after"
+
+echo ""
+echo "=== Test 9: flash from worktree directory ==="
+cd "$WT"
+flash into test-branch >/dev/null 2>&1
+output=$(flash status 2>&1)
+assert_contains "works from worktree" "Flashed into: test-branch" "$output"
+canonical_branch=$(cd "$REPO" && git branch --show-current)
+assert_eq "canonical checkout switched" "flash/test-branch" "$canonical_branch"
+flash out --discard >/dev/null 2>&1
+
+echo ""
+echo "================================"
+echo -e "Results: ${GREEN}$PASS passed${NC}, ${RED}$FAIL failed${NC}"
+[ "$FAIL" -eq 0 ] && exit 0 || exit 1