gitstow 0.7.0__tar.gz → 0.7.2__tar.gz

{gitstow-0.7.0 → gitstow-0.7.2}/.gitignore

@@ -11,6 +11,8 @@ build/
 .venv/
 venv/
 env/
+# uv's resolver lockfile — gitstow ships via pip/pipx/PyPI, not uv sync
+uv.lock
 
 # IDE
 .idea/

{gitstow-0.7.0 → gitstow-0.7.2}/AGENTS.md

@@ -73,7 +73,7 @@ src/gitstow/
 
 ## Key Files
 
-- `core/config.py` — Workspace + Settings dataclasses. `get_workspaces()` with legacy migration shim.
+- `core/config.py` — Workspace + Settings dataclasses. `get_workspaces()` returns exactly what is configured and **never synthesizes a workspace**; zero workspaces is a valid state and `get_default_workspace()` returns `None` for it. The legacy `root_path` → `oss` migration shim lives only in `load_config()`, where it is persisted to disk. Both one-time migrations (`root_path` → `oss`, and adopting the pre-0.7.2 implicit `oss` workspace at `~/opensource`) run there too, gated by `config_version` — the provenance marker every save writes, which is what keeps an explicit `workspaces: []` from being re-migrated into a workspace the user just removed. `NO_WORKSPACES_HINT` is the one empty-state message every surface (CLI, MCP, web) reuses.
 - `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.
@@ -144,7 +144,7 @@ ruff check src/
 - 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)
+- Legacy format auto-migration (flat repos.yaml → nested, root_path → workspaces) — migration happens in `load_config()` and is written to disk, never synthesized on read
 
 ## AI Integration
 

{gitstow-0.7.0 → gitstow-0.7.2}/CHANGELOG.md

@@ -4,6 +4,29 @@ 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.7.2] - 2026-09-03
+
+### Fixed
+
+- **A fresh install no longer invents an `oss` workspace at `~/opensource`** — with nothing configured, gitstow used to conjure a workspace that lived only in memory. It could not be removed (`workspace remove oss` refused: "Cannot remove the only workspace"), it could not be replaced (`workspace add ... --label oss` refused: "already exists"), removing it from the dashboard silently did nothing because the page re-conjured it on the next render, and `gitstow add owner/repo` quietly cloned into `~/opensource` under a workspace label that appeared nowhere in your config. Zero workspaces is now a real, visible state: `get_workspaces()` returns exactly what you configured, every surface shows the same empty state with the same one-line fix (`gitstow workspace add <path> --label <name>`, or `gitstow onboard`), and you may remove your last workspace — the CLI tells you what to do next, and the dashboard's library, add-repo, and workspaces pages each show an empty-state card instead of a dead form or a phantom row. The legacy `root_path` → `oss` migration is unchanged and still runs, but only in `load_config()` where it is written to disk, so what you see is what your config holds. `~/opensource` survives solely as the path `gitstow onboard` suggests for your first workspace.
+- **The empty state now reaches every surface that needed it** — `gitstow onboard` works on a config with zero workspaces (it used to refuse because the *file* existed, and `--force` silently reset `parallel_limit`, `clone_timeout` and `ui_tailscale`); `gitstow pull owner/repo` and `gitstow fetch owner/repo` stop with the hint instead of "No repos to pull"; the MCP tools `list_repos`, `pull_repos`, `fetch_repos`, `search_repos`, `collection_stats` and `repo_status` return the hint instead of a success-shaped empty result; the dashboard's Settings page shows the empty-state card in place of the collection-import form, and a POST to it answers with that page rather than raw JSON; the library page no longer renders its "Pull all" / "Fetch all" bar and repo filters with no workspace to act on, and those endpoints answer with the empty-state card instead of a zero-item summary or a wall of "workspace not found"; `gitstow doctor` prints workspace labels in its orphan reports again (Rich was parsing `[label]` as a style tag and swallowing it) and skips the SSH probe when nothing is configured; and the terminal hint prints each command on its own line so it never wraps mid-command.
+- **`--json` runs now get the empty state as JSON, not silence** — with zero workspaces configured, `add`, `pull`, `fetch`, `list`, `status`, `exec`, `search`, `stats` and `migrate` exited 1 with an empty stdout and the hint as prose on stderr, so anything parsing stdout (scripts, the Claude Code skill) saw a crash rather than "nothing configured yet". With `--json` they now write `{"success": false, "error": "No workspaces configured…"}` to stdout, in the same shape as every other JSON failure, and still exit 1. Without `--json` nothing changes.
+- **One orphaned repo no longer aborts a bulk pull or fetch** — `gitstow pull good orphan`, where `orphan` is tracked under a workspace that has since left your config, exited 1 while building the target list and never touched `good`. It now warns and skips that one repo — the same contract as the existing "not tracked. Skipping." path — so the valid repos named alongside it still run. In `--json` mode the warning goes to stderr and stdout stays the result payload. Naming only the orphan still ends in "No repos to pull."
+
+### Changed
+
+- **Upgrading from 0.7.1 or earlier adopts your implicit `oss` workspace** — installs where `gitstow add` had cloned into `~/opensource` without ever writing a config now get that workspace written to `config.yaml` once, silently, on the next command, so those repos stay visible (if `~/opensource` no longer exists, nothing is invented and `gitstow doctor` reports the leftover records). The adoption only ever looks at configs that predate this version — every config gitstow writes from now on carries a `config_version` marker, so once you remove `oss` yourself it stays removed.
+
+## [0.7.1] - 2026-08-11
+
+### Added
+
+- **Tailscale toggle on the dashboard Settings page** — `ui_tailscale` was the last config field you could only set from the CLI. Because it applies when the server binds its sockets, the page never pretends the change is live: it compares what you saved against what the running server actually bound and tells you to restart `gitstow ui`. On a machine without the Tailscale CLI the row is disabled with the reason shown, and saving there leaves an existing `ui_tailscale: true` (e.g. a config synced from another machine) untouched rather than silently clearing it.
+
+### Changed
+
+- **`gitstow ui --tailscale` now prints the tailnet IP** instead of the MagicDNS name — the IP works from any peer, while the name depends on the other device's DNS. The MagicDNS name (and short name) still work if you type them.
+
 ## [0.7.0] - 2026-08-11
 
 ### Added

{gitstow-0.7.0 → gitstow-0.7.2}/CLAUDE.md

@@ -39,6 +39,7 @@ src/gitstow/
 │   ├── 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
+│   ├── tailscale.py     # Tailscale CLI detection (tailnet IP + MagicDNS) for ui --tailscale
 │   └── __init__.py
 ├── web/          # FastAPI browser dashboard (gitstow ui)
 │   ├── server.py          # FastAPI app, uvicorn runner, app.state.server stash
@@ -57,7 +58,7 @@ src/gitstow/
 
 ## Key Files
 
-- `core/config.py` — Workspace + Settings dataclasses. `get_workspaces()` with legacy migration shim.
+- `core/config.py` — Workspace + Settings dataclasses. `get_workspaces()` returns exactly what is configured and **never synthesizes a workspace**; zero workspaces is a valid state and `get_default_workspace()` returns `None` for it. The legacy `root_path` → `oss` migration shim lives only in `load_config()`, where it is persisted to disk. Both one-time migrations (`root_path` → `oss`, and adopting the pre-0.7.2 implicit `oss` workspace at `~/opensource`) run there too, gated by `config_version` — the provenance marker every save writes, which is what keeps an explicit `workspaces: []` from being re-migrated into a workspace the user just removed. `NO_WORKSPACES_HINT` is the one empty-state message every surface (CLI, MCP, web) reuses.
 - `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.
