gitstow 0.1.0__tar.gz

gitstow-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,67 @@
+name: Bug Report
+description: Report a bug in gitstow
+labels: ["bug"]
+body:
+  - type: input
+    id: version
+    attributes:
+      label: gitstow version
+      description: "Run `gitstow --version` to find this."
+      placeholder: "0.1.0"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating System
+      options:
+        - macOS
+        - Linux
+        - Windows
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      placeholder: "3.12"
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: A clear description of the bug.
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: Commands or steps to reproduce the behavior.
+      placeholder: |
+        1. Run `gitstow add ...`
+        2. Run `gitstow pull`
+        3. See error
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant output
+      description: Paste any error messages or terminal output.
+      render: shell

gitstow-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,42 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: Describe the use case or frustration that motivates this request.
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: How do you think this should work? Include example commands if applicable.
+      placeholder: |
+        gitstow add --recursive owner/repo
+        # This would also initialize git submodules during clone
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Any other approaches you've thought about or workarounds you're using.
+
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Which area does this affect?
+      options:
+        - Core commands (add, pull, list, status)
+        - Workspace management
+        - Repo management (freeze, tags)
+        - Shell integration
+        - TUI dashboard
+        - Export/import
+        - AI integration (skill, MCP)
+        - Other

gitstow-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+## Summary
+
+<!-- What does this PR do and why? -->
+
+## Test Plan
+
+<!-- How did you verify this works? -->
+
+- [ ] `pytest` passes
+- [ ] `ruff check src/` passes
+- [ ] Tested manually with `gitstow <command>`
+
+## Related Issues
+
+<!-- Link any related issues: Fixes #123, Relates to #456 -->

gitstow-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check src/
+
+      - name: Test
+        run: pytest --tb=short

gitstow-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,45 @@
+name: Release to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

gitstow-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Claude Code (local settings only — .claude/settings.json is meant to be shared)
+.claude/settings.local.json
+
+# macOS
+.DS_Store
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Ruff
+.ruff_cache/

gitstow-0.1.0/BACKLOG.md

