🚀 NeoCommit

AI-powered git commit message generation with seamless workflow integration

NeoCommit is a production-ready, AI-powered tool that generates meaningful git commit messages. Designed for seamless integration with modern development workflows including lint-staged, husky, and automated CI/CD pipelines.

Features

• AI-Powered Generation: Leverages OpenAI GPT models for contextual commit message creation
• Package.json Integration: Configuration management through package.json for team collaboration
• Workflow Integration: First-class support for lint-staged, husky, and CI/CD systems
• Advanced Template System: Conventional commits, custom formats, and flexible templating with variables
• Lightweight Architecture: Minimal dependencies with optimized performance
• Multilingual Support: Generate commit messages in multiple languages and locales
• Intelligent Analysis: Advanced file filtering and diff analysis capabilities
• Extensible Design: Custom templates with variable support and configurable prompts

Installation

Global Installation

# Install globally with pnpm (recommended)
pnpm add -g neocommit

# Or with npm
npm install -g neocommit

# Or use with pnpx/npx without installation
pnpx neocommit
npx neocommit

Project Installation

# Add to project dependencies
pnpm add -D neocommit

# Or with npm
npm install --save-dev neocommit

Quick Start

# Interactive setup (recommended for first time)
neocommit --init

# Stage your changes
git add .

# Generate and commit with AI-generated message
neocommit

# Generate message without committing (preview mode)
neocommit --dry-run

# Use specific template
neocommit --template conventional

Configuration

Package.json Configuration (Recommended)

Configure NeoCommit directly in your package.json for team-wide settings:

{
  "neocommit": {
    "provider": "openai",
    "apiKey": "$OPENAI_API_KEY",
    "model": "gpt-4o-mini",
    "template": "conventional",
    "locale": "en",
    "maxLength": 50,
    "generate": 1,
    "timeout": 10000,
    "include": ["src/**", "lib/**", "*.js", "*.ts"],
    "exclude": ["*.lock", "dist/**", "node_modules/**"],
    "analysis": {
      "maxFiles": 50,
      "maxDiffSize": "100kb",
      "ignoreWhitespace": true,
      "priorities": {
        "src/**": "high",
        "test/**": "medium",
        "docs/**": "low"
      }
    }
  },
  "scripts": {
    "commit": "neocommit",
    "commit:dry": "neocommit --dry-run"
  }
}

Configuration File

Create a .neocommit.json file in your project root for advanced configuration:

{
  "provider": "openai",
  "apiKey": "$OPENAI_API_KEY",
  "template": "conventional",
  "maxLength": 50,
  "locale": "en",
  "analysis": {
    "maxFiles": 50,
    "maxDiffSize": "100kb",
    "priorities": {
      "src/**": "high",
      "tests/**": "medium",
      "docs/**": "low"
    }
  },
  "templates": {
    "team": {
      "system": "Generate a commit message using our team's format with ticket reference.",
      "format": "[{ticket}] {type}: {description}",
      "variables": {
        "ticket": {
          "type": "text",
          "required": true,
          "description": "Ticket or issue number",
          "prompt": "Enter the ticket/issue number"
        },
        "type": {
          "type": "select",
          "options": ["FEATURE", "BUGFIX", "HOTFIX", "REFACTOR"],
          "required": true,
          "description": "Type of change"
        },
        "description": {
          "type": "text",
          "required": true,
          "description": "Brief description of the change"
        }
      },
      "examples": [
        "[ABC-123] FEATURE: Add user authentication",
        "[DEF-456] BUGFIX: Fix memory leak in parser"
      ]
    }
  }
}

Environment Variables

# API Keys
export OPENAI_API_KEY="sk-..."

# Configuration overrides
export NEOCOMMIT_PROVIDER="openai"
export NEOCOMMIT_MODEL="gpt-4o-mini"
export NEOCOMMIT_TEMPLATE="conventional"
export NEOCOMMIT_LOCALE="en"
export NEOCOMMIT_MAX_LENGTH="50"
export NEOCOMMIT_GENERATE="1"
export NEOCOMMIT_TIMEOUT="10000"

