Name | devctx JSON |
Version |
0.1.0
JSON |
| download |
home_page | None |
Summary | A CLI tool for creating temporary monorepos from GitHub repositories |
upload_time | 2025-07-09 11:47:17 |
maintainer | None |
docs_url | None |
author | None |
requires_python | >=3.8 |
license | MIT |
keywords |
cli
git
github
monorepo
workspace
|
VCS |
 |
bugtrack_url |
|
requirements |
No requirements were recorded.
|
Travis-CI |
No Travis.
|
coveralls test coverage |
No coveralls.
|
# DevCtx - Development Context Creator
A powerful CLI tool for creating temporary monorepos from GitHub repositories with intelligent fuzzy matching and branch management.
## Features
- 🚀 **Fast Setup**: Create workspaces with multiple repositories in seconds
- 🔍 **Intelligent Fuzzy Matching**: Handles typos with helpful suggestions
- 🌿 **Branch Management**: Checkout existing branches or create new ones
- 📝 **Smart Caching**: Remembers repository lists to speed up subsequent runs
- 🎨 **Beautiful Output**: Rich, colorful interface with progress indicators
- ⚙️ **Configurable**: Set default organizations and cache preferences
## Installation
### Option 1: Using pipx (Recommended)
```bash
# Install pipx if you haven't already
pip install pipx
# Install devctx
pipx install devctx
# Verify installation
devctx --help
```
### Option 2: Using uv
```bash
# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install devctx as a tool
uv tool install devctx
# Verify installation
devctx --help
```
### Option 3: Development Installation
```bash
# Clone the repository
git clone https://github.com/PragmaticMachineLearning/devctx.git
cd devctx
# Install in development mode with pipx
pipx install -e .
# Or with uv
uv tool install -e .
```
## Quick Start
1. **Set up your GitHub token:**
```bash
export GITHUB_TOKEN=your_github_token_here
```
2. **Create your first workspace:**
```bash
devctx create repo1 repo2 --org YourOrg --folder my-workspace
```
3. **Set a default organization (optional):**
```bash
devctx config --set-org YourOrg
```
## Usage
### Basic Commands
```bash
# Create a workspace with multiple repositories
devctx create indicore workflows --org IndicoDataSolutions --folder my-workspace
# Use short flags for convenience
devctx create indicore workflows -o IndicoDataSolutions -f my-workspace
# Create workspace with specific branch
devctx create indicore workflows -o IndicoDataSolutions -f feature-branch -b develop
# Create workspace and new branch in all repos
devctx create indicore workflows -f new-feature --create-branch feature/awesome-thing
# List repositories in an organization
devctx list-repos IndicoDataSolutions
# View and modify configuration
devctx config
devctx config --set-org IndicoDataSolutions
```
### Common Use Cases
#### 1. Quick Development Setup
```bash
# Set default org once
devctx config --set-org YourOrganization
# Then create workspaces quickly
devctx create frontend backend database -f full-stack-dev
```
#### 2. Feature Development
```bash
# Create workspace on specific branch
devctx create app api -f feature-work -b develop
# Or create new feature branch across all repos
devctx create app api -f new-feature --create-branch feature/user-auth
```
#### 3. Bug Investigation
```bash
# Create workspace for investigating issues
devctx create service1 service2 logs -f bug-investigation -b hotfix
```
#### 4. Code Review
```bash
# Create workspace to review a specific PR branch
devctx create backend frontend -f pr-review -b pr/123-new-feature
```
## Configuration
DevCtx stores configuration in `~/.config/devctx/config.json`. You can manage it using the config command:
```bash
devctx config # View current configuration
devctx config --set-org MyOrg # Set default organization
```
### Configuration Options
| Setting | Default | Description |
|---------|---------|-------------|
| `default_org` | `null` | Default GitHub organization to use |
| `repo_cache_duration_days` | `30` | How long to cache repository lists (in days) |
| `repo_cache` | `{}` | Internal cache storage (managed automatically) |
### Configuration File Format
```json
{
"default_org": "IndicoDataSolutions",
"repo_cache_duration_days": 30,
"repo_cache": {
"IndicoDataSolutions": {
"repos": ["indicore", "workflows", "cyclone"],
"last_updated": "2024-01-15T10:30:00Z"
}
}
}
```
## Command Reference
### `devctx create`
Create a new workspace with specified repositories.
```bash
devctx create REPO1 REPO2 ... [OPTIONS]
```
**Options:**
- `--org, -o`: GitHub organization name
- `--folder, -f`: Workspace folder name (auto-generated if not provided)
- `--branch, -b`: Branch to checkout in all repositories
- `--create-branch, -c`: Create new branch in all repositories
- `--refresh-cache`: Force refresh of repository cache
**Examples:**
```bash
devctx create app api docs -o myorg -f workspace
devctx create frontend -f ui-work -b develop
devctx create backend -f hotfix --create-branch hotfix/critical-bug
```
### `devctx list-repos`
List all repositories in a GitHub organization.
```bash
devctx list-repos ORGANIZATION [OPTIONS]
```
**Options:**
- `--refresh-cache`: Force refresh of repository cache
**Example:**
```bash
devctx list-repos IndicoDataSolutions --refresh-cache
```
### `devctx config`
View or modify configuration settings.
```bash
devctx config [OPTIONS]
```
**Options:**
- `--set-org ORG`: Set default organization
**Examples:**
```bash
devctx config # View current config
devctx config --set-org MyOrganization # Set default org
```
## Fuzzy Matching
DevCtx includes intelligent fuzzy matching that helps when you make typos:
```bash
# Typo: "workflws" instead of "workflows"
devctx create indicore workflws -f test
# DevCtx will show:
# Multiple matches found for "workflws":
# 1. workflows (score: 89%)
# 2. workflex (score: 45%)
# Select repository [1-2]: 1
```
The fuzzy matching:
- Automatically selects exact matches
- Prompts for confirmation on close matches (>70% similarity)
- Shows multiple options for ambiguous cases
- Handles multiple typos in one command
## Branch Management
DevCtx provides flexible branch management:
### Checkout Existing Branch
```bash
devctx create repo1 repo2 -f workspace -b feature-branch
```
If the branch doesn't exist in a repository, DevCtx will:
1. Show a warning
2. Fall back to the repository's default branch
3. Continue with other repositories
### Create New Branch
```bash
devctx create repo1 repo2 -f workspace --create-branch feature/new-feature
```
DevCtx will:
1. Create the branch from each repository's default branch
2. Handle creation failures gracefully
3. Report success/failure for each repository
## Troubleshooting
### Common Issues
#### 1. "GITHUB_TOKEN not found"
**Problem:** GitHub token not set in environment.
**Solution:**
```bash
export GITHUB_TOKEN=your_token_here
# Add to your shell profile (.bashrc, .zshrc, etc.)
echo 'export GITHUB_TOKEN=your_token_here' >> ~/.bashrc
```
#### 2. "Permission denied" errors
**Problem:** GitHub token doesn't have necessary permissions.
**Solutions:**
- Ensure token has `repo` scope for private repositories
- Use `public_repo` scope for public repositories only
- Check if you have access to the organization
#### 3. "Repository not found"
**Problem:** Repository doesn't exist or you don't have access.
**Solutions:**
- Verify repository name spelling
- Check organization name
- Ensure your GitHub token has access to the repository
- Use `devctx list-repos ORGANIZATION` to see available repositories
#### 4. "Branch not found"
**Problem:** Specified branch doesn't exist.
**Solutions:**
- DevCtx will automatically fall back to the default branch
- Check branch name spelling
- Verify the branch exists in the repository
#### 5. "Folder already exists"
**Problem:** Workspace folder already exists.
**Solutions:**
- Use a different folder name with `-f other-name`
- Remove existing folder: `rm -rf existing-folder`
- DevCtx will prompt for confirmation before overwriting
#### 6. Git clone failures
**Problem:** Network issues or authentication problems.
**Solutions:**
- Check internet connection
- Verify GitHub token is valid
- Try refreshing cache with `--refresh-cache`
- Check if repositories are private and you have access
### Debug Tips
1. **Use `--refresh-cache`** to force fresh repository data
2. **Check config** with `devctx config` to verify settings
3. **Test with public repos** first to verify setup
4. **Use `devctx list-repos ORG`** to verify repository access
### Getting Help
- Run `devctx --help` for general help
- Run `devctx COMMAND --help` for command-specific help
- Check the [GitHub Issues](https://github.com/PragmaticMachineLearning/devctx/issues) for known problems
- File a bug report if you encounter new issues
## Development
### Setup
```bash
git clone https://github.com/PragmaticMachineLearning/devctx.git
cd devctx
# Install in development mode
pipx install -e .
# Or with uv
uv tool install -e .
```
### Running Tests
```bash
# Install test dependencies
pip install -e ".[dev]"
# Run tests
pytest
```
### Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run tests to ensure everything works
6. Submit a pull request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
If you encounter issues or have questions:
1. Check the [troubleshooting section](#troubleshooting)
2. Search [existing issues](https://github.com/PragmaticMachineLearning/devctx/issues)
3. Create a new issue if needed
## Changelog
### 0.1.0
- Initial release
- Basic workspace creation
- Fuzzy matching for repository names
- Branch management
- Configuration system
- Repository caching
Raw data
{
"_id": null,
"home_page": null,
"name": "devctx",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "cli, git, github, monorepo, workspace",
"author": null,
"author_email": "Madison May <madison@indico.io>",
"download_url": "https://files.pythonhosted.org/packages/5d/c1/4de11fde903cf7ffdbbb24ec31884c9c182c7e5513d57e392ac4f71a64ff/devctx-0.1.0.tar.gz",
"platform": null,
"description": "# DevCtx - Development Context Creator\n\nA powerful CLI tool for creating temporary monorepos from GitHub repositories with intelligent fuzzy matching and branch management.\n\n## Features\n\n- \ud83d\ude80 **Fast Setup**: Create workspaces with multiple repositories in seconds\n- \ud83d\udd0d **Intelligent Fuzzy Matching**: Handles typos with helpful suggestions\n- \ud83c\udf3f **Branch Management**: Checkout existing branches or create new ones\n- \ud83d\udcdd **Smart Caching**: Remembers repository lists to speed up subsequent runs\n- \ud83c\udfa8 **Beautiful Output**: Rich, colorful interface with progress indicators\n- \u2699\ufe0f **Configurable**: Set default organizations and cache preferences\n\n## Installation\n\n### Option 1: Using pipx (Recommended)\n\n```bash\n# Install pipx if you haven't already\npip install pipx\n\n# Install devctx\npipx install devctx\n\n# Verify installation\ndevctx --help\n```\n\n### Option 2: Using uv\n\n```bash\n# Install uv if you haven't already\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Install devctx as a tool\nuv tool install devctx\n\n# Verify installation\ndevctx --help\n```\n\n### Option 3: Development Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/PragmaticMachineLearning/devctx.git\ncd devctx\n\n# Install in development mode with pipx\npipx install -e .\n\n# Or with uv\nuv tool install -e .\n```\n\n## Quick Start\n\n1. **Set up your GitHub token:**\n ```bash\n export GITHUB_TOKEN=your_github_token_here\n ```\n\n2. **Create your first workspace:**\n ```bash\n devctx create repo1 repo2 --org YourOrg --folder my-workspace\n ```\n\n3. **Set a default organization (optional):**\n ```bash\n devctx config --set-org YourOrg\n ```\n\n## Usage\n\n### Basic Commands\n\n```bash\n# Create a workspace with multiple repositories\ndevctx create indicore workflows --org IndicoDataSolutions --folder my-workspace\n\n# Use short flags for convenience\ndevctx create indicore workflows -o IndicoDataSolutions -f my-workspace\n\n# Create workspace with specific branch\ndevctx create indicore workflows -o IndicoDataSolutions -f feature-branch -b develop\n\n# Create workspace and new branch in all repos\ndevctx create indicore workflows -f new-feature --create-branch feature/awesome-thing\n\n# List repositories in an organization\ndevctx list-repos IndicoDataSolutions\n\n# View and modify configuration\ndevctx config\ndevctx config --set-org IndicoDataSolutions\n```\n\n### Common Use Cases\n\n#### 1. Quick Development Setup\n```bash\n# Set default org once\ndevctx config --set-org YourOrganization\n\n# Then create workspaces quickly\ndevctx create frontend backend database -f full-stack-dev\n```\n\n#### 2. Feature Development\n```bash\n# Create workspace on specific branch\ndevctx create app api -f feature-work -b develop\n\n# Or create new feature branch across all repos\ndevctx create app api -f new-feature --create-branch feature/user-auth\n```\n\n#### 3. Bug Investigation\n```bash\n# Create workspace for investigating issues\ndevctx create service1 service2 logs -f bug-investigation -b hotfix\n```\n\n#### 4. Code Review\n```bash\n# Create workspace to review a specific PR branch\ndevctx create backend frontend -f pr-review -b pr/123-new-feature\n```\n\n## Configuration\n\nDevCtx stores configuration in `~/.config/devctx/config.json`. You can manage it using the config command:\n\n```bash\ndevctx config # View current configuration\ndevctx config --set-org MyOrg # Set default organization\n```\n\n### Configuration Options\n\n| Setting | Default | Description |\n|---------|---------|-------------|\n| `default_org` | `null` | Default GitHub organization to use |\n| `repo_cache_duration_days` | `30` | How long to cache repository lists (in days) |\n| `repo_cache` | `{}` | Internal cache storage (managed automatically) |\n\n### Configuration File Format\n\n```json\n{\n \"default_org\": \"IndicoDataSolutions\",\n \"repo_cache_duration_days\": 30,\n \"repo_cache\": {\n \"IndicoDataSolutions\": {\n \"repos\": [\"indicore\", \"workflows\", \"cyclone\"],\n \"last_updated\": \"2024-01-15T10:30:00Z\"\n }\n }\n}\n```\n\n## Command Reference\n\n### `devctx create`\n\nCreate a new workspace with specified repositories.\n\n```bash\ndevctx create REPO1 REPO2 ... [OPTIONS]\n```\n\n**Options:**\n- `--org, -o`: GitHub organization name\n- `--folder, -f`: Workspace folder name (auto-generated if not provided)\n- `--branch, -b`: Branch to checkout in all repositories\n- `--create-branch, -c`: Create new branch in all repositories\n- `--refresh-cache`: Force refresh of repository cache\n\n**Examples:**\n```bash\ndevctx create app api docs -o myorg -f workspace\ndevctx create frontend -f ui-work -b develop\ndevctx create backend -f hotfix --create-branch hotfix/critical-bug\n```\n\n### `devctx list-repos`\n\nList all repositories in a GitHub organization.\n\n```bash\ndevctx list-repos ORGANIZATION [OPTIONS]\n```\n\n**Options:**\n- `--refresh-cache`: Force refresh of repository cache\n\n**Example:**\n```bash\ndevctx list-repos IndicoDataSolutions --refresh-cache\n```\n\n### `devctx config`\n\nView or modify configuration settings.\n\n```bash\ndevctx config [OPTIONS]\n```\n\n**Options:**\n- `--set-org ORG`: Set default organization\n\n**Examples:**\n```bash\ndevctx config # View current config\ndevctx config --set-org MyOrganization # Set default org\n```\n\n## Fuzzy Matching\n\nDevCtx includes intelligent fuzzy matching that helps when you make typos:\n\n```bash\n# Typo: \"workflws\" instead of \"workflows\"\ndevctx create indicore workflws -f test\n\n# DevCtx will show:\n# Multiple matches found for \"workflws\":\n# 1. workflows (score: 89%)\n# 2. workflex (score: 45%)\n# Select repository [1-2]: 1\n```\n\nThe fuzzy matching:\n- Automatically selects exact matches\n- Prompts for confirmation on close matches (>70% similarity)\n- Shows multiple options for ambiguous cases\n- Handles multiple typos in one command\n\n## Branch Management\n\nDevCtx provides flexible branch management:\n\n### Checkout Existing Branch\n```bash\ndevctx create repo1 repo2 -f workspace -b feature-branch\n```\n\nIf the branch doesn't exist in a repository, DevCtx will:\n1. Show a warning\n2. Fall back to the repository's default branch\n3. Continue with other repositories\n\n### Create New Branch\n```bash\ndevctx create repo1 repo2 -f workspace --create-branch feature/new-feature\n```\n\nDevCtx will:\n1. Create the branch from each repository's default branch\n2. Handle creation failures gracefully\n3. Report success/failure for each repository\n\n## Troubleshooting\n\n### Common Issues\n\n#### 1. \"GITHUB_TOKEN not found\"\n**Problem:** GitHub token not set in environment.\n\n**Solution:**\n```bash\nexport GITHUB_TOKEN=your_token_here\n# Add to your shell profile (.bashrc, .zshrc, etc.)\necho 'export GITHUB_TOKEN=your_token_here' >> ~/.bashrc\n```\n\n#### 2. \"Permission denied\" errors\n**Problem:** GitHub token doesn't have necessary permissions.\n\n**Solutions:**\n- Ensure token has `repo` scope for private repositories\n- Use `public_repo` scope for public repositories only\n- Check if you have access to the organization\n\n#### 3. \"Repository not found\"\n**Problem:** Repository doesn't exist or you don't have access.\n\n**Solutions:**\n- Verify repository name spelling\n- Check organization name\n- Ensure your GitHub token has access to the repository\n- Use `devctx list-repos ORGANIZATION` to see available repositories\n\n#### 4. \"Branch not found\"\n**Problem:** Specified branch doesn't exist.\n\n**Solutions:**\n- DevCtx will automatically fall back to the default branch\n- Check branch name spelling\n- Verify the branch exists in the repository\n\n#### 5. \"Folder already exists\"\n**Problem:** Workspace folder already exists.\n\n**Solutions:**\n- Use a different folder name with `-f other-name`\n- Remove existing folder: `rm -rf existing-folder`\n- DevCtx will prompt for confirmation before overwriting\n\n#### 6. Git clone failures\n**Problem:** Network issues or authentication problems.\n\n**Solutions:**\n- Check internet connection\n- Verify GitHub token is valid\n- Try refreshing cache with `--refresh-cache`\n- Check if repositories are private and you have access\n\n### Debug Tips\n\n1. **Use `--refresh-cache`** to force fresh repository data\n2. **Check config** with `devctx config` to verify settings\n3. **Test with public repos** first to verify setup\n4. **Use `devctx list-repos ORG`** to verify repository access\n\n### Getting Help\n\n- Run `devctx --help` for general help\n- Run `devctx COMMAND --help` for command-specific help\n- Check the [GitHub Issues](https://github.com/PragmaticMachineLearning/devctx/issues) for known problems\n- File a bug report if you encounter new issues\n\n## Development\n\n### Setup\n```bash\ngit clone https://github.com/PragmaticMachineLearning/devctx.git\ncd devctx\n\n# Install in development mode\npipx install -e .\n\n# Or with uv\nuv tool install -e .\n```\n\n### Running Tests\n```bash\n# Install test dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest\n```\n\n### Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Run tests to ensure everything works\n6. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\nIf you encounter issues or have questions:\n\n1. Check the [troubleshooting section](#troubleshooting)\n2. Search [existing issues](https://github.com/PragmaticMachineLearning/devctx/issues)\n3. Create a new issue if needed\n\n## Changelog\n\n### 0.1.0\n- Initial release\n- Basic workspace creation\n- Fuzzy matching for repository names\n- Branch management\n- Configuration system\n- Repository caching ",
"bugtrack_url": null,
"license": "MIT",
"summary": "A CLI tool for creating temporary monorepos from GitHub repositories",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/PragmaticMachineLearning/devctx",
"Issues": "https://github.com/PragmaticMachineLearning/devctx/issues",
"Repository": "https://github.com/PragmaticMachineLearning/devctx"
},
"split_keywords": [
"cli",
" git",
" github",
" monorepo",
" workspace"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "25a8a7baf81d2073e7d28d15ecbfc53e3dd5be02c470ad0366f64890d2c263eb",
"md5": "1b5643fc9b1e0032e32299cf82dcb3a1",
"sha256": "1f30d3b4559eb951913b533d5f2780d5392ef63144c4b412d89520153a2ee165"
},
"downloads": -1,
"filename": "devctx-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1b5643fc9b1e0032e32299cf82dcb3a1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 16406,
"upload_time": "2025-07-09T11:47:15",
"upload_time_iso_8601": "2025-07-09T11:47:15.924662Z",
"url": "https://files.pythonhosted.org/packages/25/a8/a7baf81d2073e7d28d15ecbfc53e3dd5be02c470ad0366f64890d2c263eb/devctx-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5dc14de11fde903cf7ffdbbb24ec31884c9c182c7e5513d57e392ac4f71a64ff",
"md5": "53da741617dbe217a6aaca15130e0c14",
"sha256": "f95dc974087a8494cfe9b34de678dca4378b44f920317440d45030dcc7ccc9b1"
},
"downloads": -1,
"filename": "devctx-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "53da741617dbe217a6aaca15130e0c14",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 97252,
"upload_time": "2025-07-09T11:47:17",
"upload_time_iso_8601": "2025-07-09T11:47:17.812113Z",
"url": "https://files.pythonhosted.org/packages/5d/c1/4de11fde903cf7ffdbbb24ec31884c9c182c7e5513d57e392ac4f71a64ff/devctx-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-09 11:47:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "PragmaticMachineLearning",
"github_project": "devctx",
"github_not_found": true,
"lcname": "devctx"
}