devctx

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"
}