GComet ☄️

AI-powered Git Workflow Copilot — smarter commits, safer code, better Git.

GComet goes beyond simple commit message generation. It's a comprehensive AI assistant for your entire Git workflow, powered by GitHub Models. From generating conventional commits and PR descriptions to guiding you through merge conflicts and repository hygiene, GComet makes Git easier, faster, and safer.

🚀 Features

Core Intelligence

• 🧠 AI Commit Generation: Automatically generates meaningful, Conventional Commits-compliant messages from your staged changes.
• 🔄 Interactive Workflow: Review, edit, or regenerate commit messages before they are applied.
• 📊 Quality Scoring: Built-in commit message grading helps you write better history.
• ⚡ Breaking Change Detection: Automatically flags backward-incompatible changes in your commits.
• 🛡️ Enterprise Security: Detects and sanitizes API keys, JWTs, DB URLs, and custom secrets locally before they ever reach the AI API.

Workflow Copilot

• 💡 Git Decision Assistant (suggest): Analyzes your repository state (detached HEAD, staged changes, conflicts) and recommends the exact commands you need to run next.
• 📖 Git Learning Mode (explain, learn): AI-powered explanations for any Git command and a curated library of "Did You Know?" best practices.
• 🌿 Branch Intelligence (branches): Visualize your branch tree, detect stale branches, and get safe cleanup recommendations.
• ⚡ Conflict Resolution (conflicts): Detects merge conflicts and provides step-by-step AI guidance on how to resolve them (without touching your code automatically).
• 📋 PR & Release Assistant (pr, release): Automatically generates Pull Request descriptions and release notes by summarizing commits between branches or tags.

📦 Installation & Upgrading

Prerequisites

Before installing GComet, make sure you have Node.js 16.0.0 or higher installed on your system. You can verify your Node.js version by running:

node -v

Global Installation (Recommended for Users)

To use GComet from anywhere on your system, install it globally using your preferred package manager:

# Using npm
npm install -g gcomet

# Using pnpm
pnpm add -g gcomet

# Using yarn
yarn global add gcomet

Upgrading GComet

To upgrade to the latest version of GComet to get new features and bug fixes:

npm update -g gcomet
# or
pnpm update -g gcomet
# or
yarn global upgrade gcomet

Running from Source (For Developers & Contributors)

If you want to clone the repository to modify the code, build it yourself, or contribute to the project, follow these steps:

1. Clone the repository:

   git clone https://github.com/Soumyodeep-Das/gcomet.git
   cd gcomet

2. Install dependencies: (We recommend using pnpm, but npm or yarn work too)

   pnpm install

3. Build the project: This compiles the TypeScript code into JavaScript.

   pnpm run build

4. Run in development mode: You can run the CLI directly from the source code without installing it globally.

   pnpm run dev -- <command>
      
   # Example:
   pnpm run dev -- setup
   pnpm run dev -- suggest

5. Run tests to verify:

   pnpm test

🛠️ Setup

Before using GComet (whether installed globally or running from source), run the setup wizard to configure your GitHub token and preferred AI model.

If installed globally:

gcomet setup

If running from source:

pnpm run dev -- setup

This will securely store your token with strict local permissions (0600) in ~/.gcomet/config.json.

📚 Usage

1. Generating Commits

Stage your files and let GComet write the commit message:

git add .
gcomet generate
# or simply:
gcomet gen

Want to skip the prompt and auto-commit?

gcomet gen -f

Want to preview the message without committing?

gcomet gen --dry-run

Want to know why the AI chose that message?

gcomet gen --explain

2. Git Workflow Copilot

Stuck in Git? Ask GComet for advice based on your current repo state:

gcomet suggest

Confused by a Git command?

gcomet explain "git rebase -i HEAD~3"

Want to improve your Git skills?

gcomet learn           # Shows a random tip
gcomet learn -c safety # Shows a safety tip
gcomet learn --all     # Shows all tips

3. Branch & Conflict Management

Clean up your local branches:

gcomet branches          # View a visual tree of all branches
gcomet branches --merged # Find branches safe to delete
gcomet branches --stale  # Find old, untouched branches

Need help with a merge conflict?

gcomet conflicts

4. Collaboration

Generate a PR description summarizing your feature branch:

gcomet pr
gcomet pr -b main # Specify the base branch

Generate release notes for your next tag:

gcomet release
gcomet release --from v1.0.0 # From a specific tag

5. Git Hook Integration

You can integrate GComet directly into your Git workflow so that git commit automatically triggers generation:

gcomet hook install

Now, running git commit (without -m) will automatically populate your editor with an AI-generated commit message.

To uninstall:

gcomet hook uninstall

🔒 Security First

GComet takes your security seriously.

1. Local Secret Scanning: GComet scans your diffs locally for over 15 types of sensitive data (AWS keys, GitHub PATs, JWTs, Database URLs, PEM keys, etc.).
2. Pre-Transmission Redaction: If secrets are found, they are automatically replaced with [REDACTED] before the diff is ever sent to the GitHub Models API.
3. Custom Organization Rules: Define your own internal secret patterns in a .gcomet-security.json file in your repository root:

   {
     "rules": [
       { "pattern": "acme_secret_[a-zA-Z0-9]+", "label": "Acme Internal Token" }
     ],
     "disableDefaults": false
   }

⚙️ Configuration

Manage your configuration via the CLI:

gcomet config list
gcomet config set model gpt-4o
gcomet config set maxDiffSize 15000
gcomet config set alwaysAskBeforeCommit false
gcomet config reset

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details on our code of conduct and the process for submitting Pull Requests.

📄 License

MIT License