# 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:
```bash
node -v
```

### Global Installation (Recommended for Users)
To use GComet from anywhere on your system, install it globally using your preferred package manager:

```bash
# 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:

```bash
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:**
   ```bash
   git clone https://github.com/Soumyodeep-Das/gcomet.git
   cd gcomet
   ```

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

3. **Build the project:**
   This compiles the TypeScript code into JavaScript.
   ```bash
   pnpm run build
   ```

4. **Run in development mode:**
   You can run the CLI directly from the source code without installing it globally.
   ```bash
   pnpm run dev -- <command>
   
   # Example:
   pnpm run dev -- setup
   pnpm run dev -- suggest
   ```

5. **Run tests to verify:**
   ```bash
   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:**
```bash
gcomet setup
```

**If running from source:**
```bash
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:
```bash
git add .
gcomet generate
# or simply:
gcomet gen
```

Want to skip the prompt and auto-commit?
```bash
gcomet gen -f
```

Want to preview the message without committing?
```bash
gcomet gen --dry-run
```

Want to know *why* the AI chose that message?
```bash
gcomet gen --explain
```

### 2. Git Workflow Copilot

Stuck in Git? Ask GComet for advice based on your current repo state:
```bash
gcomet suggest
```

Confused by a Git command?
```bash
gcomet explain "git rebase -i HEAD~3"
```

Want to improve your Git skills?
```bash
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:
```bash
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?
```bash
gcomet conflicts
```

### 4. Collaboration

Generate a PR description summarizing your feature branch:
```bash
gcomet pr
gcomet pr -b main # Specify the base branch
```

Generate release notes for your next tag:
```bash
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:

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

To uninstall:
```bash
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:
    ```json
    {
      "rules": [
        { "pattern": "acme_secret_[a-zA-Z0-9]+", "label": "Acme Internal Token" }
      ],
      "disableDefaults": false
    }
    ```

---

## ⚙️ Configuration

Manage your configuration via the CLI:
```bash
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](CONTRIBUTING.md) for details on our code of conduct and the process for submitting Pull Requests.

## 📄 License

[MIT License](LICENSE)