@@ -66,13 +67,14 @@ src/gitstow/
 - `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.
+- `core/tailscale.py` — `detect_tailscale()` / `tailscale_available()`. Shells out to the `tailscale` CLI (3s timeouts, None on any failure). Powers `gitstow ui --tailscale`: `web/server.py` binds the tailnet IP as a second socket and widens the Host/Origin guard by exact match to the machine's own tailnet identity only — never `0.0.0.0`. Every failure mode degrades to localhost-only with a warning.
 - `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.
 
 ## Data Files
 
-- `~/.gitstow/config.yaml` — Settings (workspaces list, default host, SSH pref).
+- `~/.gitstow/config.yaml` — Settings (workspaces list, default host, SSH pref, `ui_tailscale` dashboard-over-tailnet toggle).
 - `~/.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.
 
@@ -116,6 +118,8 @@ ruff check src/
 
 - **Worktree gotcha:** tests run from a git worktree silently exercise the main checkout (the editable install points at the primary clone). From a worktree, run `PYTHONPATH=<worktree>/src .venv/bin/python -m pytest -q`.
 - **Releasing publishes to PyPI.** `scripts/release.sh X.Y.Z` tags and pushes; the tag triggers a public PyPI publish. Require the user's explicit in-session instruction to release — plan approval or a "let's go" on implementation does not cover it.
+- **Lint with CI's ruff, not the venv's.** CI installs fresh (`ruff>=0.16` floor); the local venv keeps whatever was installed last. Before trusting "ruff clean" ahead of a push or release, compare `ruff --version` to the pyproject floor and `pip install -U ruff` if older (this blocked the v0.7.0 publish).
+- **Pressure-test before merging a feature branch.** Run `/code-review <PR#> high` and fix confirmed findings before merge — plan-scoped task reviews and even a clean whole-branch review do not count as the pressure test (on v0.7.0 it found 10 real issues after both were green).
 
 ## Patterns
 
