git-issue-commit/README.md

# git-issue-commit

[![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