npm package: @pmatheis/goodgit
Description: CLI tool for GoodGit Commit - AI-powered commit message generation
Author: GoodGit Commit
Latest version: 1.2.21

# GoodGit Commit CLI

AI-powered Git commit message generator that analyzes your staged changes and suggests clear, conventional commit messages.

## Features

- 🤖 **AI-Powered**: Uses OpenAI to analyze code changes and generate meaningful commit messages
- 📝 **Conventional Commits**: Follows conventional commit standards (feat:, fix:, docs:, etc.)
- 🎯 **Smart Analysis**: Detects programming language and repository context
- ⚡ **Interactive**: Choose from multiple suggestions or enter custom messages
- 🔧 **Configurable**: Customize API settings, themes, and default behaviors
- 🚀 **Fast**: Quick setup and instant suggestions

## Installation

### From Source

```bash
# Clone the repository
git clone https://github.com/goodgit/commit.git
cd commit/cli

# Install dependencies
npm install

# Build the CLI
npm run build

# Install globally
npm link
```

### From NPM (Coming Soon)

```bash
npm install @pmatheis/goodgit
```

## Quick Start

1. **Get your API key** from the [GoodGit dashboard](https://goodgit.dev/dashboard)

2. **Setup** (first time only):
   ```bash
   goodgit setup
   ```
   You'll need to provide your API key during setup.

3. **Stage your changes**:
   ```bash
   git add .
   ```

3. **Generate commit message**:
   ```bash
   goodgit generate
   ```

## Usage

### Basic Commands

```bash
# Generate commit message from staged changes
goodgit generate
goodgit gen

# Sync local repository commits to GoodGit
goodgit sync

# Setup configuration
goodgit setup

# Manage configuration
goodgit config

# Show version information
goodgit version
```

### Advanced Options

#### Generate Command
```bash
# Force specific commit type
goodgit generate --type feat

# Add scope to commit message
goodgit generate --scope auth

# Include detailed body
goodgit generate --body

# Auto-accept first suggestion
goodgit generate --yes

# Dry run (show suggestions without committing)
goodgit generate --dry-run

# Custom API URL
goodgit generate --api-url https://api.goodgit.com
```

#### Sync Command
```bash
# Sync last 100 commits (default)
goodgit sync

# Sync specific number of commits
goodgit sync --max-commits 50

# Sync commits since a specific date
goodgit sync --since "2024-01-01"
goodgit sync --since "1 week ago"

# Sync all commits (no limit)
goodgit sync --force

# Custom API URL
goodgit sync --api-url https://api.goodgit.com
```

## Configuration

The CLI stores configuration in `~/.goodgit/config.json`. You can manage it through:

```bash
# Interactive configuration
goodgit config

# View current settings
goodgit config --list

# Reset to defaults
goodgit config --reset
```

### Configuration Options

- **API URL**: Backend API endpoint for commit generation
- **API Key**: **Required** - Authentication key for the API (get from dashboard)
- **Default Type**: Default commit type to use
- **Include Body**: Whether to include detailed body by default
- **Auto Accept**: Whether to auto-accept first suggestion
- **Theme**: UI theme preference (auto/light/dark)

> **Note**: An API key is required to use GoodGit Commit. You can get your API key from the [dashboard](https://goodgit.dev/dashboard) after signing up.

## Examples

### Basic Usage

```bash
$ git add src/components/Button.tsx
$ goodgit generate

🚀 GoodGit Commit - AI-Powered Commit Message Generator

📋 Staged Changes:
──────────────────────────────────────────────────
+export interface ButtonProps {
+  children: React.ReactNode;
+  variant?: 'primary' | 'secondary';
+  onClick?: () => void;
+}
+
+export const Button: React.FC<ButtonProps> = ({ children, variant = 'primary', onClick }) => {
+  return (
+    <button className={`btn btn-${variant}`} onClick={onClick}>
+      {children}
+    </button>
+  );
+};
──────────────────────────────────────────────────

🤖 Generating AI commit suggestions...

💡 AI-Generated Commit Suggestions:

1. [conventional]
   feat: add Button component with TypeScript support

2. [simple]
   Add reusable Button component

3. [detailed]
   feat(ui): add Button component with TypeScript support

   Add a reusable Button component with TypeScript interfaces,
   variant support, and click handling for improved UI consistency.

? Choose a commit message: (Use arrow keys)
❯ feat: add Button component with TypeScript support (conventional)
  Add reusable Button component (simple)
  feat(ui): add Button component with TypeScript support (detailed)
  ✏️  Enter custom message
  🔄 Regenerate suggestions
  ❌ Cancel
```

### With Options

```bash
# Force specific type and scope
$ goodgit generate --type feat --scope auth --body

# Auto-accept first suggestion
$ goodgit generate --yes

# Dry run to see suggestions without committing
$ goodgit generate --dry-run
```

## API Integration

The CLI connects to your GoodGit Commit backend API. Make sure your API is running and accessible.

### Local Development

```bash
# Start the backend API
cd ../app
npm run dev

# Use local API in CLI
goodgit generate --api-url http://localhost:3000/api
```

### Production

```bash
# Setup with production API
goodgit setup --api-url https://api.goodgit.com --api-key your-api-key
```

## Git Integration

### Git Hooks (Optional)

You can set up a Git hook to automatically suggest commit messages:

```bash
# Create prepare-commit-msg hook
echo '#!/bin/sh
goodgit generate --yes' > .git/hooks/prepare-commit-msg
chmod +x .git/hooks/prepare-commit-msg
```

### VS Code Integration

The CLI works great with VS Code's integrated terminal. You can also use it with the VS Code extension for seamless integration.

## Troubleshooting

### Common Issues

1. **"Not in a Git repository"**
   - Make sure you're in a Git repository directory
   - Run `git init` if needed

2. **"No staged changes found"**
   - Stage your changes with `git add .` or `git add <file>`
   - Check with `git status`

3. **"API connection failed"**
   - Check your API URL and key configuration
   - Ensure the backend API is running
   - Test connection with `goodgit config`

4. **"No suggestions generated"**
   - Check your API configuration
   - Ensure you have a valid API key
   - Try with `--dry-run` to debug

### Debug Mode

```bash
# Enable debug logging
DEBUG=goodgit* goodgit generate
```

## Development

### Building

```bash
# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode
npm run dev
```

### Testing

```bash
# Run tests (when available)
npm test

# Test with sample repository
cd test-repo
git add .
goodgit generate
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Support

- 📖 Documentation: https://docs.goodgit.com
- 🐛 Issues: https://github.com/goodgit/commit/issues
- 💬 Discussions: https://github.com/goodgit/commit/discussions