@@ -0,0 +1,16 @@
+# Backlog
+
+Post-v0.1.0 improvements tracked here. See [GitHub Issues](https://github.com/rishmadaan/gitstow/issues) for discussion.
+
+## Enhancements
+
+- [x] **TUI: expand beyond read-only dashboard** (#1) — Added pull selected (P), workspace cycling (w), tag cycling (t)
+- [x] **Shell completion for repo names** (#2) — `gitstow shell completions` for bash/zsh/fish; `--quiet` on list/tags/workspace list
+- [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
+
+## Documentation
+
+- [ ] **Record demo GIF for README** (#7) — VHS tape script created (`demo.tape`); run `vhs demo.tape` to record

gitstow-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+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.1.0] - 2026-04-10
+
+Initial release.
+
+### Added
+
+- **Core commands:** `add`, `pull`, `list`, `status`, `remove`, `migrate`
+- **Workspace system:** Multiple workspaces with structured (`owner/repo`) and flat (`repo`) layouts
+- **Workspace commands:** `workspace list`, `workspace add`, `workspace remove`, `workspace scan`
+- **Repo management:** `repo freeze`, `repo unfreeze`, `repo tag`, `repo untag`, `repo tags`, `repo info`
+- **Bulk operations:** Parallel pull/status with configurable concurrency (default 6)
+- **Power commands:** `exec` (run commands across repos), `search` (grep across repos via ripgrep), `open` (editor/browser/finder), `stats`
+- **Collection sharing:** `collection export` (YAML/JSON/URLs) and `collection import`
+- **Shell integration:** `shell pick` (fzf picker), `shell init` (aliases), `shell setup`
+- **Interactive TUI:** `tui` command with Textual-based dashboard (filter, pull, freeze toggle)
+- **URL parsing:** GitHub, GitLab, Bitbucket, Codeberg, Azure DevOps, custom hosts; HTTPS, SSH, and shorthand formats
+- **AI integration:** Claude Code skill (auto-installed via `onboard` or `install-skill`) and optional MCP server
+- **Setup:** `onboard` wizard, `doctor` health check, `config show/set`
+- **Output modes:** `--json` and `--quiet` flags on all main commands
+- **Global workspace filter:** `-w/--workspace` flag on all commands
+- **Error isolation:** One failing repo never blocks operations on others

gitstow-0.1.0/CLAUDE.md

@@ -0,0 +1,129 @@
+# 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.
+
+## 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
+│   ├── 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
+└── skill/        # Claude Code 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/claude-code:
+    remote_url: https://github.com/anthropic/claude-code.git
+    tags: [ai]
+active:
+  gitstow:
+    remote_url: https://github.com/rishmadaan/gitstow.git
+    tags: [active]
+```
+
+## All Commands (26)
+
+**Core:** `add`, `pull`, `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 setup`, `tui`
+**Setup:** `onboard`, `config show/set/path/migrate-root`, `doctor`, `install-skill`
+
+## 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: Claude Code skill** (`src/gitstow/skill/SKILL.md`)
+- Installed to `~/.claude/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
+- Claude runs gitstow CLI commands via Bash — full access to all commands
+
+**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
+- **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.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Code of Conduct
+
+This project follows the [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+By participating, you agree to uphold a welcoming, inclusive, and respectful environment for everyone.
+
+## Reporting
+
+If you experience or witness unacceptable behavior, please report it by opening a GitHub issue or contacting the maintainer directly.
+
+## Enforcement
+
+Project maintainers will review and address reports promptly and fairly.

gitstow-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,82 @@
+# Contributing to gitstow
+
+Thanks for your interest in contributing! This guide will help you get started.
+
+## Development Setup
+
+```bash
+git clone https://github.com/rishmadaan/gitstow
+cd gitstow
+pip install -e ".[dev]"
+```
+
+For TUI development:
+```bash
+pip install -e ".[tui]"
+```
+
+## Running Tests
+
+```bash
+pytest                # Run all tests
+pytest -x             # Stop on first failure
+ruff check src/       # Lint
+```
+
+Both must pass before submitting a PR. CI runs these automatically.
+
+## Code Style
+
+- **Linter:** ruff (config in `pyproject.toml`)
+- **Line length:** 100 characters
+- **Python:** 3.10+ (use modern syntax — `list[str]` not `List[str]`)
+- **Formatting:** Follow existing patterns in the codebase
+
+## Architecture
+
+The codebase has a strict layered architecture:
+
+```
+cli/     → Thin command layer (Typer). Delegates to core/.
+core/    → Business logic. Git ops, config, repo store, URL parsing.
+tui/     → Textual interactive dashboard.
+skill/   → Claude Code skill (SKILL.md).
+mcp/     → MCP server for non-Claude-Code AI tools.
+```
+
+**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` owns all config loading/saving
+4. `cli/helpers.py` provides shared workspace resolution — don't duplicate it
+
+See `CLAUDE.md` for a detailed architecture guide.
+
+## Making Changes
+
+1. **Fork** the repo and create a branch from `main`
+2. **Make your changes** — keep commits focused
+3. **Add tests** if you're changing behavior
+4. **Run `pytest` and `ruff check src/`** — both must pass
+5. **Submit a PR** with a clear description of what and why
+
+## Versioning
+
+- Version lives in `pyproject.toml` (`version = "X.Y.Z"`)
+- Mirrored in `src/gitstow/__init__.py`
+- The Claude Code skill auto-updates when the version changes (checked on every CLI invocation)
+- Follow [Semantic Versioning](https://semver.org/): breaking.feature.fix
+
+## What to Work On
+
+- Check [open issues](https://github.com/rishmadaan/gitstow/issues) for things to pick up
+- Bug fixes and test coverage improvements are always welcome
+- For larger features, open an issue first to discuss the approach
+
+## Reporting Bugs
+
+Use the [bug report template](https://github.com/rishmadaan/gitstow/issues/new?template=bug_report.yml) and include:
+- gitstow version (`gitstow --version`)
+- OS and Python version
+- Steps to reproduce
+- Expected vs actual behavior

gitstow-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rish Madaan
+
+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.