gitstow 0.2.6__tar.gz → 0.3.0__tar.gz

{gitstow-0.2.6 → gitstow-0.3.0}/.github/workflows/ci.yml

@@ -8,10 +8,14 @@ on:
 
 jobs:
   test:
-    runs-on: ubuntu-latest
     strategy:
       matrix:
+        os: [ubuntu-latest]
         python-version: ["3.10", "3.11", "3.12", "3.13"]
+        include:
+          - os: macos-latest
+            python-version: "3.12"
+    runs-on: ${{ matrix.os }}
 
     steps:
       - uses: actions/checkout@v4

{gitstow-0.2.6 → gitstow-0.3.0}/.github/workflows/publish.yml

@@ -5,7 +5,26 @@ on:
     tags: ["v*"]
 
 jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check src/
+
+      - name: Test
+        run: pytest --tb=short
+
   publish:
+    needs: test
     runs-on: ubuntu-latest
     environment: pypi
     permissions:

gitstow-0.3.0/AGENTS.md

@@ -0,0 +1,150 @@
+# gitstow - AI Developer Guide
+
+## What is this?
+
+A CLI tool that manages collections of git repositories across multiple workspaces. Think "package manager for repos" - whether they're open-source projects you learn from or active projects you work on.
+
+## Operating Contract
+
+- Prefer proper long-term solutions over shortcut patches. If a feature is incomplete in one surface, build the feature into that surface instead of papering over it with wording, partial conditionals, or one-off display logic.
+- Do not recommend quick fixes, temporary patches, or narrow workarounds unless the user explicitly asks for a shortcut.
+- Read the relevant existing code before proposing or editing. Let the current architecture decide where the change belongs.
+- Keep changes scoped to the requested behavior. Avoid unrelated refactors, formatting churn, or drive-by cleanups.
+- Do not revert user changes or generated local state unless the user explicitly asks.
+
+## Product Standards
+
+- Keep CLI, TUI, web dashboard, JSON output, docs, and tests semantically aligned when changing user-facing status behavior.
+- For repo state presentation, avoid using "dirty" as a broad user-facing bucket for every local change. Present it as local/uncommitted changes with the composition visible: modified, staged, and untracked counts.
+- Keep local working-tree state separate from remote relationship state. For example: local changes, clean, ahead, behind, diverged, frozen, missing.
+- When improving the web dashboard, implement the actual missing dashboard feature and shared classification/model behavior instead of copying a CLI-only assumption into the template.
+
+## Key Concept: Workspaces
+
+Repos are organized into **workspaces** - directories with a label and layout mode:
+- **structured** layout: `workspace/owner/repo/` (open-source collections)
+- **flat** layout: `workspace/repo/` (active projects, no owner subdirectory)
+
+Each workspace can have auto-tags applied to all repos it discovers.
+
+## Architecture
+
+```
+src/gitstow/
+├── cli/          # Typer commands (thin — delegates to core)
+│   ├── main.py          # App entry, command registration, global --workspace flag
+│   ├── helpers.py       # Shared workspace resolution, repo lookup, iteration
+│   ├── add.py, pull.py, list_cmd.py, status.py, remove.py  # Core commands
+│   ├── workspace_cmd.py # workspace list/add/remove/scan subcommands
+│   ├── manage.py        # freeze/unfreeze/tag/untag/info subcommands
+│   ├── exec_cmd.py, search.py, open_cmd.py, stats.py       # Power commands
+│   ├── export_cmd.py    # export/import collection
+│   ├── shell.py         # Shell integration (fzf, aliases)
+│   ├── tui.py           # TUI launcher
+│   ├── serve.py         # Web dashboard launcher
+│   ├── migrate.py, config_cmd.py, onboard.py, doctor.py, skill_cmd.py
+│   └── __init__.py
+├── core/         # Business logic (git ops, URL parsing, state)
+│   ├── paths.py       # Path constants, central repos.yaml resolution
+│   ├── config.py      # Workspace + Settings dataclasses, load/save
+│   ├── repo.py        # Repo dataclass + RepoStore (nested YAML CRUD)
+│   ├── url_parser.py  # URL → (host, owner, repo) extraction
+│   ├── git.py         # All git subprocess calls
+│   ├── discovery.py   # Walk directory tree (structured + flat), reconcile
+│   ├── parallel.py    # Async execution with semaphore
+│   └── __init__.py
+├── tui/          # Textual interactive dashboard
+│   ├── app.py         # Main TUI application
+│   └── __init__.py
+├── web/          # FastAPI browser dashboard (gitstow ui)
+│   ├── server.py          # FastAPI app, uvicorn runner, app.state.server stash
+│   ├── static/app.css     # Dark theme, Bricolage Grotesque + JetBrains Mono
+│   ├── templates/         # Jinja2 — base.html + page templates + partials/
+│   └── routes/            # dashboard.py, repos.py, workspaces.py, collection.py, pages.py, system.py
+└── skill/        # Codex skill (SKILL.md)
+    └── SKILL.md
+```
+
+**Key rules:**
+1. CLI never touches git directly - it calls `core/git.py`
+2. `core/repo.py` (RepoStore) is the only module that reads/writes `repos.yaml`
+3. `core/config.py` defines Workspace dataclass - all workspace logic flows from here
+4. `cli/helpers.py` provides `resolve_workspaces()`, `resolve_repo()`, `iter_repos_with_workspace()`
+
+## Key Files
+
+- `core/config.py` - Workspace + Settings dataclasses. `get_workspaces()` with legacy migration shim.
+- `core/repo.py` - Repo with workspace field, RepoStore with nested YAML format, legacy auto-migration.
+- `core/discovery.py` - `discover_repos(root, layout)` supports structured and flat layouts.
+- `core/url_parser.py` - URL parsing (the hardest part). Test changes here thoroughly.
+- `core/git.py` - All git subprocess calls. Uses `git status --porcelain=v2 --branch` for single-call efficiency.
+- `core/parallel.py` - Async execution with semaphore (max 6 concurrent).
+- `cli/helpers.py` - Shared workspace resolution used by all CLI commands.
+- `cli/workspace_cmd.py` - workspace list/add/remove/scan subcommands.
+- `cli/main.py` - Typer app, global `-w/--workspace` option, command registration.
+- `tui/app.py` - Textual dashboard with DataTable, filter, pull, freeze toggle.
+
+## Data Files
+
+- `~/.gitstow/config.yaml` - Settings (workspaces list, default host, SSH pref).
+- `~/.gitstow/repos.yaml` - Repo metadata nested by workspace label. Central location.
+
+### repos.yaml format
+```yaml
+oss:
+  anthropic/Codex:
+    remote_url: https://github.com/anthropic/Codex.git
+    tags: [ai]
+active:
+  gitstow:
+    remote_url: https://github.com/rishmadaan/gitstow.git
+    tags: [active]
+```
+
+## All Commands (32)
+
+**Core:** `add`, `pull`, `fetch`, `list`, `status`, `remove`, `migrate`
+**Workspace:** `workspace list`, `workspace add`, `workspace remove`, `workspace scan`
+**Repo management:** `repo freeze`, `repo unfreeze`, `repo tag`, `repo untag`, `repo tags`, `repo info`
+**Power:** `exec`, `search`, `open`, `stats`
+**Sharing:** `collection export`, `collection import`
+**Shell:** `shell pick`, `shell init`, `shell completions`, `shell setup`, `tui`, `ui`
+**Setup:** `onboard`, `config show/set/path/migrate-root`, `doctor`, `install-skill`, `setup-ai`, `update`
+
+## Development
+
+```bash
+cd ~/labs/projects/gitstow
+pip install -e ".[dev]"
+pytest                    # 44 tests
+ruff check src/
+pip install -e ".[tui]"   # For TUI development
+```
+
+## Patterns
+
+- `--json -j` and `--quiet -q` on all main commands
+- Global `-w/--workspace` flag filters all commands to a single workspace
+- `cli/helpers.py` for workspace resolution (don't repeat in each command)
+- Rich console for stdout, err_console for stderr
+- Typer with `rich_markup_mode="rich"`, `typer.Context` for global options
+- YAML for persistence (not JSON, not SQLite)
+- asyncio with semaphore for parallel git ops
+- `git status --porcelain=v2 --branch` for single-call status (vs gita's 4-5 calls)
+- Repo.global_key (`workspace:key`) for unique identification across workspaces
+- Legacy format auto-migration (flat repos.yaml -> nested, root_path -> workspaces)
+
+## AI Integration
+
+**Primary: Codex skill** (`src/gitstow/skill/SKILL.md`)
+- Installed to `~/.Codex/skills/gitstow/` via `gitstow install-skill` or `gitstow onboard`
+- Auto-updates on version bumps (checks `.version` marker on every CLI invocation)
+- Zero context cost when inactive - only loaded when task matches the skill description
+- Codex runs gitstow CLI commands via Bash - full access to all commands
+
+**Optional: MCP server** (`src/gitstow/mcp/server.py`)
+- For non-Codex AI tools (Codex Desktop, Cursor, Windsurf)
+- Install: `pip install gitstow[mcp]`, entry point: `gitstow-mcp`
+- 13 tools + 3 resources, wraps same `core/` modules as CLI
+- **Tradeoff:** MCP tools are always loaded into context (costs tokens even when idle).
+  The skill has no such cost. Only use MCP for dedicated repo-management setups.

{gitstow-0.2.6 → gitstow-0.3.0}/BACKLOG.md

@@ -9,9 +9,9 @@ Post-v0.1.0 improvements tracked here. See [GitHub Issues](https://github.com/ri
 - [x] **Network retry/resume for batch operations** (#3) — `--retry N` flag on add and pull; cleans up partial clones before retry
 - [x] **Export format versioning and checksums** (#4) — Added `version: 1` to YAML/JSON exports; validates on import; backward-compatible with unversioned files
 - [x] **Progress indication during long clones** (#5) — `git clone --progress`; pull shows live counter `[5/47]`
-- [x] **Publish to PyPI** (#6) — Release workflow created (`.github/workflows/release.yml`); publish on GitHub release
+- [x] **Publish to PyPI** (#6) — Release workflow created (`.github/workflows/publish.yml`); publish on GitHub release
 - [x] **Web dashboard (`gitstow ui`)** — Dark local browser UI wrapping core/ for daily repo management. FastAPI + Jinja2 + HTMX, dark + ember accent aesthetic. See [CHANGELOG.md](CHANGELOG.md) v0.2.0.
-- [ ] **Fix TUI breakage** — Multiple issues across the Textual TUI; currently unusable in daily flow. Keep around for SSH/remote use case but triage and repair when time allows.
+- [x] **Fix TUI breakage** — Resolved by retirement: the Textual TUI was removed in v0.3.0; `gitstow ui` (web dashboard) is the visual surface going forward.
 
 ## Documentation
 

{gitstow-0.2.6 → gitstow-0.3.0}/CHANGELOG.md

@@ -4,6 +4,66 @@ All notable changes to gitstow will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.3.0] - 2026-07-12
+
+### Added
+
+- **Composition-aware status everywhere.** `gitstow status` now shows a Local Changes column (modified/staged/untracked counts) and a separate Remote column (in-sync/ahead/behind/diverged). The web dashboard rows, repo drawer, and help legend all use the same shared classifier — a repo with only staged or untracked files can no longer display as "clean". JSON output gains additive `local` and `remote` keys (all existing keys preserved).
+- **`gitstow fetch_repos` MCP tool** and a `last_fetched` timestamp in all JSON outputs — MCP clients can now see fetch state, matching the CLI and web dashboard.
+- **Untracked-repo hints on `list` and `status`.** Repos found on disk but not in the registry are now surfaced with a hint pointing at `workspace scan`, instead of being silently invisible.
+- **`doctor` detects orphaned workspaces**, and `workspace remove` now warns when repos would be left pointing at a removed workspace.
+- **`clone_timeout` setting** (`gitstow config set clone_timeout <seconds>`) — clone operations on very large repos no longer fail on a hardcoded 300s limit.
+- **macOS added to the CI test matrix**, matching the packaging classifiers.
+- **CHANGELOG gate in the release script** — `scripts/release.sh` now refuses to cut a release without a corresponding changelog entry.
+
+### Changed
+
+- **`add` clones multiple repos in parallel** and now detects remote mismatches and duplicate URLs before cloning, instead of silently registering whatever is already on disk.
+- **`search` now runs across repos in parallel**, matching `exec`.
+- **Pull, fetch, and the MCP server share one operations layer.** The MCP server now follows the same bulk-pull rule as the CLI and web dashboard (modified/staged skip, diverged skip, untracked-only pulls).
+- **`open` prefers `$VISUAL`/`$EDITOR`** over guessing an editor, and runs terminal editors in the foreground so they actually get a usable TTY.
+- **Disk sizing (`stats`, `repo info`) now shells out to `du`** instead of walking every file in Python — much faster on large repos.
+- **`collection import` honors each entry's recorded workspace** instead of dumping everything into one workspace, and now fails loudly (with a printed error) on newer file versions instead of exiting silently.
+- **The web dashboard's dependencies (FastAPI, uvicorn, Jinja2) moved to the optional `[ui]` extra.** Existing installs keep working; fresh CLI-only installs are ~15 packages lighter. Install with `pip install "gitstow[ui]"` to keep the dashboard.
+- **Bulk pull rule unified and refined (behavior change).** CLI `pull` and the dashboard's Pull-all now follow one rule: repos with modified or staged files are skipped (with the composition shown), diverged repos are skipped (fast-forward pull cannot succeed), and repos with only untracked files ARE pulled — previously the CLI skipped them forever while the web pulled everything.
+
+### Fixed
+
+- **`search`, `exec`, and `status` `--json` now emit pure JSON on an empty filter match** — previously they printed a "no repos match" banner and no payload at all, even with `--json` set.
+
+### Removed
+
+- **The Textual TUI (`gitstow tui`).** The web dashboard (`gitstow ui`) replaced it as the visual surface in v0.2.0; the TUI had been broken and parked since. Git history preserves it.
+
+## [0.2.8] - 2026-07-12
+
+### Fixed
+
+- **Pasted GitHub browse URLs now resolve correctly.** URLs like `/tree/...`, `/blob/...`, `/pull/...` now resolve to the repo root instead of being misparsed.
+- **`config migrate-root`** now actually updates workspace paths, and honors the global `-w/--workspace` flag.
+- **`repo freeze/unfreeze/tag/untag`** now honor `-w/--workspace` and report cross-workspace ambiguity clearly instead of guessing.
+- **`pull --json` and `fetch --json`** always emit pure JSON on stdout — no more banners or progress lines interleaved with the payload.
+- **Pull summary** keeps per-workspace identity for same-named frozen repos in different workspaces.
+- **Bulk git operations** no longer hang on credential prompts and are now locale-independent.
+- **`remove --delete`** refuses to delete paths that resolve outside the workspace root.
+- **Workspace labels** are now validated (lowercase alphanumeric, dash, underscore only).
+
+### Added
+
+- **Atomic, cross-process-locked writes** to `repos.yaml`, safe for concurrent CLI and web UI use.
+- **Test gate before PyPI publish** — releases now require a passing test suite.
+
+### Security
+
+- **Web dashboard CSRF protection.** POST routes now reject cross-origin and DNS-rebinding requests on the localhost UI.
+
+## [0.2.7] - 2026-05-28
+
+### Fixed
+
+- **`gitstow onboard`** now uses Beaupy's `default_is_yes` confirmation parameter, fixing first-run setup crashes on confirmation prompts.
+- **AI integration setup** now renders MCP warning text with balanced Rich markup during onboarding and `gitstow setup-ai`.
+
 ## [0.2.5] - 2026-04-19
 
 ### Added

{gitstow-0.2.6 → gitstow-0.3.0}/CLAUDE.md

@@ -25,21 +25,20 @@ src/gitstow/
 │   ├── exec_cmd.py, search.py, open_cmd.py, stats.py       # Power commands
 │   ├── export_cmd.py    # export/import collection
 │   ├── shell.py         # Shell integration (fzf, aliases)
-│   ├── tui.py           # TUI launcher
 │   ├── serve.py         # Web dashboard launcher
 │   ├── migrate.py, config_cmd.py, onboard.py, doctor.py, skill_cmd.py
 │   └── __init__.py
 ├── core/         # Business logic (git ops, URL parsing, state)
-│   ├── paths.py       # Path constants, central repos.yaml resolution
-│   ├── config.py      # Workspace + Settings dataclasses, load/save
-│   ├── repo.py        # Repo dataclass + RepoStore (nested YAML CRUD)
-│   ├── url_parser.py  # URL → (host, owner, repo) extraction
-│   ├── git.py         # All git subprocess calls
-│   ├── discovery.py   # Walk directory tree (structured + flat), reconcile
-│   ├── parallel.py    # Async execution with semaphore
-│   └── __init__.py
-├── tui/          # Textual interactive dashboard
-│   ├── app.py         # Main TUI application
+│   ├── paths.py         # Path constants, central repos.yaml resolution
+│   ├── config.py        # Workspace + Settings dataclasses, load/save
+│   ├── repo.py          # Repo dataclass + RepoStore (nested YAML CRUD)
+│   ├── url_parser.py    # URL → (host, owner, repo) extraction
+│   ├── git.py           # All git subprocess calls
+│   ├── discovery.py     # Walk directory tree (structured + flat), reconcile
+│   ├── parallel.py      # Async execution with semaphore
+│   ├── status_model.py  # Shared repo-state classifier — local composition vs remote relationship
+│   ├── operations.py    # Shared filter + bulk-runner layer (pull/fetch/MCP)
+│   ├── locking.py       # Cross-process file lock guarding repos.yaml writes
 │   └── __init__.py
 ├── web/          # FastAPI browser dashboard (gitstow ui)
 │   ├── server.py          # FastAPI app, uvicorn runner, app.state.server stash
@@ -64,15 +63,18 @@ src/gitstow/
 - `core/url_parser.py` — URL parsing (the hardest part). Test changes here thoroughly.
 - `core/git.py` — All git subprocess calls. Uses `git status --porcelain=v2 --branch` for single-call efficiency.
 - `core/parallel.py` — Async execution with semaphore (max 6 concurrent).
+- `core/status_model.py` — `RepoState` — the single source of truth for local (modified/staged/untracked) vs remote (in-sync/ahead/behind/diverged) classification, consumed by CLI, web, and JSON.
+- `core/operations.py` — Shared `filter_repo_pairs()` + bulk-runner used by `pull`, `fetch`, and the MCP server so surfaces can't drift.
+- `core/locking.py` — `file_lock()` cross-process advisory lock guarding `repos.yaml` against concurrent CLI/web writes.
 - `cli/helpers.py` — Shared workspace resolution used by all CLI commands.
 - `cli/workspace_cmd.py` — workspace list/add/remove/scan subcommands.
 - `cli/main.py` — Typer app, global `-w/--workspace` option, command registration.
-- `tui/app.py` — Textual dashboard with DataTable, filter, pull, freeze toggle.
 
 ## Data Files
 
 - `~/.gitstow/config.yaml` — Settings (workspaces list, default host, SSH pref).
 - `~/.gitstow/repos.yaml` — Repo metadata nested by workspace label. Central location.
+- `~/.gitstow/repos.lock` — Cross-process advisory lock file (`core/locking.py`) held during `repos.yaml` writes. Not user-facing data; safe to ignore/delete if orphaned.
 
 ### repos.yaml format
 ```yaml
@@ -86,14 +88,14 @@ active:
     tags: [active]
 ```
 
-## All Commands (32)
+## All Commands (37)
 
 **Core:** `add`, `pull`, `fetch`, `list`, `status`, `remove`, `migrate`
 **Workspace:** `workspace list`, `workspace add`, `workspace remove`, `workspace scan`
 **Repo management:** `repo freeze`, `repo unfreeze`, `repo tag`, `repo untag`, `repo tags`, `repo info`
 **Power:** `exec`, `search`, `open`, `stats`
 **Sharing:** `collection export`, `collection import`
-**Shell:** `shell pick`, `shell init`, `shell completions`, `shell setup`, `tui`, `ui`
+**Shell:** `shell pick`, `shell init`, `shell completions`, `shell setup`, `ui`
 **Setup:** `onboard`, `config show/set/path/migrate-root`, `doctor`, `install-skill`, `setup-ai`, `update`
 
 ## Development
@@ -101,9 +103,8 @@ active:
 ```bash
 cd ~/labs/projects/gitstow
 pip install -e ".[dev]"
-pytest                    # 44 tests
+pytest                    # full suite — keep green
 ruff check src/
-pip install -e ".[tui]"   # For TUI development
 ```
 
 ## Patterns
@@ -119,6 +120,15 @@ pip install -e ".[tui]"   # For TUI development
 - Repo.global_key (`workspace:key`) for unique identification across workspaces
 - Legacy format auto-migration (flat repos.yaml → nested, root_path → workspaces)
 
+## Product & Implementation Standards
+
+- Prefer proper long-term solutions over shortcut patches. If a feature is incomplete in one surface, build the feature into that surface instead of papering over it with wording, partial conditionals, or one-off display logic.
+- Do not recommend quick fixes, temporary patches, or narrow workarounds unless the user explicitly asks for a shortcut.
+- Keep CLI, web dashboard, JSON output, docs, and tests semantically aligned when changing user-facing status behavior.
+- For repo state presentation, avoid using "dirty" as a broad user-facing bucket for every local change. Present it as local/uncommitted changes with the composition visible: modified, staged, and untracked counts.
+- Keep local working-tree state separate from remote relationship state. For example: local changes, clean, ahead, behind, diverged, frozen, missing.
+- When improving the web dashboard, implement the actual missing dashboard feature and shared classification/model behavior instead of copying a CLI-only assumption into the template.
+
 ## AI Integration
 
 **Primary: Claude Code skill** (`src/gitstow/skill/SKILL.md`)
@@ -130,6 +140,6 @@ pip install -e ".[tui]"   # For TUI development
 **Optional: MCP server** (`src/gitstow/mcp/server.py`)
 - For non-Claude-Code AI tools (Claude Desktop, Cursor, Windsurf)
 - Install: `pip install gitstow[mcp]`, entry point: `gitstow-mcp`
-- 13 tools + 3 resources, wraps same `core/` modules as CLI
+- 14 tools + 3 resources, wraps same `core/` modules as CLI
 - **Tradeoff:** MCP tools are always loaded into context (costs tokens even when idle).
   The skill has no such cost. Only use MCP for dedicated repo-management setups.

{gitstow-0.2.6 → gitstow-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitstow
-Version: 0.2.6
+Version: 0.3.0
 Summary: A git repository library manager — clone, organize, and maintain collections of repos you learn from
 Project-URL: Homepage, https://github.com/rishmadaan/gitstow
 Project-URL: Repository, https://github.com/rishmadaan/gitstow
@@ -26,21 +26,25 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Version Control :: Git
 Requires-Python: >=3.10
 Requires-Dist: beaupy>=3.0
-Requires-Dist: fastapi>=0.110
-Requires-Dist: jinja2>=3.1
-Requires-Dist: python-multipart>=0.0.9
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=13.0
-Requires-Dist: typer[all]>=0.9
-Requires-Dist: uvicorn>=0.27
+Requires-Dist: typer>=0.9
 Provides-Extra: dev
+Requires-Dist: fastapi>=0.110; extra == 'dev'
 Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: jinja2>=3.1; extra == 'dev'
+Requires-Dist: mcp>=1.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: python-multipart>=0.0.9; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: uvicorn>=0.27; extra == 'dev'
 Provides-Extra: mcp
 Requires-Dist: mcp>=1.0; extra == 'mcp'
-Provides-Extra: tui
-Requires-Dist: textual>=0.50; extra == 'tui'
+Provides-Extra: ui
+Requires-Dist: fastapi>=0.110; extra == 'ui'
+Requires-Dist: jinja2>=3.1; extra == 'ui'
+Requires-Dist: python-multipart>=0.0.9; extra == 'ui'
+Requires-Dist: uvicorn>=0.27; extra == 'ui'
 Description-Content-Type: text/markdown
 
 # gitstow
@@ -62,8 +66,8 @@ Existing tools solve parts of this:
 ## Quick Start
 
 ```bash
-pipx install gitstow   # recommended
-# or: pip install gitstow
+pipx install "gitstow[ui]"   # recommended — CLI + browser dashboard
+# or: pip install gitstow    # CLI only; add [ui] for the dashboard
 
 # First-run setup (optional — works without it)
 gitstow onboard
@@ -99,6 +103,8 @@ gitstow workspace scan active
 ```bash
 gitstow add anthropic/claude-code facebook/react torvalds/linux
 ```
+Multiple URLs clone concurrently (bounded by `parallel_limit`, default 6) — a mismatched remote on an existing path errors instead of silently registering, and duplicate URLs in the same invocation are deduped.
+
 Creates (in a structured workspace):
 ```
 ~/oss/
@@ -117,8 +123,9 @@ gitstow -w oss pull             # Only update oss workspace
 gitstow pull --tag ai           # Only repos tagged 'ai'
 gitstow pull --exclude-tag stale # Everything except stale repos
 gitstow status                  # Git status dashboard
-gitstow -w active status --dirty # Dirty repos in active workspace
+gitstow -w active status --dirty # Repos with local changes in active workspace
 ```
+`status` shows local changes as a composition (e.g. "2 modified · 1 staged · 3 untracked") rather than a single "dirty" bucket, and keeps the remote relationship (ahead/behind/diverged) in its own column.
 
 ### Freeze & Tags
 ```bash
@@ -182,17 +189,13 @@ gsp                              # gitstow pull shorthand
 
 ### Browser Dashboard
 ```bash
-gitstow ui             # opens http://127.0.0.1:7853 in your browser
+pip install "gitstow[ui]"   # if you installed CLI-only
+gitstow ui                  # opens http://127.0.0.1:7853 in your browser
 gitstow ui --port 8080
 gitstow ui --no-browser
 ```
 Persistent local web dashboard for daily repo management — a tab you leave open. Shows dirty state across your library, pulls single repos or all-of-them with a parallel summary panel, adds/removes repos, edits tags, freezes stale ones. Auto-refreshes row status every 30 seconds. Binds `127.0.0.1` only (arbitrary git execution must not be LAN-reachable). Click **Shutdown** in the footer — or Ctrl+C — to stop.
 
-### Interactive Dashboard (TUI)
-```bash
-gitstow tui    # Keyboard-driven terminal dashboard (SSH-friendly)
-```
-
 ### JSON Output
 Every command supports `--json` for scripting and AI consumption:
 ```bash
@@ -237,7 +240,6 @@ gitstow status --json
 | `gitstow shell init` | Print shell functions to source in rc file |
 | `gitstow shell pick` | fzf-powered repo picker |
 | `gitstow shell completions` | Tab completion for repo names, workspaces, tags |
-| `gitstow tui` | Interactive terminal dashboard |
 | `gitstow fetch` | Fetch all remotes — update ahead/behind counts without merging |
 | `gitstow ui` | Launch local browser dashboard (http://127.0.0.1:7853) |
 | `gitstow update` | Upgrade gitstow itself from PyPI (detects pipx / pip / editable) |

{gitstow-0.2.6 → gitstow-0.3.0}/README.md

@@ -17,8 +17,8 @@ Existing tools solve parts of this:
 ## Quick Start
 
 ```bash
-pipx install gitstow   # recommended
-# or: pip install gitstow
+pipx install "gitstow[ui]"   # recommended — CLI + browser dashboard
+# or: pip install gitstow    # CLI only; add [ui] for the dashboard
 
 # First-run setup (optional — works without it)
 gitstow onboard
@@ -54,6 +54,8 @@ gitstow workspace scan active
 ```bash
 gitstow add anthropic/claude-code facebook/react torvalds/linux
 ```
+Multiple URLs clone concurrently (bounded by `parallel_limit`, default 6) — a mismatched remote on an existing path errors instead of silently registering, and duplicate URLs in the same invocation are deduped.
+
 Creates (in a structured workspace):
 ```
 ~/oss/
@@ -72,8 +74,9 @@ gitstow -w oss pull             # Only update oss workspace
 gitstow pull --tag ai           # Only repos tagged 'ai'
 gitstow pull --exclude-tag stale # Everything except stale repos
 gitstow status                  # Git status dashboard
-gitstow -w active status --dirty # Dirty repos in active workspace
+gitstow -w active status --dirty # Repos with local changes in active workspace
 ```
+`status` shows local changes as a composition (e.g. "2 modified · 1 staged · 3 untracked") rather than a single "dirty" bucket, and keeps the remote relationship (ahead/behind/diverged) in its own column.
 
 ### Freeze & Tags
 ```bash
@@ -137,17 +140,13 @@ gsp                              # gitstow pull shorthand
 
 ### Browser Dashboard
 ```bash
-gitstow ui             # opens http://127.0.0.1:7853 in your browser
+pip install "gitstow[ui]"   # if you installed CLI-only
+gitstow ui                  # opens http://127.0.0.1:7853 in your browser
 gitstow ui --port 8080
 gitstow ui --no-browser
 ```
 Persistent local web dashboard for daily repo management — a tab you leave open. Shows dirty state across your library, pulls single repos or all-of-them with a parallel summary panel, adds/removes repos, edits tags, freezes stale ones. Auto-refreshes row status every 30 seconds. Binds `127.0.0.1` only (arbitrary git execution must not be LAN-reachable). Click **Shutdown** in the footer — or Ctrl+C — to stop.
 
-### Interactive Dashboard (TUI)
-```bash
-gitstow tui    # Keyboard-driven terminal dashboard (SSH-friendly)
-```
-
 ### JSON Output
 Every command supports `--json` for scripting and AI consumption:
 ```bash
@@ -192,7 +191,6 @@ gitstow status --json
 | `gitstow shell init` | Print shell functions to source in rc file |
 | `gitstow shell pick` | fzf-powered repo picker |
 | `gitstow shell completions` | Tab completion for repo names, workspaces, tags |
-| `gitstow tui` | Interactive terminal dashboard |
 | `gitstow fetch` | Fetch all remotes — update ahead/behind counts without merging |
 | `gitstow ui` | Launch local browser dashboard (http://127.0.0.1:7853) |
 | `gitstow update` | Upgrade gitstow itself from PyPI (detects pipx / pip / editable) |