488 lines
13 KiB
Markdown
488 lines
13 KiB
Markdown
# DevTools
|
|
|
|
A collection of developer tools to enhance your workflow. This package includes tools for generating commit messages, changelogs, hooks, and .gitignore files, all accessible from a single unified CLI: `devtools`.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
# Stable release from PyPI
|
|
pip install devtools-utils
|
|
|
|
# Using pipx
|
|
pipx install devtools-utils
|
|
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### API Keys
|
|
|
|
The tools use various APIs that require API keys. You can set these using the config command:
|
|
|
|
```bash
|
|
# Set AI provider API key (required for AI features)
|
|
# For OpenRouter
|
|
devtools config set OPENROUTER_API_KEY "your-openrouter-api-key"
|
|
|
|
# For OpenAI
|
|
devtools config set OPENAI_API_KEY "your-openai-api-key"
|
|
|
|
# For Google Gemini
|
|
devtools config set GOOGLE_API_KEY "your-google-api-key"
|
|
|
|
# For Anthropic Claude
|
|
devtools config set ANTHROPIC_API_KEY "your-anthropic-api-key"
|
|
|
|
# For Hugging Face
|
|
devtools config set HUGGINGFACE_API_KEY "your-huggingface-api-key"
|
|
|
|
# Set GitHub token (recommended for license generator)
|
|
devtools config set GITHUB_TOKEN "your-github-token"
|
|
```
|
|
|
|
Or set them in your environment:
|
|
|
|
```bash
|
|
# AI Provider API keys
|
|
export OPENROUTER_API_KEY="your-openrouter-api-key"
|
|
export OPENAI_API_KEY="your-openai-api-key"
|
|
export GOOGLE_API_KEY="your-google-api-key"
|
|
export ANTHROPIC_API_KEY="your-anthropic-api-key"
|
|
export HUGGINGFACE_API_KEY="your-huggingface-api-key"
|
|
|
|
# GitHub token for license generator
|
|
export GITHUB_TOKEN="your-github-token"
|
|
```
|
|
|
|
### Managing Configuration
|
|
|
|
```bash
|
|
# Show all configuration
|
|
devtools config show
|
|
|
|
# Show specific value
|
|
devtools config show OPENROUTER_API_KEY
|
|
|
|
# Delete a value
|
|
devtools config delete OPENROUTER_API_KEY
|
|
|
|
# Clear all configuration
|
|
devtools config clear
|
|
```
|
|
|
|
Configuration files are stored in:
|
|
|
|
- `~/.devtools/config.yaml`
|
|
|
|
Example config.yaml:
|
|
|
|
```yaml
|
|
# API Keys
|
|
OPENROUTER_API_KEY:
|
|
OPENAI_API_KEY:
|
|
GOOGLE_API_KEY:
|
|
ANTHROPIC_API_KEY:
|
|
HUGGINGFACE_API_KEY:
|
|
GITHUB_TOKEN:
|
|
|
|
# AI Settings
|
|
provider: openrouter # or "openai", "gemini", "claude", "huggingface"
|
|
model: mistralai/mixtral-8x7b-instruct # model name for the selected provider
|
|
max_tokens: 1024
|
|
temperature: 0.7
|
|
output_format: text
|
|
|
|
# Commit Settings
|
|
conventional_commits: true
|
|
emoji: false
|
|
|
|
# Repository Settings
|
|
repositories: []
|
|
```
|
|
|
|
## Configuration via CLI
|
|
|
|
You can set up all configuration options for DevTools using the CLI. This is the recommended way to configure your `~/.devtools/config.yaml` file:
|
|
|
|
```bash
|
|
# Set AI provider (required for AI features)
|
|
devtools config set provider "openrouter" # or "openai", "gemini", "claude", "huggingface"
|
|
|
|
# Set preferred AI model (optional, depends on provider)
|
|
# For OpenRouter
|
|
devtools config set model "mistralai/mixtral-8x7b-instruct"
|
|
# For OpenAI
|
|
devtools config set model "gpt-4-turbo-preview"
|
|
# For Gemini
|
|
devtools config set model "gemini-pro"
|
|
# For Claude
|
|
devtools config set model "claude-3-opus-20240229"
|
|
# For Hugging Face
|
|
devtools config set model "mistralai/Mixtral-8x7B-Instruct-v0.1"
|
|
|
|
# Set temperature for AI completions (optional, default is 0.7)
|
|
devtools config set temperature 0.7
|
|
|
|
# Set maximum tokens for AI completions (optional, default is 150)
|
|
devtools config set max_tokens 150
|
|
|
|
# Set conventional commit style (optional, default is true)
|
|
devtools config set conventional_commits true
|
|
|
|
# Enable or disable emojis in commit messages (optional, default is false)
|
|
devtools config set emoji false
|
|
|
|
# Set output format (optional, e.g., text or markdown)
|
|
devtools config set output_format text
|
|
|
|
# Set repositories list (optional, usually not needed)
|
|
devtools config set repositories "[]"
|
|
```
|
|
|
|
To view your current configuration:
|
|
|
|
```bash
|
|
devtools config show
|
|
```
|
|
|
|
To delete a config value:
|
|
|
|
```bash
|
|
devtools config delete output_format
|
|
```
|
|
|
|
To clear all config:
|
|
|
|
```bash
|
|
devtools config clear
|
|
```
|
|
|
|
All configuration is stored in `~/.devtools/config.yaml` and can be managed entirely through these commands. You do not need to manually edit the YAML file.
|
|
|
|
## Usage
|
|
|
|
All tools are available under the main `devtools` command:
|
|
|
|
```
|
|
devtools [COMMAND] [SUBCOMMAND] [OPTIONS]
|
|
```
|
|
|
|
### Commit Message Generator
|
|
|
|
Generate and apply commit messages, create changelogs, and manage configuration.
|
|
|
|
#### Generate Commit Message
|
|
|
|
```bash
|
|
devtools commit generate [OPTIONS]
|
|
```
|
|
|
|
**Options:**
|
|
|
|
- `--files, -f [FILE]...` Specific files to generate commit messages for
|
|
- `--repo, -r PATH` Repository path (default: current directory)
|
|
- `--commit, -c` Automatically commit changes
|
|
- `--push, -p` Push changes after commit
|
|
- `--conventional/--no-conventional` Use conventional commit format (default: True)
|
|
- `--no-stage` Skip automatic staging of changes
|
|
- `--sign` Sign commits with GPG
|
|
- `--temperature FLOAT` AI temperature (0.0-1.0)
|
|
- `--emoji/--no-emoji` Include emoji prefixes (default: disabled)
|
|
- `--smart-group/--per-file` Group multi-file changes into one commit (default: smart-group)
|
|
- `--no-verify` Bypass git hooks when committing
|
|
|
|
Commit messages follow the conventional format (emojis optional):
|
|
|
|
When emojis are enabled, these prefixes are used:
|
|
- ✨ feat: New feature
|
|
- 🐛 fix: Bug fix
|
|
- 📚 docs: Documentation
|
|
- 💅 style: Formatting, missing semi colons, etc
|
|
- ♻️ refactor: Code refactoring
|
|
- ✅ test: Adding tests
|
|
- 🔧 chore: Maintenance
|
|
|
|
Per-file vs grouped commits:
|
|
|
|
- Use `--smart-group` (default) to generate a single message that covers all staged changes.
|
|
- Use `--per-file` to generate a message per changed file. The CLI will create separate git commits, one per file, each with its own AI-generated message.
|
|
|
|
Examples:
|
|
|
|
```bash
|
|
# Single grouped message (default behavior)
|
|
devtools commit generate -c
|
|
|
|
# Separate commits per file
|
|
devtools commit generate --per-file -c
|
|
```
|
|
|
|
#### Changelog Generation
|
|
|
|
```bash
|
|
# From commit subcommand (legacy path)
|
|
devtools commit changelog generate [OPTIONS]
|
|
|
|
# Top-level changelog commands
|
|
devtools changelog generate [OPTIONS] # from git history (alias: g)
|
|
devtools changelog generate-interactive [OPTIONS] # interactive mode (alias: i)
|
|
devtools changelog generate-from-file [OPTIONS] # from a file (alias: f)
|
|
```
|
|
|
|
**Options (history-based):**
|
|
|
|
- `--version, -v VERSION` Version number (required)
|
|
- `--from-tag, -t TAG` Generate from this tag
|
|
- `--days, -d N` Generate from the last N days
|
|
- `--commits, -n N` Generate from the last N commits
|
|
- `--output, -o FILE` Output file path (default: CHANGELOG.md)
|
|
- `--temperature FLOAT` AI temperature (default: 0.7)
|
|
|
|
**Options (interactive):**
|
|
|
|
- `--version, -v VERSION` Version number (required)
|
|
- `--output, -o FILE` Output file path (default: CHANGELOG.md)
|
|
- `--temperature FLOAT` AI temperature (default: 0.7)
|
|
|
|
**Options (from file):**
|
|
|
|
- `--version, -v VERSION` Version number (required)
|
|
- `--input, -i FILE` Input changes file (required)
|
|
- `--output, -o FILE` Output file path (default: CHANGELOG.md)
|
|
- `--temperature FLOAT` AI temperature (default: 0.7)
|
|
|
|
The changelog generator supports three modes:
|
|
|
|
1. Git history: Automatically generates changelog from commit history
|
|
2. Interactive: Enter changes manually with emoji prefixes
|
|
3. File-based: Generate from a file containing changes
|
|
|
|
Changes are grouped by type with emojis:
|
|
|
|
- ✨ Added
|
|
- 🔄 Changed
|
|
- 🐛 Fixed
|
|
- 🚀 Performance
|
|
- 📝 Documentation
|
|
- 🔧 Maintenance
|
|
- 🗑️ Removed
|
|
- 🔒 Security
|
|
|
|
#### Repository Status
|
|
|
|
```bash
|
|
devtools commit status
|
|
```
|
|
|
|
---
|
|
|
|
### Gitignore Generator
|
|
|
|
Generate .gitignore files for your project, either by auto-detecting project types or specifying technologies.
|
|
|
|
#### Auto-detect Project Types
|
|
|
|
```bash
|
|
devtools gitignore auto [OPTIONS]
|
|
```
|
|
|
|
**Options:**
|
|
|
|
- `--directory, -d DIR` Directory to scan (default: current directory)
|
|
- `--output, -o FILE` Output file path (default: .gitignore)
|
|
|
|
#### Generate for Specific Technologies
|
|
|
|
```bash
|
|
devtools gitignore generate python django vscode [OPTIONS]
|
|
```
|
|
|
|
**Options:**
|
|
|
|
- `--output, -o FILE` Output file path (default: .gitignore)
|
|
|
|
The generator uses the gitignore.io API to fetch templates. No API key is required.
|
|
|
|
---
|
|
|
|
### License Generator
|
|
|
|
Generate LICENSE files for your project using templates from GitHub's license API.
|
|
|
|
```bash
|
|
# List available licenses
|
|
devtools license list
|
|
|
|
# Generate a license
|
|
devtools license generate [OPTIONS]
|
|
```
|
|
|
|
**Options:**
|
|
|
|
- `--type, -t TYPE` Type of license to generate (e.g., mit, apache-2.0, gpl-3.0)
|
|
- `--author, -a NAME` Name of the author/copyright holder
|
|
- `--year, -y YEAR` Year for the copyright notice (defaults to current year)
|
|
- `--output, -o FILE` Output file path (default: LICENSE)
|
|
- `--multi, -m` Generate multiple licenses in one run
|
|
|
|
Example:
|
|
|
|
```bash
|
|
# List available licenses
|
|
devtools license list
|
|
|
|
# Interactive mode
|
|
devtools license generate
|
|
|
|
# With all options specified
|
|
devtools license generate --type mit --author "John Doe" --year 2024 --output LICENSE
|
|
|
|
# Generate multiple licenses in one go
|
|
devtools license generate --multi
|
|
```
|
|
|
|
The license generator uses GitHub's license API to fetch templates. For optimal performance:
|
|
|
|
1. Set up a GitHub token:
|
|
```bash
|
|
devtools config set GITHUB_TOKEN "your-github-token"
|
|
```
|
|
This increases your API rate limit from 60 to 5,000 requests per hour.
|
|
|
|
2. If no token is set, the tool will use a fallback list of common licenses.
|
|
|
|
If an invalid license type is provided, the tool will display a list of available licenses.
|
|
|
|
When generating multiple licenses with `--multi`, separate files are created (e.g., `LICENSE_mit`, `LICENSE_apache-2.0`). A summary `LICENSE.md` is also written linking to each generated license.
|
|
|
|
---
|
|
|
|
### Hooks Manager
|
|
|
|
Manage Git hooks easily. Install lint/test hooks for `pre-commit` and `pre-push`.
|
|
|
|
```bash
|
|
# Install both pre-commit and pre-push hooks in current repo
|
|
devtools hooks install
|
|
|
|
# Install only pre-commit
|
|
devtools hooks install --pre-commit --no-pre-push
|
|
|
|
# Install only pre-push
|
|
devtools hooks install --no-pre-commit --pre-push
|
|
|
|
# Uninstall hooks
|
|
devtools hooks uninstall # both
|
|
devtools hooks uninstall --pre-commit --no-pre-push
|
|
|
|
# Use your own script templates
|
|
devtools hooks install \
|
|
--pre-commit-template ./scripts/hooks/my-pre-commit.sh \
|
|
--pre-push-template ./scripts/hooks/my-pre-push.sh
|
|
|
|
# List hooks present in the repository
|
|
devtools hooks list
|
|
```
|
|
|
|
The hooks auto-detect your ecosystem and run sensible defaults:
|
|
|
|
- Node.js: `npm run lint --if-present` then `eslint` or `prettier --check`; tests via `npm test`/`pnpm test`/`yarn test`
|
|
- Python: `ruff .` or fallback to `black --check .`; tests via `pytest -q`
|
|
- Rust: `cargo fmt --check`; tests via `cargo test`
|
|
- Go: `gofmt -l` (fail if unformatted), `go vet`; tests via `go test ./...`
|
|
- Java: Gradle `check`/`test` or Maven `verify -DskipTests=true`/`test`
|
|
- If `.pre-commit-config.yaml` is present, `pre-commit run --all-files` is used for pre-commit, and `pre-commit run --hook-stage push --all-files` for pre-push.
|
|
|
|
You can customize hooks by editing files in `.git/hooks/` after installation.
|
|
Alternatively, pass `--pre-commit-template` and/or `--pre-push-template` to install from your own script files. The files will be copied into `.git/hooks/` and made executable.
|
|
|
|
Note: If a hook already exists, DevTools creates a timestamped backup in `.git/hooks/` with the `.bak` suffix before overwriting, e.g., `pre-commit.20250101123000.bak`.
|
|
|
|
Auto-fix behavior (pre-commit):
|
|
|
|
- If initial checks fail, DevTools attempts to auto-fix issues by running `scripts/format.py` and `scripts/lintfix.py` if those files exist in your repo.
|
|
- Any changes made are automatically staged (`git add -A`), and checks are re-run. The commit will fail only if the re-run still fails.
|
|
- You can run these scripts manually as well:
|
|
|
|
```bash
|
|
python3 scripts/format.py
|
|
python3 scripts/lintfix.py
|
|
```
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
- **Commit Message Generator:**
|
|
- AI-powered commit message suggestions using multiple providers:
|
|
- OpenRouter (Mixtral 8x7B)
|
|
- OpenAI (GPT-4, GPT-3.5)
|
|
- Google Gemini
|
|
- Anthropic Claude
|
|
- Hugging Face
|
|
- Conventional commit format with emojis
|
|
- GPG signing and push support
|
|
- Changelog generation from commit history
|
|
- Repository status with diff previews
|
|
- **Gitignore Generator:**
|
|
- Auto-detects project types and generates .gitignore
|
|
- Uses gitignore.io API for up-to-date templates
|
|
- No API key required
|
|
- Falls back to generic template if API is unavailable
|
|
- **License Generator:**
|
|
- Generates LICENSE files using GitHub's license API
|
|
- Supports all licenses available on GitHub
|
|
- Interactive license selection
|
|
- Automatic year and author replacement
|
|
|
|
## Requirements
|
|
|
|
- Python 3.8+
|
|
- Git
|
|
- AI Provider API key (one of):
|
|
- OpenRouter API key
|
|
- OpenAI API key
|
|
- Google API key
|
|
- Anthropic API key
|
|
- Hugging Face API key
|
|
- GitHub token (recommended for license generator)
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://github.com/S4NKALP/DevTools.git
|
|
cd DevTools
|
|
|
|
# (Optional) Create and activate a virtual environment
|
|
python3 -m venv .venv
|
|
source .venv/bin/activate
|
|
|
|
# Install package in editable (dev) mode
|
|
pip install -e .
|
|
|
|
# Install dev tools (optional but recommended)
|
|
pip install pytest black ruff
|
|
|
|
# Run tests
|
|
pytest
|
|
|
|
# Lint and format
|
|
black .
|
|
|
|
# Or use the helper scripts (if present)
|
|
python3 scripts/format.py
|
|
python3 scripts/lintfix.py
|
|
|
|
# Run the CLI locally after editable install
|
|
devtools --help
|
|
```
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! Please open issues or submit pull requests.
|
|
|
|
## License
|
|
|
|
This project is licensed under the GNU General Public License v3.0 (GPL-3.0) - see the LICENSE file for details.
|