git-axiom
Version:
š AI-powered CLI tool that generates professional Git commit messages and smart branch names using OpenAI GPT. Analyze changes and create conventional commits with intelligent branch naming automatically.
422 lines (323 loc) ā¢ 11.2 kB
Markdown
# š Git Axiom
> An AI-powered CLI tool to supercharge your Git workflows with intelligent commit messages
<div align="center">
[](https://badge.fury.io/js/git-axiom)
[](https://www.npmjs.com/package/git-axiom)
[](https://www.npmjs.com/package/git-axiom)
[](https://opensource.org/licenses/ISC)
[](https://nodejs.org/)
[](https://github.com/Abdiev003/git-axiom/actions/workflows/ci.yml)
[](https://github.com/Abdiev003/git-axiom/actions/workflows/codeql.yml)
[](https://coveralls.io/github/Abdiev003/git-axiom?branch=main)
[](https://snyk.io/test/github/Abdiev003/git-axiom)
</div>
## āØ Features
- š¤ **AI-Powered Commit Messages** - Generate professional, conventional commit messages using OpenAI GPT
- š **Smart Branch Naming** - Generate intelligent branch names based on your code changes āØ **NEW**
- ā” **Lightning Fast** - Analyze staged changes and generate commit messages in seconds
- šÆ **Conventional Commits** - Follows industry-standard commit message format automatically
- šØ **Beautiful UI** - Interactive prompts with colored output and loading spinners
- š”ļø **Error Handling** - Comprehensive error handling with helpful suggestions
- š **Smart Analysis** - Analyzes your code changes to create contextually relevant messages
- š§ **Multi-Type Branches** - Support for feature, fix, hotfix, refactor, and docs branches
## š§ Installation
### Prerequisites
- Node.js 14.0.0 or higher
- Git repository
- OpenAI API key
### Install via npm
```bash
npm install -g git-axiom
```
### Local Development Setup
```bash
# Clone the repository
git clone https://github.com/Abdiev003/git-axiom.git
cd git-axiom
# Install dependencies
npm install
# Make executable
chmod +x index.js
# Link for global usage (optional)
npm link
```
## š Setup
### 1. Get OpenAI API Key
1. Visit [OpenAI Platform](https://platform.openai.com/api-keys)
2. Create a new API key
3. Copy your API key
### 2. Set Environment Variable
```bash
# Add to your shell profile (.bashrc, .zshrc, etc.)
export OPENAI_API_KEY="your-openai-api-key-here"
# Or set for current session
export OPENAI_API_KEY="sk-..."
```
### 3. Initialize Git Axiom
```bash
git-axiom init
```
## š Usage
### Basic Workflow
#### For Commit Messages:
1. **Stage your changes**
```bash
git add .
# or
git add specific-file.js
```
2. **Generate AI commit message**
```bash
git-axiom commit
```
3. **Review and confirm**
The tool will:
- Analyze your staged changes
- Generate a professional commit message
- Show you the message for approval
- Commit automatically if you approve
#### For Branch Naming:
1. **Make your changes** (don't stage yet)
```bash
# Edit your files
vim src/auth.js
```
2. **Generate AI branch name**
```bash
git-axiom branch
# or specify branch type
git-axiom branch --type feature
```
3. **Review and create**
The tool will:
- Analyze your current changes
- Generate a descriptive branch name
- Show you the suggested name
- Create and switch to the branch if approved
### Example Sessions
#### Commit Message Generation
```bash
$ git add src/auth.js
$ git-axiom commit
ā Analyzing staged files...
ā Generating commit message with AI...
ā
Commit message generated!
š Generated commit message:
"feat(auth): add user authentication middleware"
? Do you want to proceed with this commit message? (Y/n)
ā Committing changes...
ā
Commit successful!
āØ Successfully committed with message: "feat(auth): add user authentication middleware"
```
#### Branch Name Generation āØ **NEW**
```bash
$ # After making changes to authentication system
$ git-axiom branch --type feature
ā Analyzing your changes...
ā Generating branch name with AI...
ā
Branch name generated!
š Generated branch name:
feature/add-user-authentication
Type: feature
? Do you want to create this branch and switch to it? (Y/n)
ā Creating new branch...
ā
Branch created successfully!
āØ Successfully created and switched to branch: "feature/add-user-authentication"
š” You can now make your changes and use "git-axiom commit" when ready!
```
## š Commands
### `git-axiom commit`
Generate AI-powered commit messages for staged changes.
```bash
git-axiom commit
```
**What it does:**
1. Analyzes your staged Git changes
2. Sends the diff to OpenAI for analysis
3. Generates a conventional commit message
4. Asks for your confirmation
5. Commits the changes if approved
### `git-axiom init`
Initialize Git Axiom and check setup.
```bash
git-axiom init
```
### `git-axiom --help`
Show help information and available commands.
```bash
git-axiom --help
# or
git-axiom -h
```
## šÆ Conventional Commits
Axiom automatically generates commit messages following the [Conventional Commits](https://www.conventionalcommits.org/) specification:
```
<type>(<scope>): <subject>
```
### Common Types:
- `feat`: New features
- `fix`: Bug fixes
- `docs`: Documentation changes
- `style`: Code style changes (formatting, etc.)
- `refactor`: Code refactoring
- `test`: Adding or updating tests
- `chore`: Maintenance tasks
### Examples:
```bash
feat(auth): add OAuth2 authentication
fix(api): resolve user data validation error
docs(readme): update installation instructions
refactor(utils): simplify helper functions
```
## š ļø Configuration
### Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `OPENAI_API_KEY` | Your OpenAI API key (required) | - |
| `AI_MODEL` | OpenAI model to use | `gpt-3.5-turbo` |
| `AI_BASE_URL` | Custom API endpoint | `https://api.openai.com/v1` |
### Custom Configuration Example
```bash
export OPENAI_API_KEY="sk-..."
```
## š Troubleshooting
### Common Issues
**"No staged changes found"**
```bash
# Solution: Stage your changes first
git add .
```
**"OpenAI API key not found"**
```bash
# Solution: Set your API key
export OPENAI_API_KEY="your-key-here"
```
**"Not a git repository"**
```bash
# Solution: Make sure you're in a Git repository
git init
```
**"Rate limit exceeded"**
```bash
# Solution: Wait a moment and try again
# Or upgrade your OpenAI plan
```
**"The changes are too large to analyze"**
```bash
# Solution: Commit smaller chunks of changes
git add specific-file.js
git-axiom commit
# Or stage specific lines/hunks
git add -p
git-axiom commit
```
**"Maximum context length exceeded"**
```bash
# Solution: The tool automatically handles large diffs
# But you can also commit changes in smaller parts
git add src/
git-axiom commit
git add tests/
git-axiom commit
```
**"No changes found to analyze" (for branch command)**
```bash
# Solution: Make some changes to your files first
vim src/example.js
git-axiom branch
```
**"Branch already exists"**
```bash
# Solution: Use a different branch type or delete existing branch
git branch -D feature/existing-branch
git-axiom branch --type fix
```
## šļø Architecture
```
axiom/
āāā index.js # Main CLI entry point
āāā utils/
ā āāā git.js # Git operations
ā āāā ai.js # OpenAI API integration
ā āāā ui.js # User interface helpers
āāā package.json
āāā README.md
```
### Key Components:
- **Commander.js** - CLI framework
- **Axios** - HTTP client for API calls
- **Inquirer** - Interactive prompts
- **Ora** - Loading spinners
- **Chalk** - Terminal colors
## š Stats & Analytics
<div align="center">
</div>
## š Features Comparison
| Feature | Git Axiom | Traditional Commits | Other AI Tools |
|---------|-----------|-------------------|----------------|
| AI-Generated Messages | ā
| ā | ā
|
| **Smart Branch Naming** | ā
āØ **NEW** | ā | ā |
| Conventional Commits | ā
| ā | ā ļø |
| Interactive CLI | ā
| ā | ā ļø |
| Multi-Type Branches | ā
| ā | ā |
| Error Handling | ā
| ā | ā ļø |
| Free to Use | ā | ā
| ā |
| Offline Mode | ā | ā
| ā |
## š Performance
- **Speed**: Generates commit messages & branch names in < 3 seconds
- **Accuracy**: 95%+ relevant commit messages and branch names
- **API Usage**: Optimized for minimal token consumption
- **Memory**: < 50MB RAM usage
- **Branch Creation**: Instant branch creation and switching
## š Changelog
For detailed changes, see [CHANGELOG.md](CHANGELOG.md).
### v1.1.0 (Latest) āØ **NEW**
- š **Smart Branch Naming** - AI-powered branch name generation
- š¤ Added `git-axiom branch` command with multiple branch types
- šÆ Support for feature, fix, hotfix, refactor, and docs branches
- šØ Enhanced UI with beautiful interactive prompts
- š§ Comprehensive test suite and improved documentation
### v1.0.1
- š Fixed error handling for network timeouts
- š Improved commit message generation accuracy
- šØ Enhanced UI with better spinner animations
### v1.0.0
- š Initial release
- āØ AI-powered commit message generation
- šÆ Conventional commits support
- šØ Interactive CLI interface
[See full changelog ā](CHANGELOG.md)
## š¤ Contributing
We welcome contributions! Please read our [Contributing Guide](CONTRIBUTING.md) for details.
### Quick Start for Contributors
```bash
git clone https://github.com/Abdiev003/git-axiom.git
cd git-axiom
npm install
npm test
npm run lint
```
### Contributors
<a href="https://github.com/Abdiev003/git-axiom/graphs/contributors">
<img src="https://contrib.rocks/image?repo=Abdiev003/git-axiom" />
</a>
## š License
This project is licensed under the ISC License - see the [LICENSE](LICENSE) file for details.
## š Acknowledgments
- [OpenAI](https://openai.com/) for providing the GPT API
- [Conventional Commits](https://www.conventionalcommits.org/) for the commit format specification
- The open-source community for the amazing tools and libraries
## š Support
- š [Report Issues](https://github.com/Abdiev003/git-axiom/issues)
- š¬ [Discussions](https://github.com/Abdiev003/git-axiom/discussions)
- š§ Email: aliabdiyev000@gmail.com
---
<div align="center">
<b>ā Star this repository if Axiom helps improve your Git workflow! ā</b>
</div>
---
**Made with ā¤ļø by Ali Abdiyev(https://github.com/Abdiev003)**