From 5e38b3e649dbd061e5fdf1995e5fab0bc0014994 Mon Sep 17 00:00:00 2001 From: 7000pctAUTO Date: Thu, 29 Jan 2026 19:59:18 +0000 Subject: [PATCH] Initial commit: git-issue-commit CLI tool --- README.md | 266 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 265 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 7b490ae..3482414 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,267 @@ # git-issue-commit -A CLI tool that parses GitHub/GitLab issue URLs and generates conventional commit messages following semver standards \ No newline at end of file +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![Rust](https://img.shields.io/badge/Rust-1.70+-orange.svg)](https://www.rust-lang.org) +[![Version](https://img.shields.io/badge/Version-0.1.0-blue.svg)](https://github.com/7000pctAUTO/git-issue-commit/releases) + +A powerful CLI tool that parses GitHub/GitLab issue URLs or PR descriptions and generates [Conventional Commit](https://www.conventionalcommits.org/) messages following semver standards. + +## Table of Contents + +- [Features](#features) +- [Installation](#installation) +- [Quick Start](#quick-start) +- [Usage](#usage) + - [From GitHub Issue URL](#from-github-issue-url) + - [From GitLab Issue URL](#from-gitlab-issue-url) + - [From Text Description](#from-text-description) + - [Interactive Mode](#interactive-mode) + - [Direct Git Commit](#direct-git-commit) +- [Configuration](#configuration) +- [Examples](#examples) +- [Architecture](#architecture) +- [Contributing](#contributing) +- [License](#license) + +## Features + +- **Parse GitHub/GitLab URLs**: Extract issue/PR content using REST APIs with optional authentication +- **Conventional Commits**: Generate semver-compliant messages (e.g., `type(scope): description`) +- **Breaking Changes**: Automatically detect and format breaking changes per the conventional commits spec +- **Interactive Mode**: Review and edit generated messages before committing +- **Git Integration**: Direct commit with `--commit` flag or dry-run with `--dry-run` +- **Multiple Input Formats**: Support for GitHub, GitLab, and plain text descriptions +- **Type Detection**: Smart detection of commit types (feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert) + +## Installation + +### From Source + +```bash +git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/git-issue-commit.git +cd git-issue-commit +cargo install --path . +``` + +### From Crates.io (Coming Soon) + +```bash +cargo install git-issue-commit +``` + +### Pre-built Binaries + +Download pre-built binaries from the [Releases](https://7000pct.gitea.bloupla.net/7000pctAUTO/git-issue-commit/releases) page. + +## Quick Start + +```bash +# Generate a commit message from a GitHub issue +git-issue-commit --url https://github.com/owner/repo/issues/123 + +# Generate from plain text +git-issue-commit --text "Fix authentication bug where users couldn't login" + +# Interactive mode with preview +git-issue-commit --text "Add new feature" --interactive +``` + +## Usage + +### From GitHub Issue URL + +```bash +git-issue-commit --url https://github.com/owner/repo/issues/123 +``` + +For private repositories, set your GitHub token: + +```bash +export GITHUB_TOKEN=your_github_token +git-issue-commit --url https://github.com/owner/private-repo/issues/42 +``` + +### From GitLab Issue URL + +```bash +git-issue-commit --url https://gitlab.com/group/project/issues/456 +``` + +For private GitLab instances or private repositories: + +```bash +export GITLAB_TOKEN=your_gitlab_token +# For self-hosted GitLab +export GITLAB_API_URL=https://gitlab.company.com/api/v4 +git-issue-commit --url https://gitlab.company.com/group/project/issues/789 +``` + +### From Text Description + +```bash +git-issue-commit --text "Fix memory leak in connection pool" +``` + +Specify custom type and scope: + +```bash +git-issue-commit --text "Fix memory leak in connection pool" --type fix --scope db +``` + +### Interactive Mode + +Interactive mode allows you to review and edit the generated commit message before committing: + +```bash +git-issue-commit --text "Add new API endpoint" --interactive +``` + +### Direct Git Commit + +Commit directly to your repository: + +```bash +git-issue-commit commit --text "Fix login bug" +``` + +Dry run to preview without committing: + +```bash +git-issue-commit commit --text "Add new API endpoint" --dry-run +``` + +## Configuration + +### Environment Variables + +| Variable | Description | Required | +|----------|-------------|----------| +| `GITHUB_TOKEN` | GitHub API token for authenticated requests to private repos | No | +| `GITLAB_TOKEN` | GitLab API token for authenticated requests | No | +| `GITHUB_API_URL` | GitHub API endpoint (for GitHub Enterprise) | No | +| `GITLAB_API_URL` | GitLab API endpoint (for self-hosted GitLab instances) | No | + +### Commit Types + +| Type | Description | Example | +|------|-------------|---------| +| `feat` | A new feature | `feat(auth): add OAuth2 login` | +| `fix` | A bug fix | `fix(db): resolve connection timeout` | +| `docs` | Documentation only changes | `docs: update README` | +| `style` | White-space, formatting, missing semi-colons | `style: format code with rustfmt` | +| `refactor` | Code change neither fix nor add feature | `refactor: simplify authentication logic` | +| `perf` | Performance improvement | `perf(api): optimize database queries` | +| `test` | Adding or correcting tests | `test(auth): add unit tests for login` | +| `build` | Build system or dependencies | `build: update to Rust 1.70` | +| `ci` | CI configuration | `ci: add GitHub Actions workflow` | +| `chore` | Maintenance tasks | `chore: update dependencies` | +| `revert` | Revert a previous commit | `revert: revert #123` | + +## Examples + +### Basic GitHub Issue Parsing + +```bash +$ git-issue-commit --url https://github.com/user/repo/issues/42 +feat: add user authentication module + +This adds OAuth2 authentication to the application. + +BREAKING CHANGE: The login API endpoint has changed from /login to /auth/login +``` + +### With Custom Type and Scope + +```bash +$ git-issue-commit --text "Fix memory leak in connection pool" --type fix --scope db +fix(db): fix memory leak in connection pool +``` + +### Dry Run Mode + +```bash +$ git-issue-commit commit --text "Add new API endpoint" --dry-run +[dry-run] Would commit: +feat(api): add new API endpoint +``` + +### GitLab Enterprise + +```bash +$ export GITLAB_API_URL=https://gitlab.internal.company.com/api/v4 +$ export GITLAB_TOKEN=glpat-xxxxx +$ git-issue-commit --url https://gitlab.internal.company.com/mygroup/myproject/issues/123 +fix(auth): resolve SAML authentication issue +``` + +## Architecture + +``` +git-issue-commit/ +├── src/ +│ ├── main.rs # CLI entry point +│ ├── lib.rs # Library root +│ ├── cli/ # Command-line interface +│ ├── fetcher/ # GitHub/GitLab API fetching +│ ├── parser/ # Issue/PR content parsing +│ ├── generator/ # Commit message generation +│ └── interactive/ # Interactive editing mode +├── tests/ +│ ├── cli_tests.rs # CLI tests +│ ├── generator_tests.rs +│ ├── parser_tests.rs +│ └── integration_tests.rs +├── Cargo.toml +└── README.md +``` + +## Contributing + +Contributions are welcome! Please follow these steps: + +1. Fork the repository +2. Create a feature branch (`git checkout -b feature/amazing-feature`) +3. Commit your changes (`git commit -m 'feat: add amazing feature'`) +4. Push to the branch (`git push origin feature/amazing-feature`) +5. Open a Pull Request + +### Development Setup + +```bash +# Clone the repository +git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/git-issue-commit.git +cd git-issue-commit + +# Install dependencies +cargo build + +# Run tests +cargo test + +# Run lints +cargo clippy + +# Format code +cargo fmt +``` + +## Roadmap + +- [ ] Support for Bitbucket +- [ ] Commit message validation +- [ ] Configuration file support (`.git-issue-commit.yml`) +- [ ] Shell completion support +- [ ] Plugin system for custom commit templates + +## License + +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. + +## Support + +- Create an [Issue](https://7000pct.gitea.bloupla.net/7000pctAUTO/git-issue-commit/issues) for bugs or feature requests +- Check the [Documentation](docs/) for detailed guides + +--- + +Made with ❤️ by the git-issue-commit team