xoegit 1.1.4 → 1.1.5

package/README.md

@@ -17,6 +17,7 @@
 - **Atomic Commits** — Automatically suggests splitting large changes into multiple logical commits
 - **Execute Mode** — Optionally execute commits with confirmation using `--execute`
 - **Context Aware** — Provide context with `--context` for more accurate commit messages
+- **Explain Mode** — Learn commit crafting with `--explain` to see reasoning behind each grouping
 - **Smart Fallback** — Automatically switches between Gemini models when rate limits are hit
 - **Semantic Commits** — Strictly follows [Conventional Commits](https://www.conventionalcommits.org/)
 - **PR Ready** — Generates ready-to-use PR title and description
@@ -37,13 +38,19 @@ You remain in full control of your git workflow.
 - **Git**: Must be installed and available in your PATH
 - **API Key**: A Google Gemini API key ([get one here](https://aistudio.google.com/))
 
-### Install
+### Quick Start
+
+```bash
+npx xoegit
+```
+
+### Global Installation (Optional)
 
 ```bash
 npm install -g xoegit
 ```
 
-**or** install from source:
+### Install from Source 
 
 ```bash
 git clone git@github.com:ujangdoubleday/xoegit.git
@@ -59,7 +66,13 @@ Simply run `xoegit` for the first time. It will prompt you for your API Key secu
 
 ## Usage
 
-Then, from whatever project you're working on, just run:
+From any git repository, just run:
+
+```bash
+npx xoegit
+```
+
+**or** if installed globally:
 
 ```bash
 xoegit
@@ -74,6 +87,7 @@ xoegit
 | `-k, --api-key <key>`  | Use specific API key for this session               |
 | `-c, --context <text>` | Provide context for more accurate suggestions       |
 | `-e, --execute`        | Execute commits after confirmation prompt           |
+| `--explain`            | Show reasoning behind each commit grouping          |
 | `-s, --set-key <key>`  | Save API key to config                              |
 | `-d, --delete-key`     | Delete saved API key from config                    |
 | `-V, --version`        | Show version                                        |
@@ -84,36 +98,41 @@ xoegit
 **Basic usage:**
 
 ```bash
-xoegit
+npx xoegit
 ```
 
 **With context for better commit type detection:**
 
 ```bash
-xoegit --context "refactoring folder structure"
-xoegit -c "fixing authentication bug"
-xoegit -c "adding new payment feature"
+npx xoegit --context "refactoring folder structure"
+npx xoegit -c "fixing authentication bug"
+npx xoegit -c "adding new payment feature"
 ```
 
-**Use API key for this session only (not saved):**
-
 ```bash
-xoegit --api-key "YOUR_GEMINI_API_KEY"
+npx xoegit --api-key "YOUR_GEMINI_API_KEY"
 ```
 
 **Manage API key:**
 
 ```bash
-xoegit --set-key "YOUR_GEMINI_API_KEY"
-xoegit --delete-key
+npx xoegit --set-key "YOUR_GEMINI_API_KEY"
+npx xoegit --delete-key
 ```
 
 **Execute mode (auto-commit with confirmation):**
 
 ```bash
-xoegit --execute
-xoegit -e
-xoegit -e -c "fixing critical bug"
+npx xoegit --execute
+npx xoegit -e
+npx xoegit -e -c "fixing critical bug"
+```
+
+**Explain mode (verbose reasoning):**
+
+```bash
+npx xoegit --explain
+npx xoegit --explain -c "refactoring auth module"
 ```
 
 ### Sample Output
@@ -137,6 +156,20 @@ pr description: feat(auth): implement secure login
 - refactor(utils): improve error logging
 ```
 
+### Explain Mode Output
+
+```
+commit 1
+git add src/auth/login.ts src/auth/validator.ts
+git commit -m "feat(auth): add login validation"
+why: I grouped these files because they both handle authentication logic and the validator is directly used by login.ts.
+
+commit 2
+git add package.json package-lock.json
+git commit -m "chore: update dependencies"
+why: I separated dependency updates from code changes to keep the commit atomic and make it easy to revert if needed.
+```
+
 ### Execute Mode Output
 
 ```

package/dist/cli/analyze.js

@@ -80,7 +80,7 @@ export async function analyzeAction() {
             return;
         }
         // 3. Generate Prompt
-        const systemPrompt = await generateSystemPrompt();
+        const systemPrompt = await generateSystemPrompt({ explain: options.explain });
         // Get user context if provided
         const userContext = options.context || '';
         if (userContext) {

package/dist/cli/program.js

@@ -9,4 +9,5 @@ program
     .option('-c, --context <context>', 'Context for the changes (e.g., "refactoring folder structure")')
     .option('-s, --set-key <key>', 'Save Gemini API Key to config (overwrites existing)')
     .option('-d, --delete-key', 'Delete saved API Key from config')
-    .option('-e, --execute', 'Execute commit after confirmation prompt');
+    .option('-e, --execute', 'Execute commit after confirmation prompt')
+    .option('--explain', 'Show explanation for each commit grouping (verbose mode)');

package/dist/prompts/service.js

@@ -4,7 +4,7 @@ import url from 'url';
 /**
  * Generates the system prompt for the AI
  */
-export async function generateSystemPrompt() {
+export async function generateSystemPrompt(options = {}) {
     let rulesContent = '';
     try {
         const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
@@ -15,6 +15,33 @@ export async function generateSystemPrompt() {
         console.warn('Could not read RULES.md, using default rules.');
         rulesContent = 'Follow conventional commits.';
     }
+    // Build explain mode instructions
+    const explainInstructions = options.explain
+        ? `
+EXPLAIN MODE ENABLED:
+For each commit, you MUST add a "why:" line directly after the git commit command (no blank line in between).
+This line should explain the logical reasoning behind grouping these specific files together.
+
+Format:
+commit N
+git add <files>
+git commit -m "<message>"
+why: <one sentence explaining why these files are grouped together>
+
+Example:
+commit 1
+git add src/auth/login.ts src/auth/utils.ts
+git commit -m "feat(auth): add login validation"
+why: I grouped these files because they both handle authentication logic and the validation directly depends on the auth utilities.
+
+commit 2
+git add package.json package-lock.json
+git commit -m "chore: update dependencies"
+why: I separated dependency updates from code changes to keep the commit atomic and make it easy to revert if needed.
+
+The explanation should help developers understand your commit crafting logic for educational purposes.
+`
+        : '';
     return `
 You are a Git Commit Assistant for the 'xoegit' CLI.
 Your goal is to suggest git commands and commit messages based on the provided changes.
@@ -28,7 +55,7 @@ Your goal is to suggest git commands and commit messages based on the provided c
 RULES FROM USER:
 ${rulesContent}
 ---
-
+${explainInstructions}
 IMPORTANT:
 - You definitely MUST NOT execute commands. You only suggest them.
 - Output MUST be strictly valid shell commands or clear instructions as per the examples in RULES.md.

package/dist/utils/ui.js

@@ -53,6 +53,10 @@ function formatSuggestionLine(line) {
     if (line.startsWith('pr title:') || line.startsWith('pr description:')) {
         return chalk.yellow(line);
     }
+    // Format explanation lines from --explain mode
+    if (line.startsWith('why:')) {
+        return brand.muted('   ') + chalk.italic.hex('#A78BFA')(line);
+    }
     return line;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xoegit",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "description": "AI-powered CLI tool for generating semantic git commit messages and PR descriptions",
   "license": "MIT",
   "author": "ujangdoubleday",