@@ -128,13 +132,15 @@ ruff check src/
 - 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)
+- Legacy format auto-migration (flat repos.yaml → nested, root_path → workspaces) — migration happens in `load_config()` and is written to disk, never synthesized on read
+- `app.state.tailscale_serving` — `run()` records what it actually bound; the settings page compares saved config against that instead of guessing, so restart notices state facts (and direction), never implied live changes
 
 ## 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.
+- **Feature scope includes every surface that states the behavior.** A user-facing feature plan must carry, as explicit in-scope tasks: README, CHANGELOG, `docs/user/commands.md`, `src/gitstow/skill/SKILL.md`, and the landing page (`site/`) with core-feature billing. Enumerate the surfaces by grepping the repo for the old behavior's claim (e.g. `grep -rn "127.0.0.1" --include="*.md" --include="*.html"`) during planning — every hit becomes a plan task. Reviews inherit the plan's surface list, so a surface missed at planning stays stale through every review.
 - 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.

{gitstow-0.7.0 → gitstow-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gitstow
-Version: 0.7.0
+Version: 0.7.2
 Summary: A git repository library manager — clone, organize, and maintain collections of repos you learn from
 Project-URL: Homepage, https://gitstow.com
 Project-URL: Repository, https://github.com/rishmadaan/gitstow
@@ -71,8 +71,10 @@ pipx install gitstow   # recommended — full install: CLI + browser dashboard
 #   sudo apt install pipx      (Debian/Ubuntu)
 #   brew install pipx          (macOS)
 
-# First-run setup (optional — works without it)
+# First-run setup — creates your first workspace, sets your default host
 gitstow onboard
+# ...or skip the wizard and add a workspace directly:
+#   gitstow workspace add ~/oss --label oss
 
 # Add repos (GitHub shorthand or full URLs)
 gitstow add anthropic/claude-code
@@ -206,6 +208,7 @@ Private by default: binds `127.0.0.1` (arbitrary git execution must not be LAN-r
 gitstow config set ui_tailscale true   # every gitstow ui from now on
 gitstow ui --tailscale                 # or per-run
 ```
+You can also flip it on the dashboard's own **Settings** page — it takes effect the next time you start `gitstow ui`.
 If Tailscale isn't running, `gitstow ui` warns and serves localhost only.
 
 ### JSON Output
@@ -308,7 +311,9 @@ active:
 2. **Folder-as-state** — The directory structure is the primary source of truth. `repos.yaml` supplements with metadata (frozen, tags, timestamps).
 3. **Error isolation** — One bad repo never stops operations on others. Failures are collected and reported in a summary.
 4. **Parallel execution** — Bulk operations use `asyncio` with a semaphore (default 6 concurrent) to prevent SSH connection storms.
-5. **Zero-config start** — `gitstow add owner/repo` works immediately with sensible defaults.
+5. **Explicit state** — gitstow never invents a workspace. A fresh install has none, and
+   commands that need one say exactly how to create it. Zero workspaces is a valid state:
+   you can remove your last workspace and gitstow will simply say so.
 
 ### A note on folder structure
 
@@ -322,6 +327,8 @@ Flat workspaces skip the owner directory entirely — repos are just `workspace/
 
 **SSH clone fails with "Permission denied (publickey)"** — Your SSH key isn't configured for the git host. Either add your key (`ssh-add`) or use HTTPS: `gitstow config set prefer_ssh false`.
 
+**`No workspaces configured`** — Expected on a fresh install, and after removing your last workspace. gitstow never invents one. Run `gitstow workspace add <path> --label <name>` or `gitstow onboard`.
+
 **Workspace directory doesn't exist** — Run `gitstow doctor` to check workspace health. Create missing directories or update the path with `gitstow workspace add`.
 
 **`gitstow doctor`** — Run this first when something isn't working. It checks git installation, config files, and workspace integrity.

{gitstow-0.7.0 → gitstow-0.7.2}/README.md

@@ -26,8 +26,10 @@ pipx install gitstow   # recommended — full install: CLI + browser dashboard
 #   sudo apt install pipx      (Debian/Ubuntu)
 #   brew install pipx          (macOS)
 
-# First-run setup (optional — works without it)
+# First-run setup — creates your first workspace, sets your default host
 gitstow onboard
+# ...or skip the wizard and add a workspace directly:
+#   gitstow workspace add ~/oss --label oss
 
 # Add repos (GitHub shorthand or full URLs)
 gitstow add anthropic/claude-code
@@ -161,6 +163,7 @@ Private by default: binds `127.0.0.1` (arbitrary git execution must not be LAN-r
 gitstow config set ui_tailscale true   # every gitstow ui from now on
 gitstow ui --tailscale                 # or per-run
 ```
+You can also flip it on the dashboard's own **Settings** page — it takes effect the next time you start `gitstow ui`.
 If Tailscale isn't running, `gitstow ui` warns and serves localhost only.
 
 ### JSON Output
@@ -263,7 +266,9 @@ active:
 2. **Folder-as-state** — The directory structure is the primary source of truth. `repos.yaml` supplements with metadata (frozen, tags, timestamps).
 3. **Error isolation** — One bad repo never stops operations on others. Failures are collected and reported in a summary.
 4. **Parallel execution** — Bulk operations use `asyncio` with a semaphore (default 6 concurrent) to prevent SSH connection storms.
-5. **Zero-config start** — `gitstow add owner/repo` works immediately with sensible defaults.
+5. **Explicit state** — gitstow never invents a workspace. A fresh install has none, and
+   commands that need one say exactly how to create it. Zero workspaces is a valid state:
+   you can remove your last workspace and gitstow will simply say so.
 
 ### A note on folder structure
 
@@ -277,6 +282,8 @@ Flat workspaces skip the owner directory entirely — repos are just `workspace/
 
 **SSH clone fails with "Permission denied (publickey)"** — Your SSH key isn't configured for the git host. Either add your key (`ssh-add`) or use HTTPS: `gitstow config set prefer_ssh false`.
 
+**`No workspaces configured`** — Expected on a fresh install, and after removing your last workspace. gitstow never invents one. Run `gitstow workspace add <path> --label <name>` or `gitstow onboard`.
+
 **Workspace directory doesn't exist** — Run `gitstow doctor` to check workspace health. Create missing directories or update the path with `gitstow workspace add`.
 
 **`gitstow doctor`** — Run this first when something isn't working. It checks git installation, config files, and workspace integrity.

{gitstow-0.7.0 → gitstow-0.7.2}/docs/user/commands.md

@@ -80,7 +80,7 @@ gitstow add anthropic/claude-code --update
 ```
 
 **Behavior:**
-- Repos are added to the default workspace (first configured), or the workspace specified with `-w`
+- Repos are added to the first configured workspace, or the workspace specified with `-w`. With none configured, `add` exits 1 with `No workspaces configured…` and clones nothing
 - If the repo is already tracked: skips (or pulls with `--update`)
 - If the path exists on disk but isn't tracked: registers it automatically
 - If the path exists on disk with a **different** remote than the one requested: errors with a remote-mismatch message instead of silently registering — move the directory or pick another workspace
@@ -548,7 +548,7 @@ gitstow ui --tailscale         # also serve on this machine's Tailscale address
 - Workspace CRUD + Scan; Collection export/import under Settings
 - Click **Shutdown** in the footer (or Ctrl+C) to stop
 
-**Tailscale access:** with `--tailscale` (or `gitstow config set ui_tailscale true` to make it the default), the dashboard additionally binds this machine's own Tailscale address, so you can open it from any other device on your tailnet — useful for a VPS or headless box. `--no-tailscale` turns it off for a single run. If the Tailscale CLI isn't installed or the daemon isn't reachable, gitstow prints a warning and serves localhost-only instead of failing.
+**Tailscale access:** with `--tailscale` (or `gitstow config set ui_tailscale true` to make it the default), the dashboard additionally binds this machine's own Tailscale address, so you can open it from any other device on your tailnet — useful for a VPS or headless box. `--no-tailscale` turns it off for a single run. The same setting has a checkbox on the dashboard's Settings page — saving it there applies from the next `gitstow ui` onward, and the page says so. If the Tailscale CLI isn't installed or the daemon isn't reachable, gitstow prints a warning and serves localhost-only instead of failing.
 
 **Security:** binds `127.0.0.1` by default, and — only when Tailscale access is enabled — this machine's own Tailscale address as well. It never binds `0.0.0.0`, and there is no `--host` flag. The server runs git operations in arbitrary workspace directories, so it must not be LAN-reachable; with Tailscale access on, your trust boundary is your tailnet. Requests arriving with any other Host/Origin are rejected.
 
@@ -628,7 +628,7 @@ Valid keys: `default_host`, `prefer_ssh`, `parallel_limit`, `clone_timeout` (clo
 Move one workspace's repos to a new directory and update that workspace's `path` in config.
 
 ```bash
-gitstow config migrate-root ~/new-location            # Moves the default workspace
+gitstow config migrate-root ~/new-location            # Moves the first configured workspace
 gitstow -w active config migrate-root ~/new-location  # Moves a specific workspace
 gitstow config migrate-root ~/new-location --copy      # Keep originals
 gitstow config migrate-root ~/new-location --yes       # Skip confirmation
@@ -685,6 +685,18 @@ gitstow workspace list
 gitstow workspace list --quiet   # One label per line (for scripting/completions)
 ```
 
+With no workspaces configured — a fresh install, or after removing your last one —
+the command exits **0** (this is a valid state, not an error) and prints:
+
+```
+No workspaces configured. Add one with:
+  gitstow workspace add <path> --label <name>
+or run:
+  gitstow onboard
+```
+
+`--quiet` prints nothing in that case, so scripts see an empty list.
+
 ### `gitstow workspace add`
 
 Add a new workspace.
@@ -729,7 +741,28 @@ gitstow workspace remove <label> [flags]
 |------|-------------|
 | `--keep-repos/--untrack-repos` | Keep tracked repos in the store (default) or untrack them. |
 
-You cannot remove the only remaining workspace.
+**Removing your last workspace is allowed.** Zero workspaces is a valid state —
+gitstow does not invent one to fill the gap. The command reports the removal and
+then tells you how to get back:
+
+```
+  ✓ Workspace oss removed
+  No workspaces configured. Add one with:
+    gitstow workspace add <path> --label <name>
+  or run:
+    gitstow onboard
+```
+
+Until you add one, commands that sweep workspaces (`add`, `pull`, `fetch`, `list`, `status`, `exec`, `search`, `stats`, `migrate`,
+`collection import`, `config migrate-root` and `shell pick`)
+exit **1** with that same message on stderr. Run with `--json`, the same failure
+is emitted as `{"success": false, "error": "..."}` on stdout instead (still exit
+1), so a parsed run never sees an empty stdout — `collection import`,
+`config migrate-root` and `shell pick` have no `--json` option and always use the
+prose form. `workspace list`, `config show` and
+`doctor` still run, and each points at the same fix. Commands that name a single
+repo (`diff`, `open`, `remove`, `repo …`) report that the repo isn't tracked, which
+is what actually happened.
 
 ### `gitstow workspace scan`
 

{gitstow-0.7.0 → gitstow-0.7.2}/docs/user/concepts.md

@@ -53,11 +53,22 @@ gitstow pull --workspace oss
 gitstow repo info anthropic/claude-code -w work
 ```
 
-> **Migration from single root:** If you have a pre-workspace config with `root_path`, gitstow auto-migrates it to a single workspace labeled `oss` on first use. No action needed.
+> **Migration from single root:** If you have a pre-workspace config with `root_path`, gitstow auto-migrates it to a single workspace labeled `oss` on first use, and rewrites `config.yaml` to match. No action needed.
+>
+> This is the only case where gitstow creates a workspace for you, and it persists it. A config with no `root_path` and no workspaces stays empty.
 
 ## Folder Structure
 
-When you add a repo, gitstow places it in the default workspace (or the one you specify with `-w`).
+When you add a repo, gitstow places it in your first configured workspace (or the one you
+specify with `-w`). A fresh install has none — gitstow does not invent one, so create a
+workspace before adding repos. Every command that sweeps workspaces says so:
+
+```
+Error: No workspaces configured. Add one with:
+  gitstow workspace add <path> --label <name>
+or run:
+  gitstow onboard
+```
 
 ### Structured layout (default)
 

{gitstow-0.7.0 → gitstow-0.7.2}/docs/user/configuration.md

@@ -36,10 +36,13 @@ gitstow onboard
 
 | Key | Default | Description |
 |-----|---------|-------------|
-| `workspaces` | Single workspace at `~/oss` | List of workspace directories. Each has a path, label, layout, and optional auto-tags. |
+| `workspaces` | *(none)* | List of workspace directories. Each has a path, label, layout, and optional auto-tags. A fresh install has none — add one with `gitstow workspace add <path> --label <name>` or `gitstow onboard`. An empty list is valid; gitstow never invents a workspace. |
 | `default_host` | `github.com` | Assumed host when you type shorthand like `owner/repo`. |
 | `prefer_ssh` | `false` | If `true`, clones via SSH (`git@host:owner/repo.git`) instead of HTTPS. |
 | `parallel_limit` | `6` | Maximum concurrent git operations during `pull` and `status`. |
+| `clone_timeout` | `300` | Seconds before a clone is abandoned. Raise it for very large repos. |
+| `ui_tailscale` | `false` | If `true`, `gitstow ui` also serves the dashboard on this machine's Tailscale address. See [Web Dashboard over Tailscale](#web-dashboard-over-tailscale). |
+| `config_version` | *(written by gitstow)* | Internal — records which version of gitstow last wrote this file, so one-time upgrade migrations know they have already run. Do not edit. |
 
 ## File Locations
 
@@ -61,6 +64,9 @@ workspaces:
 default_host: github.com
 prefer_ssh: false
 parallel_limit: 6
+clone_timeout: 300
+ui_tailscale: false
+config_version: 2
 ```
 
 Each workspace entry has:
@@ -163,6 +169,32 @@ If you see SSH connection errors during bulk pulls, lower it:
 gitstow config set parallel_limit 3
 ```
 
+## Web Dashboard over Tailscale
+
+By default the dashboard (`gitstow ui`) binds `127.0.0.1` only. On a VPS or
+home server you can also serve it on the machine's own Tailscale address, so
+any device on your tailnet can open it:
+
+```bash
+gitstow config set ui_tailscale true   # every gitstow ui from now on
+gitstow ui --tailscale                 # or per-run (--no-tailscale to skip once)
+```
+
+The same setting can be flipped from the dashboard's own **Settings** page,
+and `gitstow onboard` offers it during setup when Tailscale is installed.
+
+Things worth knowing:
+
+- The setting applies when the server starts (that's when the socket binds).
+  Toggling it in the dashboard saves the config and tells you to restart
+  `gitstow ui` — it never pretends to change the running server.
+- It never binds `0.0.0.0`. The trust boundary is your tailnet: traffic is
+  WireGuard-encrypted, and anyone on your tailnet can reach the dashboard.
+- The startup message prints the tailnet URL as `http://<tailscale-ip>:7853`.
+  The MagicDNS name works too if you type it.
+- If Tailscale isn't installed or the daemon isn't running, `gitstow ui`
+  warns and serves localhost only — it never fails to start over this.
+
 ## MCP Server (Optional)
 
 > **Most users don't need this.** The Claude Code skill is the recommended AI integration — it has zero context overhead and auto-updates on version bumps. The MCP server is only for AI tools that don't support Claude Code skills (Claude Desktop, Cursor, Windsurf).

{gitstow-0.7.0 → gitstow-0.7.2}/docs/user/getting-started.md

@@ -41,7 +41,34 @@ gitstow --version
 
 > **Command not found?** On some systems, pip installs to a directory not on your PATH. Try `python3 -m gitstow --version` instead, or use pipx which handles PATH automatically.
 
-## 2. Add Your First Repo
+## 2. Create a Workspace
+
+A fresh install has **no workspaces**. A workspace is the directory gitstow clones
+into, and gitstow never invents one for you — so this is the first step.
+
+The interactive wizard walks you through it (and suggests `~/opensource` as a path):
+
+```bash
+gitstow onboard
+```
+
+Or do it in one line:
+
+```bash
+gitstow workspace add ~/oss --label oss --layout structured
+```
+
+Until a workspace exists, commands that need one (`add`, `pull`, `list`, `status`, …)
+stop with:
+
+```
+Error: No workspaces configured. Add one with:
+  gitstow workspace add <path> --label <name>
+or run:
+  gitstow onboard
+```
+
+## 3. Add Your First Repo
 
 ```bash
 gitstow add anthropic/claude-code
@@ -49,12 +76,13 @@ gitstow add anthropic/claude-code
 
 That's it. gitstow:
 1. Recognizes `anthropic/claude-code` as GitHub shorthand
-2. Clones to `~/oss/anthropic/claude-code/` (your default workspace)
+2. Clones to `~/oss/anthropic/claude-code/` (your first configured workspace)
 3. Registers it in your collection
 
-> **Default workspace:** Repos go to `~/oss/` by default (in a workspace labeled `oss`). Change it with `gitstow onboard` for the interactive setup wizard, or add additional workspaces with `gitstow workspace add`.
+> **Which workspace?** With more than one configured, `gitstow add` uses the first
+> one listed in `config.yaml`. Target another with `-w`, e.g. `gitstow -w active add owner/repo`.
 
-## 3. Add More Repos
+## 4. Add More Repos
 
 ```bash
 # GitHub shorthand (most common)
@@ -70,7 +98,7 @@ gitstow add git@bitbucket.org:owner/repo.git
 gitstow add torvalds/linux --shallow
 ```
 
-## 4. See Your Collection
+## 5. See Your Collection
 
 ```bash
 gitstow list
@@ -90,7 +118,7 @@ Output:
     linux                                     just now
 ```
 
-## 5. Update Everything
+## 6. Update Everything
 
 ```bash
 gitstow pull
@@ -110,7 +138,7 @@ Output:
 
 Every repo is pulled in parallel (up to 6 at once). If one repo fails, the others still update — you get a summary at the end.
 
-## 6. Check Status
+## 7. Check Status
 
 ```bash
 gitstow status
@@ -132,7 +160,7 @@ For a guided first-run experience:
 gitstow onboard
 ```
 
-This walks you through choosing a root directory, default git host, SSH vs HTTPS preference, and scans for existing repos to register.
+This walks you through creating your first workspace (suggesting `~/opensource` as its path), choosing a default git host and SSH vs HTTPS preference, then scans for existing repos to register.
 
 ## Multiple Workspaces
 
@@ -170,7 +198,7 @@ This is also done automatically during `gitstow onboard` and auto-updates when y
 gitstow ui
 ```
 
-Opens a local dark-themed dashboard at `http://127.0.0.1:7853` — a tab you leave open. Shows dirty state across every repo at a glance, pulls single repos or all-of-them in parallel, adds/removes repos, edits tags. Auto-refreshes every 30 seconds. Click **Shutdown** in the footer (or Ctrl+C) when done. See [commands.md — `gitstow ui`](commands.md#gitstow-ui) for full details.
+Opens a local dark-themed dashboard at `http://127.0.0.1:7853` — a tab you leave open. Shows dirty state across every repo at a glance, pulls single repos or all-of-them in parallel, adds/removes repos, edits tags. Auto-refreshes every 30 seconds. Click **Shutdown** in the footer (or Ctrl+C) when done. Running gitstow on a VPS? `gitstow ui --tailscale` (or the Tailscale toggle in the dashboard's Settings) also serves it on your tailnet so you can open it from your other devices — see [configuration.md](configuration.md#web-dashboard-over-tailscale). See [commands.md — `gitstow ui`](commands.md#gitstow-ui) for full details.
 
 ## Keep gitstow Up to Date
 
@@ -195,6 +223,10 @@ gitstow update            # upgrade to the latest PyPI version
 - For SSH: check your SSH key is added (`ssh -T git@github.com`)
 - Set SSH as default: `gitstow config set prefer_ssh true`
 
+**"No workspaces configured"**
+- Expected on a fresh install, and after removing your last workspace — zero workspaces is a valid state, not a broken one.
+- Fix it with `gitstow workspace add <path> --label <name>` or the `gitstow onboard` wizard. The same message appears in the web dashboard, with a link to the workspaces page.
+
 **"gitstow doctor" for diagnostics**
 ```bash
 gitstow doctor

{gitstow-0.7.0 → gitstow-0.7.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "gitstow"
-version = "0.7.0"
+version = "0.7.2"
 description = "A git repository library manager — clone, organize, and maintain collections of repos you learn from"
 readme = "README.md"
 license = "MIT"

{gitstow-0.7.0 → gitstow-0.7.2}/site/index.html

@@ -73,7 +73,7 @@
       </div>
       <p class="pipx-note" id="tab-note">Already have pipx? <code class="code-chip">pipx install gitstow</code> alone does it.</p>
       <div class="term-lines">
-        <div><span class="prompt">$</span> <span class="cmd">gitstow onboard</span> <span class="comment"># optional first-run wizard, installs the Claude skill too</span></div>
+        <div><span class="prompt">$</span> <span class="cmd">gitstow onboard</span> <span class="comment"># first-run wizard: creates your workspace, installs the Claude skill</span></div>
         <div><span class="prompt">$</span> <span class="cmd">gitstow add anthropic/claude-code</span> <span class="comment"># shorthand or full URLs</span></div>
         <div><span class="prompt">$</span> <span class="cmd">gitstow pull</span> <span class="comment"># update everything, in parallel</span></div>
         <div><span class="prompt">$</span> <span class="cmd">gitstow ui</span> <span class="comment"># open the dashboard ↓</span></div>
@@ -97,7 +97,7 @@
     <div class="center-head">
       <div class="eyebrow"><span class="bar"></span>gitstow ui<span class="bar"></span></div>
       <h2 class="section">The tab you leave open.</h2>
-      <p>A local-first browser dashboard, and the primary way to live with your library. Dirty state at a glance, one-click pulls, tags, freezes, and per-file diffs. It auto-refreshes every 30 seconds and never phones home: <code class="code-chip">127.0.0.1</code> by default — or flip on Tailscale access and open it from any device on your tailnet. Never the public internet.</p>
+      <p>A local-first browser dashboard, and the primary way to live with your library. Dirty state at a glance, one-click pulls, tags, freezes, and per-file diffs. It auto-refreshes every 30 seconds and never phones home: <code class="code-chip">127.0.0.1</code> by default — or flip on Tailscale access — right from its Settings page — and open it from any device on your tailnet. Never the public internet.</p>
     </div>
     <div class="bw-scroll">
       <div class="bw">

{gitstow-0.7.0 → gitstow-0.7.2}/src/gitstow/__init__.py

@@ -1,3 +1,3 @@
 """gitstow — a git repository library manager."""
 
-__version__ = "0.7.0"
+__version__ = "0.7.2"

{gitstow-0.7.0 → gitstow-0.7.2}/src/gitstow/cli/add.py

@@ -67,7 +67,8 @@ def add(
     """[bold green]Add[/bold green] repos — clone into organized structure.
 
     Accepts full URLs, SSH URLs, or shorthand (owner/repo assumes GitHub).
-    Uses the default workspace unless -w is specified.
+    Clones into the first configured workspace unless -w is specified;
+    errors with a hint if none is configured.
 
     \b
     Examples:
@@ -79,8 +80,8 @@ def add(
     settings = load_config()
     store = RepoStore()
     ws_label = ctx.obj.get("workspace") if ctx.obj else None
-    ws_list = resolve_workspaces(settings, ws_label)
-    ws = ws_list[0]  # Use the specified or default workspace
+    ws_list = resolve_workspaces(settings, ws_label, output_json=output_json)
+    ws = ws_list[0]  # The -w workspace, or the first configured one
     root = ws.get_path()
     tags = list(tag or []) + list(ws.auto_tags)
 

{gitstow-0.7.0 → gitstow-0.7.2}/src/gitstow/cli/config_cmd.py

@@ -8,6 +8,7 @@ import sys
 import typer
 from rich.console import Console
 
+from gitstow.cli.helpers import print_no_workspaces_hint, resolve_workspaces
 from gitstow.core.config import load_config, save_config
 from gitstow.core.paths import CONFIG_FILE, REPOS_FILE
 from gitstow.core.repo import RepoStore
@@ -57,6 +58,8 @@ def config_show(
     # Show workspaces
     workspaces = settings.get_workspaces()
     console.print(f"    [bold]Workspaces ({len(workspaces)}):[/bold]")
+    if not workspaces:
+        print_no_workspaces_hint(console, indent="      ")
     ws_counts = store.all_workspaces()
     for ws in workspaces:
         count = ws_counts.get(ws.label, 0)
@@ -92,6 +95,9 @@ def config_set(
     """
     settings = load_config()
 
+    # config_version is deliberately absent: it is provenance gitstow writes, not
+    # a setting. Editing it would either re-trigger or permanently disable the
+    # one-time legacy migrations.
     valid_keys = {"default_host", "prefer_ssh", "parallel_limit", "clone_timeout", "ui_tailscale"}
     if key not in valid_keys:
         err_console.print(
@@ -138,7 +144,7 @@ def config_migrate_root(
 
     \b
     Examples:
-      gitstow config migrate-root ~/new-location            # default workspace
+      gitstow config migrate-root ~/new-location            # first configured workspace
       gitstow -w active config migrate-root ~/new-location  # specific workspace
     """
     import shutil
@@ -149,16 +155,9 @@ def config_migrate_root(
     settings = load_config()
     store = RepoStore()
 
-    # Ensure the workspace list is materialized (legacy configs synthesize it).
-    if not settings.workspaces:
-        settings.workspaces = settings.get_workspaces()
-
-    ws_label = (ctx.obj or {}).get("workspace") or settings.get_default_workspace().label
-    ws = settings.get_workspace(ws_label)
-    if ws is None:
-        labels = ", ".join(w.label for w in settings.get_workspaces())
-        err_console.print(f"[red]Error:[/red] Unknown workspace [bold]{ws_label}[/bold]. Available: {labels}")
-        raise typer.Exit(code=1)
+    # No configured workspace → the shared hint + exit 1; unknown -w label → the
+    # shared "Unknown workspace" error; otherwise the named or first workspace.
+    ws = resolve_workspaces(settings, (ctx.obj or {}).get("workspace"))[0]
 
     old_root = ws.get_path()
     new_root_path = Path(new_root).expanduser().resolve()