gitstow 0.1.0__py3-none-any.whl

gitstow-0.1.0.dist-info/METADATA

@@ -0,0 +1,306 @@
+Metadata-Version: 2.4
+Name: gitstow
+Version: 0.1.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
+Project-URL: Documentation, https://github.com/rishmadaan/gitstow#readme
+Project-URL: Issues, https://github.com/rishmadaan/gitstow/issues
+Project-URL: Changelog, https://github.com/rishmadaan/gitstow/blob/main/CHANGELOG.md
+Author: Rish Madaan
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,developer-tools,git,manager,open-source,repository
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Requires-Dist: beaupy>=3.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer[all]>=0.9
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Provides-Extra: tui
+Requires-Dist: textual>=0.50; extra == 'tui'
+Description-Content-Type: text/markdown
+
+# gitstow
+
+A git repository library manager — clone, organize, and maintain collections of repos you learn from.
+
+## Why?
+
+AI-assisted development has created a new relationship with open source. Developers increasingly maintain local clones of repositories they study and reference, not just repos they contribute to. `gitstow` manages this collection as a first-class concern.
+
+Existing tools solve parts of this:
+- **[ghq](https://github.com/x-motemen/ghq)** (3.5k stars) auto-organizes repos by `host/owner/repo` — but can't pull, status-check, or run commands across them.
+- **[gita](https://github.com/nosarthur/gita)** (1.8k stars) runs bulk git operations — but doesn't organize or auto-structure anything.
+
+`gitstow` combines the best of both: **paste a URL → auto-organized → bulk pull, freeze, tag, and manage your entire collection.** Works across multiple workspaces — open-source collections, active projects, and more.
+
+## Quick Start
+
+```bash
+pipx install gitstow   # recommended
+# or: pip install gitstow
+
+# First-run setup (optional — works without it)
+gitstow onboard
+
+# Add repos (GitHub shorthand or full URLs)
+gitstow add anthropic/claude-code
+gitstow add https://gitlab.com/group/project
+
+# Update everything
+gitstow pull
+
+# See your collection
+gitstow list
+
+# Check git status across all repos
+gitstow status
+```
+
+## Features
+
+### Workspaces
+```bash
+# Track open-source repos (structured: owner/repo layout)
+gitstow workspace add ~/oss --label oss --layout structured
+
+# Track your active projects (flat: repos directly in folder)
+gitstow workspace add ~/labs/projects --label active --layout flat --auto-tag active
+
+# Scan to discover existing repos
+gitstow workspace scan active
+```
+
+### Auto-Organization
+```bash
+gitstow add anthropic/claude-code facebook/react torvalds/linux
+```
+Creates (in a structured workspace):
+```
+~/oss/
+├── anthropic/
+│   └── claude-code/
+├── facebook/
+│   └── react/
+└── torvalds/
+    └── linux/
+```
+
+### Bulk Operations
+```bash
+gitstow pull                    # Update all repos across all workspaces
+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
+```
+
+### Freeze & Tags
+```bash
+gitstow repo freeze facebook/react   # Skip during pull
+gitstow repo tag anthropic/claude-code ai tools
+gitstow pull --tag ai                # Update only AI repos
+gitstow repo tags                    # List all tags
+```
+
+### Migrate Existing Repos
+```bash
+gitstow migrate ~/old-projects/some-repo   # Auto-detects owner/repo from remote
+```
+
+### Any Git Host
+```bash
+gitstow add anthropic/claude-code              # GitHub (default)
+gitstow add https://gitlab.com/group/project   # GitLab (nested groups work)
+gitstow add git@bitbucket.org:owner/repo.git   # Bitbucket
+gitstow add https://codeberg.org/owner/repo    # Codeberg
+```
+
+### AI Integration
+
+gitstow is designed to be used primarily through AI tools. The Claude Code skill is installed automatically during onboarding and auto-updates on version bumps:
+
+```bash
+gitstow install-skill   # Or: gitstow onboard (includes this)
+# Then in Claude Code: "add this repo" or "update my repos"
+```
+
+> **MCP server** is also available for non-Claude-Code AI tools (Claude Desktop, Cursor, etc.) via `pip install gitstow[mcp]`. See [docs/user/configuration.md](docs/user/configuration.md#mcp-server-optional) for setup. Note: MCP tools are always loaded into context and cost tokens even when not in use — the skill has zero overhead when inactive.
+
+### Run Commands Across Repos
+```bash
+gitstow exec -- git log -1 --oneline      # Last commit in each repo
+gitstow exec --tag python -- wc -l README.md  # Line count in Python repos
+```
+
+### Search Across Repos
+```bash
+gitstow search "TODO"                     # Grep everything
+gitstow search "def main" --glob "*.py"   # Only Python files
+gitstow search "error" --tag ai -i        # Case-insensitive, AI repos only
+```
+
+### Share Your Collection
+```bash
+gitstow collection export -o my-repos.yaml   # Export as portable YAML
+gitstow collection import my-repos.yaml      # Import on another machine
+gitstow collection export --format urls      # Plain URL list
+```
+
+### Shell Integration
+```bash
+eval "$(gitstow shell init)"    # Add to ~/.zshrc or ~/.bashrc
+gs                               # cd into a repo (fzf picker)
+gse                              # Open repo in editor (fzf picker)
+gsp                              # gitstow pull shorthand
+```
+
+### Interactive Dashboard
+```bash
+gitstow tui    # Keyboard-driven dashboard with filter, pull, freeze
+```
+
+### JSON Output
+Every command supports `--json` for scripting and AI consumption:
+```bash
+gitstow list --json
+gitstow pull --json --quiet
+gitstow status --json
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| **Core** | |
+| `gitstow add <url> [urls...]` | Clone repos into organized structure |
+| `gitstow pull` | Bulk update all (or filtered) repos |
+| `gitstow list` | List repos grouped by owner/workspace |
+| `gitstow status` | Git status dashboard |
+| `gitstow remove <repo>` | Remove a repo from tracking |
+| `gitstow migrate <path>` | Adopt existing repos into structure |
+| **Workspaces** | |
+| `gitstow workspace list` | List all configured workspaces |
+| `gitstow workspace add <path>` | Add a new workspace |
+| `gitstow workspace remove <label>` | Remove a workspace |
+| `gitstow workspace scan <label>` | Discover and register repos on disk |
+| **Repo Management** | |
+| `gitstow repo freeze <repo>` | Skip repo during pull |
+| `gitstow repo unfreeze <repo>` | Re-enable pulling |
+| `gitstow repo tag <repo> <tags...>` | Add tags to a repo |
+| `gitstow repo untag <repo> <tag>` | Remove a tag |
+| `gitstow repo tags` | List all tags with counts |
+| `gitstow repo info <repo>` | Detailed repo info |
+| **Power** | |
+| `gitstow exec <command>` | Run a command in every repo |
+| `gitstow search <pattern>` | Grep across all repos (uses ripgrep) |
+| `gitstow open <repo>` | Open in editor, browser, or Finder |
+| `gitstow stats` | Collection statistics and disk usage |
+| **Sharing** | |
+| `gitstow collection export` | Export collection as YAML, JSON, or URLs |
+| `gitstow collection import <file>` | Import a collection from file |
+| **Shell** | |
+| `gitstow shell setup` | Show shell integration instructions |
+| `gitstow shell pick` | fzf-powered repo picker |
+| `gitstow tui` | Interactive terminal dashboard |
+| **Config** | |
+| `gitstow config show` | Show current config and workspaces |
+| `gitstow config set <key> <value>` | Change a setting |
+| `gitstow onboard` | First-run setup wizard |
+| `gitstow doctor` | Health check |
+| `gitstow install-skill` | Install Claude Code skill |
+
+All commands accept `-w <label>` to filter to a specific workspace.
+
+## Configuration
+
+Config lives at `~/.gitstow/config.yaml`:
+
+```yaml
+workspaces:
+  - path: ~/oss
+    label: oss
+    layout: structured
+  - path: ~/labs/projects
+    label: active
+    layout: flat
+    auto_tags: [active]
+default_host: github.com
+prefer_ssh: false
+parallel_limit: 6
+```
+
+Repo metadata at `~/.gitstow/repos.yaml` (nested by workspace):
+
+```yaml
+oss:
+  anthropic/claude-code:
+    remote_url: https://github.com/anthropic/claude-code.git
+    frozen: false
+    tags: [ai, tools]
+    added: '2026-04-05'
+active:
+  gitstow:
+    remote_url: https://github.com/rishmadaan/gitstow.git
+    tags: [active]
+    added: '2026-04-05'
+```
+
+## How It Works
+
+1. **Workspaces** — Each workspace is a directory with a layout mode (`structured` = owner/repo, `flat` = just repo). Repos are organized across workspaces, tagged, and managed as a unified collection.
+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.
+
+### A note on folder structure
+
+Structured workspaces organize repos as `owner/repo/` (e.g., `~/oss/anthropic/claude-code/`). Unlike [ghq](https://github.com/x-motemen/ghq) which includes the host (`root/github.com/owner/repo/`), we omit it for simplicity.
+
+Flat workspaces skip the owner directory entirely — repos are just `workspace/repo-name/`. Use flat layout for directories where you already have projects organized your own way.
+
+## Troubleshooting
+
+**`gitstow: command not found`** — Make sure the install location is on your PATH. With pipx this is automatic. With pip, you may need `python3 -m gitstow` or add `~/.local/bin` to your PATH.
+
+**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`.
+
+**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.
+
+## Development
+
+```bash
+git clone https://github.com/rishmadaan/gitstow
+cd gitstow
+pip install -e ".[dev]"
+pytest
+ruff check src/
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
+
+## License
+
+MIT

gitstow-0.1.0.dist-info/RECORD

@@ -0,0 +1,43 @@
+gitstow/__init__.py,sha256=xph079dNr3G335VAHKs3jVqUCY63knfLhEtA9WLb_Rs,75
+gitstow/__main__.py,sha256=z0J_37INhn0j_x2hIhgDU1IgDLF7Izv_I_hXY1t6g48,216
+gitstow/cli/__init__.py,sha256=aOn6p9V8EFcRyjWxrA6w-horRYLRnm0fposov9wfQlo,43
+gitstow/cli/add.py,sha256=ffGHmaQVdRFdmWePoB0PqwLx3aG-T65vYP0zcyFE99c,10094
+gitstow/cli/config_cmd.py,sha256=6w2fTXdxxtXE4kt3sZs5cDapOxbywnOsu2SKhH9H40s,7642
+gitstow/cli/doctor.py,sha256=z9pvr8iz4-yNj7xmOsFVd-PINXW-3weFi6UuC8V0KTQ,6122
+gitstow/cli/exec_cmd.py,sha256=P5-s6XgeaaO2u9PVFf3SPeohcnk-3AdvVDQqDLT4U6M,5310
+gitstow/cli/export_cmd.py,sha256=JOATKgdt3w6bE-r4fKqmeWJMPkrSFfP_85HrRUnSEWs,9968
+gitstow/cli/helpers.py,sha256=nhMRSUEKlHrU3Rta1VCL01iDcSjUAChZqBV5h0PJC0s,3545
+gitstow/cli/list_cmd.py,sha256=o8OJs4cniBLMP0BN5zxHLNQjLbzQ7EgcPJ2iJUEU6yg,7094
+gitstow/cli/main.py,sha256=I08WgcglVlajwjRGbTRgv_YTMlutqlMt6PpFHqKBsNg,4276
+gitstow/cli/manage.py,sha256=J4jlZcoGihiaFybkA4yPMfoyKck1uS20Lp3H5jWXQcU,8796
+gitstow/cli/migrate.py,sha256=mzKOKvEh3gXwuP3eDzyRHorqw532TcKt72Zw40q4xys,5281
+gitstow/cli/onboard.py,sha256=L6HKFwBpP7TYPna-B9VXw8YZnVlZEXiqy6UHBMjr8JA,8545
+gitstow/cli/open_cmd.py,sha256=dxQZH2SObEOydC0sWmjLWKjMpmu1JTlVlCi390ht3U0,4571
+gitstow/cli/pull.py,sha256=vWWjuVMTa_vO-hmAGoMlOG_W86JxbN2dUGfPDDGbqo4,9537
+gitstow/cli/remove.py,sha256=1XqQl0jSQYKNijcl25xdCpcF3M8wk2PNP5B0rtGUeKw,2698
+gitstow/cli/search.py,sha256=fJk-V0lF7dc8WSKQCuXQRV-sm8nJF250arCQwdATbI4,6245
+gitstow/cli/setup_ai.py,sha256=-DXByoe5aRd4RqWZX63m7Cdp313YL9Mv59b4ARPdJmY,8981
+gitstow/cli/shell.py,sha256=oVOysvKNjaJ1jiiK2RaJlYcTST99rQVVBstzrX4qgLU,9372
+gitstow/cli/skill_cmd.py,sha256=KyHXAIxZRud9qdHlQbEijnviKtlTxtrecBoo7OY2M50,2006
+gitstow/cli/stats.py,sha256=BpmdoeeycM7m9Gi0u2GvaLpOT5tI73tNtpSwoYrtN6A,4166
+gitstow/cli/status.py,sha256=FtJ5AqjQ7qwp_VDpfTF5yl8mcfQzX6pVHjKX1Eo54zA,7010
+gitstow/cli/tui.py,sha256=b9I439hJ4nw5VvU22VuYf1MT7CZy8B-m_SMOGcujEWg,684
+gitstow/cli/workspace_cmd.py,sha256=JFAXLWSJhs-DF6nNNwPXFQso7ER1i3DKzY9yNTPjttA,6422
+gitstow/core/__init__.py,sha256=Yc5Xfujdd-110F9ErAZnfy9MJYVI3P-sUc-_wwrYc_k,77
+gitstow/core/config.py,sha256=pMDJlDjXUj1aEoUGnXmyN9smNjY6Wsw6xQlHIyEqBHU,4446
+gitstow/core/discovery.py,sha256=CPrniHKBeXvUHHIM_fL3ZP7pRBGUqDf1JOq9aE8P5i0,3443
+gitstow/core/git.py,sha256=BTPN4_NjC0g2zZvPOC7jc7on9rYg17dEXpcHA34NIS0,8101
+gitstow/core/parallel.py,sha256=dfR9LGVJpG5vshxaPXgsvR7QR6ZPpe5xDCkAfU70VcA,2603
+gitstow/core/paths.py,sha256=9BQU8HFjXKxutn9AyvqUMqSCbB54ArQjjvPI0Y5pPhQ,1776
+gitstow/core/repo.py,sha256=WDytmjvxAVFf8PbGZlBfQwNYz1Ls87fdcofaM49euLg,10680
+gitstow/core/url_parser.py,sha256=loo5CnEhwWIMvqmB-svdBr-_0EfNQMCOe6tveDKpFHo,4878
+gitstow/mcp/__init__.py,sha256=kguWR6pSrls1YUbb-QjXU-p-xXE92xAbXcpp8XLU2oU,75
+gitstow/mcp/server.py,sha256=LGoEjYH0Du9QFFC7gESEGbuhhIok9s1NKBwHVGwvx5M,21449
+gitstow/skill/SKILL.md,sha256=c8YjtP7fqVl9DD9L7O9rhOY94SZFqMqr7zgMnJBJ_f8,7210
+gitstow/tui/__init__.py,sha256=tm_LtIWe5H0uwfFF4nol9SQTET_KzgmWJC7Wr-y5Zvs,73
+gitstow/tui/app.py,sha256=STf4_RJVW04vXqjz1EQU9HXmlKdKIXN46exb6ucH4fk,13713
+gitstow-0.1.0.dist-info/METADATA,sha256=lWE8sufKcjGl_p5BuEco4CkFSdAbz77ECThV2rE9mnw,11412
+gitstow-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+gitstow-0.1.0.dist-info/entry_points.txt,sha256=yEbVxHuXqjwHWzwp76wDoA6zYUxzJLyfLIVq3OEmsQ0,87
+gitstow-0.1.0.dist-info/licenses/LICENSE,sha256=0HBGPEMLmwH9rsg_eJ8WhfSxRdHeN3t2JxnYOVZzlM0,1068
+gitstow-0.1.0.dist-info/RECORD,,

gitstow-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

gitstow-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+gitstow = gitstow.cli.main:app
+gitstow-mcp = gitstow.mcp.server:main

gitstow-0.1.0.dist-info/licenses/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.