Template System

Built-in Templates

Conventional Commits (Default)

neocommit --template conventional
# Output: feat(auth): add OAuth2 login support

Simple Format

neocommit --template simple
# Output: Add OAuth2 login support

Emoji Format

neocommit --template emoji
# Output: ✨ Add OAuth2 login support

Custom Templates

Define advanced custom templates with variables and validation:

{
  "neocommit": {
    "templates": {
      "detailed": {
        "system": "Generate a detailed commit message with comprehensive information.",
        "format": "{emoji} {type}({scope}): {description}\n\n{details}",
        "variables": {
          "emoji": {
            "type": "select",
            "options": ["✨", "🐛", "📝", "🎨", "♻️", "✅", "🔧", "⚡"],
            "required": true,
            "description": "Emoji representing the change"
          },
          "type": {
            "type": "auto",
            "description": "Auto-detected change type",
            "default": "feat"
          },
          "scope": {
            "type": "auto",
            "description": "Auto-detected scope from files"
          },
          "description": {
            "type": "text",
            "required": true,
            "description": "Brief description"
          },
          "details": {
            "type": "text",
            "description": "Additional details (optional)"
          }
        },
        "examples": [
          "✨ feat(auth): add OAuth2 integration\n\nImplemented Google and GitHub OAuth providers"
        ],
        "maxLength": 120
      }
    }
  }
}

Template Variables

Templates support three types of variables:

• select: Choose from predefined options
• text: Free-form text input
• auto: Automatically detected from code changes

Each variable can have:

• type: Variable type (select, text, auto)
• options: Available choices for select type
• required: Whether the variable is mandatory
• default: Default value
• description: Human-readable description
• prompt: Custom prompt text

Workflow Integration

Integration with Lint-Staged

Seamlessly integrate with your existing lint-staged workflow:

{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "*.{js,ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*": [
      "neocommit --staged --template conventional"
    ]
  }
}

Integration with Husky v8+

# .husky/pre-commit
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

pnpx lint-staged
pnpx neocommit --staged --dry-run # Validate commit message generation

CI/CD Integration (GitLab)

stages:
  - test
  - build
  - deploy

commit_validation:
  stage: test
  image: node:18
  script:
    - npm install -g pnpm
    - pnpm install --frozen-lockfile
    - pnpm exec neocommit --dry-run
  only:
    - merge_requests

automated_commits:
  stage: deploy
  image: node:18
  script:
    - git config --local user.email "[email protected]"
    - git config --local user.name "GitLab CI"
    - git add .
    - pnpx neocommit || exit 0
  only:
    - main

Multilingual Support

Generate commit messages in different languages:

{
  "neocommit": {
    "locale": "es",
    "templates": {
      "conventional": {
        "system": "Genera un mensaje de commit convencional en español usando el formato: {type}({scope}): {description}"
      }
    }
  }
}

Supported locales: en, es, fr, de, ja, zh, ko, pt, ru, it

Advanced Configuration

File Analysis Control

Configure intelligent file analysis and prioritization:

{
  "neocommit": {
    "include": ["src/**", "lib/**"],
    "exclude": ["*.test.js", "*.spec.ts", "*.lock"],
    "analysis": {
      "maxFiles": 50,
      "maxDiffSize": "100kb",
      "ignoreWhitespace": true,
      "priorities": {
        "src/components/**": "high",
        "src/utils/**": "medium",
        "docs/**": "low"
      }
    }
  }
}

Provider Configuration

{
  "neocommit": {
    "provider": "openai",
    "providers": {
      "openai": {
        "apiKey": "$OPENAI_API_KEY",
        "model": "gpt-4o-mini",
        "temperature": 0.7,
        "maxTokens": 200,
        "timeout": 10000
      }
    }
  }
}

CLI Reference

neocommit [options]

Options:
  -d, --dry-run               Generate message without committing
  -s, --staged                Only analyze staged files
  -t, --template <name>       Use specific template (conventional, simple, emoji)
  -g, --generate <number>     Generate multiple message options
  -m, --max-length <number>   Maximum commit message length
  -l, --locale <code>         Language for commit message
  -f, --files <pattern>       Analyze specific file patterns
  -c, --config <path>         Use specific config file
  -q, --quiet                 Silent mode - only output the commit message
  -i, --init                  Initialize configuration interactively
  -h, --help                  Show help
  -v, --version               Show version

Examples:
  neocommit                                    # Generate and commit
  neocommit --dry-run                         # Generate only
  neocommit --template conventional           # Use conventional commits
  neocommit --generate 3                      # Generate 3 options
  neocommit --staged --files "src/**"         # Analyze specific files
  neocommit --locale es                       # Spanish commit message
  neocommit --init                            # Interactive setup

Configuration Priority

NeoCommit loads configuration from multiple sources in order of priority:

1. CLI options (highest priority)
2. package.json neocommit field
3. .neocommit.json file
4. Environment variables
5. Global config (~/.neocommit.json)
6. Default config (lowest priority)

Development

Local Development Setup

git clone https://gitlab.com/maxmcneal/neocommit.git
cd neocommit
pnpm install
pnpm run build

Testing and Quality Assurance

pnpm test                    # Run test suite
pnpm run test:watch          # Watch mode for development
pnpm run lint                # Code linting
pnpm run typecheck           # TypeScript type checking
pnpm run format              # Code formatting

Contributing

We welcome contributions to NeoCommit. Please follow these steps:

1. Fork the repository on GitLab
2. Create a feature branch (git checkout -b feature/enhancement-name)
3. Commit your changes with conventional commit messages
4. Push to your branch (git push origin feature/enhancement-name)
5. Create a Merge Request with a detailed description

CI/CD Pipeline

This project uses GitLab CI/CD for comprehensive automation:

• Quality Assurance: Automated testing, linting, and type checking
• Build Process: TypeScript compilation and artifact generation
• Publishing: Automated npm publishing on version tags
• Security: Dependency vulnerability scanning and security audits

Release Process:

1. Update version in package.json
2. Create and push a git tag: git tag v1.x.x && git push origin --tags
3. The CI/CD pipeline will automatically publish to npm

API Documentation

Core Types

interface NeoCommitConfig {
  provider: string;
  apiKey?: string;
  model?: string;
  template?: string;
  locale?: string;
  maxLength?: number;
  generate?: number;
  include?: string[];
  exclude?: string[];
  timeout?: number;
  analysis?: {
    maxFiles?: number;
    maxDiffSize?: string;
    ignoreWhitespace?: boolean;
    priorities?: Record<string, 'high' | 'medium' | 'low'>;
  };
  templates?: Record<string, TemplateConfig>;
  providers?: Record<string, ProviderConfig>;
}

interface TemplateConfig {
  system: string;
  format?: string;
  variables?: Record<string, TemplateVariable>;
  examples?: string[];
  maxLength?: number;
  locale?: string;
}

interface TemplateVariable {
  type: 'select' | 'text' | 'auto';
  options?: string[];
  default?: string;
  required?: boolean;
  description?: string;
  prompt?: string;
}

interface CommitMessage {
  message: string;
  confidence: number;
  template: string;
  variables?: Record<string, string>;
}

Troubleshooting

Common Issues

API Key Configuration

# Verify API key is set
echo $OPENAI_API_KEY

# Set API key for current session
export OPENAI_API_KEY="your-api-key-here"

# Or run interactive setup
neocommit --init

Large Repository Performance

{
  "neocommit": {
    "analysis": {
      "maxFiles": 25,
      "maxDiffSize": "50kb",
      "exclude": ["node_modules/**", "dist/**", "*.lock"]
    }
  }
}

Template Validation Errors

{
  "neocommit": {
    "templates": {
      "custom": {
        "system": "Required: system prompt",
        "variables": {
          "type": {
            "type": "select",
            "options": ["feat", "fix"], // Required for select type
            "required": true
          }
        }
      }
    }
  }
}

Repository • Package • Issues • Contributions • License