Core git operations engine:
- Safe git command execution with error handling
- Repository validation and detection
- Git status, log, diff, and branch operations
- File staging/unstaging and blame information
- Stash management and commit operations
- Branch creation, checkout, and management
- Repository insights (contributors, remotes, commit search)
- Reset operations with safety checks
CodeCompanion chat tool integration:
- OpenAI-compatible function calling schema
- Natural language interface for git operations
- Comprehensive parameter validation and handling
- Formatted output for chat buffer display
- Approval system for destructive operations
- Error handling and user feedback
- Integration with CodeCompanion's agent system A CodeCompanion extension that generates AI-powered git commit messages following the Conventional Commits specification.
- 🤖 AI-powered commit message generation using CodeCompanion's LLM adapters
- 📋 Interactive UI with copy to clipboard and yank register options
- ✅ Conventional Commits specification compliance
- 🔍 Automatic git repository detection
- 📝 Support for both user commands and slash commands
- ⌨️ Smart keymap integration for gitcommit buffers
- 🌍 Multi-language support for commit messages
- 🔄 Support for both regular commits and
git commit --amend - 📁 File filtering support with glob patterns to exclude files from diff analysis
- 🛠️ @git_bot tool - Advanced Git operations through CodeCompanion chat
- 📊 Git status and branch management - Check status, create/switch branches
- 🔍 Advanced Git operations - Diff, log, blame, stash operations
- 👥 Repository insights - Contributors, commit search, remote info
- 🔒 Safe operations - Automatic approval requirements for destructive operations
- 💬 Natural language interface - Control Git through conversation
- 📝 Comprehensive Git workflow - From status check to commit in one chat
Add this to your CodeCompanion configuration:
require("codecompanion").setup({
extensions = {
gitcommit = {
callback = "codecompanion._extensions.gitcommit",
opts = {
add_slash_command = true, -- Optional: adds /gitcommit slash command
adapter = "openai", -- Optional: specify LLM adapter (defaults to codecompanion chat adapter)
model = "gpt-4", -- Optional: specify model (defaults to codecompanion chat model)
languages = { "English", "简体中文", "日本語", "Français", "Español" }, -- Optional: list of languages for commit messages
exclude_files = { "*.pb.go", "*.min.js", "package-lock.json" }, -- Optional: exclude files from diff analysis
add_git_tool = true, -- Optional: add @git_bot tool to CodeCompanion (default: true)
add_git_commands = true, -- Optional: add :CodeCompanionGit commands (default: true)
buffer = {
enabled = true, -- Enable gitcommit buffer keymaps
keymap = "<leader>gc", -- Keymap for generating commit message in gitcommit buffer
auto_generate = true, -- Automatically generate message on entering gitcommit buffer
auto_generate_delay = 100, -- Delay in ms before auto-generating
}
}
}
}
}):CodeCompanionGitCommit- Generate git commit message:CCGitCommit- Short alias for the above command:CodeCompanionGit- Open CodeCompanion chat with git assistant (🆕):CCGit- Short alias for git assistant (🆕)
Use :CodeCompanionGit or :CCGit to open a CodeCompanion chat buffer with the @git_bot tool pre-loaded. This gives you a natural language interface to Git operations.
In any CodeCompanion chat buffer, use the @git_bot tool to perform Git operations:
@git_bot help # Show available operations
@git_bot status # Show git status
@git_bot log --count 5 # Show last 5 commits
@git_bot diff --staged # Show staged changes
@git_bot branch # List all branches
@git_bot create_branch --branch_name feature/new-ui
@git_bot stage --files ["src/main.lua", "README.md"]
@git_bot stash --message "Work in progress"
Repository Status & Info
@git_bot status- Show repository status@git_bot log [--count N] [--format FORMAT]- Show commit history@git_bot branch [--remote_only]- List branches@git_bot remotes- Show remote repositories@git_bot contributors [--count N]- Show top contributors
File Operations
@git_bot diff [--staged] [--file_path PATH]- Show differences@git_bot stage --files ["file1", "file2"]- Stage files@git_bot unstage --files ["file1", "file2"]- Unstage files@git_bot blame --file_path PATH [--line_start N] [--line_end N]- Show blame info
Branch Management
@git_bot create_branch --branch_name NAME [--checkout BOOL]- Create new branch@git_bot checkout --target BRANCH_OR_COMMIT- Switch branch/commit
Commit Operations
@git_bot show [--commit_hash HASH]- Show commit details@git_bot diff_commits --commit1 HASH1 [--commit2 HASH2] [--file_path PATH]- Compare commits@git_bot search_commits --pattern "PATTERN" [--count N]- Search commits
Stash Operations
@git_bot stash [--message "MSG"] [--include_untracked]- Stash changes@git_bot stash_list- List all stashes@git_bot apply_stash [--stash_ref "stash@{0}"]- Apply stash
Advanced Operations (require approval)
@git_bot reset --commit_hash HASH [--mode soft|mixed|hard]- Reset to commit
The git tool includes automatic safety features:
- Read-only operations (status, log, diff, show, blame) don't require approval
- Modifying operations (stage, unstage, create_branch, checkout, reset) require user confirmation
- Repository validation ensures you're in a valid Git repository
- Comprehensive error handling with helpful error messages
Code Review Workflow:
@git_bot status
@git_bot diff --staged
/gitcommit # Generate commit message
Branch Management:
@git_bot branch
@git_bot create_branch --branch_name feature/new-ui
# ... make changes ...
@git_bot stage --files ["src/ui.lua"]
@git_bot status
Investigation Workflow:
@git_bot log --count 10
@git_bot show --commit_hash abc123
@git_bot blame --file_path src/main.lua --line_start 50 --line_end 60
When you run git commit or open a gitcommit buffer:
- If
buffer.auto_generateistrue, the commit message will be generated and inserted automatically. - If
buffer.auto_generateisfalse(default), press<leader>gc(or your configured keymap) in normal mode to trigger generation. - The generated message will be inserted directly into the commit buffer.
In a CodeCompanion chat buffer, use /gitcommit to generate a commit message.
local gitcommit = require("codecompanion").extensions.gitcommit
-- Generate commit message with language selection
gitcommit.generate("English", function(result, error)
if error then
print("Error:", error)
else
print("Generated:", result)
end
end)
-- Generate commit message without language (uses default)
gitcommit.generate(nil, function(result, error)
if error then
print("Error:", error)
else
print("Generated:", result)
end
end)
-- Check if in git repository
local is_git_repo = gitcommit.is_git_repo()
-- Get staged diff
local diff = gitcommit.get_staged_diff()
-- Commit changes
local success = gitcommit.commit_changes("feat: add new feature")
-- Get buffer configuration
local buffer_config = gitcommit.get_buffer_config()
-- Git Tool API (🆕)
-- Basic operations
local success, output = gitcommit.git_tool.status()
local success, branches = gitcommit.git_tool.branches()
local success, log = gitcommit.git_tool.log(5, "oneline")
-- File operations
local success, diff = gitcommit.git_tool.diff(true) -- staged diff
local success, diff_file = gitcommit.git_tool.diff(false, "src/main.lua") -- specific file
gitcommit.git_tool.stage({"src/main.lua", "README.md"})
gitcommit.git_tool.unstage({"src/main.lua"})
-- Branch operations
local success, current = gitcommit.git_tool.current_branch()
gitcommit.git_tool.create_branch("feature/new-feature", true) -- create and checkout
gitcommit.git_tool.checkout("main")
-- Repository info
local success, remotes = gitcommit.git_tool.remotes()
local success, contributors = gitcommit.git_tool.contributors(10)
local success, commit_info = gitcommit.git_tool.show("HEAD")
-- Blame and history
local success, blame = gitcommit.git_tool.blame("src/main.lua", 10, 20)
local success, commits = gitcommit.git_tool.search_commits("fix bug", 5)
local success, comparison = gitcommit.git_tool.diff_commits("HEAD~1", "HEAD", "src/main.lua")
-- Stash operations
gitcommit.git_tool.stash("Work in progress", true) -- include untracked
local success, stashes = gitcommit.git_tool.stash_list()
gitcommit.git_tool.apply_stash("stash@{0}")
-- Advanced operations (use with caution)
gitcommit.git_tool.reset("HEAD~1", "soft")lua/codecompanion/_extensions/gitcommit/
├── init.lua # Main extension entry point and command registration
├── git.lua # Git operations (repository detection, diff, commit, amend support)
├── generator.lua # LLM integration for commit message generation
├── ui.lua # Floating window UI and interactions
├── buffer.lua # GitCommit buffer keymap integration
├── langs.lua # Language selection functionality
├── types.lua # Type definitions and TypeScript-style annotations
└── tools/ # Git tool implementations (🆕)
├── git.lua # Core git operations and command execution
└── git_bot.lua # CodeCompanion chat tool integration
Handles all git-related operations:
- Repository detection with filesystem and git command fallback
- Staged changes retrieval and contextual diff generation
- File filtering support with glob patterns to exclude files from analysis
- Support for both regular commits and
git commit --amend - Commit execution with proper error handling
Manages LLM interaction:
- Prompt creation for commit message generation with language support
- API communication with CodeCompanion adapters
- Response handling and error management
- Adapter and model configuration
Provides interactive user interface:
- Floating window display with markdown formatting
- Interactive keyboard shortcuts (
c,y,s,Enter,q/Esc) - Copy to clipboard and yank register functionality
- Responsive window sizing
Handles gitcommit buffer integration:
- Automatic keymap setup for gitcommit filetype
- Smart commit message insertion at correct position
- Buffer content management and validation
- Language selection integration
Manages language selection:
- Multi-language support configuration
- Interactive language selection UI
- Language preference handling
Provides type definitions:
- TypeScript-style type annotations for Lua
- Interface definitions for all modules
- Configuration option types
Main extension coordinator:
- Module integration and dependency management
- Command registration (
:CodeCompanionGitCommit,:CCGitCommit) - Slash command integration
- Extension exports for programmatic usage
- Git tool integration and command setup (🆕)
- Neovim with CodeCompanion plugin installed
- Git repository with staged changes
- Configured LLM adapter in CodeCompanion
- Stage your changes with
git add - Run
:CodeCompanionGitCommit - Review the generated commit message in the floating window
- Choose an action:
c- Copy to clipboardy- Copy to yank registers- Submit (commit changes)Enter- Copy and closeq/Esc- Close without action
When the floating window is displayed with the generated commit message, the following keymaps are available:
c- Copy the commit message to the system clipboard (+register)y- Copy the commit message to Vim's default yank register ("register)s- Submit the commit message immediately (executesgit commit)Enter- Copy to clipboard and close the floating windowqorEsc- Close the floating window without taking any action
- Stage your changes with
git add - Run
git committo open the commit buffer - If
auto_generateis enabled, the message appears automatically. Otherwise, press<leader>gcin normal mode to generate it. - The AI-generated message will be inserted into the buffer.
- Edit if needed and save to complete the commit.
- Make additional changes to your files
- Stage changes with
git add(optional, for new changes) - Run
git commit --amendto open the amend buffer - Press
<leader>gcin normal mode to generate an updated commit message - The extension will analyze the full commit changes and generate an appropriate message
- Edit if needed and save to complete the amend
The extension accepts the following options:
opts = {
add_slash_command = true, -- Add /gitcommit slash command to chat buffer
adapter = "openai", -- LLM adapter to use (default: codecompanion chat adapter)
model = "gpt-4", -- Model to use (default: codecompanion chat model)
languages = { "English", "简体中文", "日本語", "Français", "Español" }, -- Languages for commit messages
exclude_files = { "*.pb.go", "*.min.js", "package-lock.json" }, -- File patterns to exclude from diff analysis
add_git_tool = true, -- Add @git_bot tool to CodeCompanion (default: true)
add_git_commands = true, -- Add :CodeCompanionGit commands (default: true)
git_tool_auto_submit_errors = false, -- Auto-submit git tool errors to LLM (default: false)
git_tool_auto_submit_success = false, -- Auto-submit git tool success to LLM (default: false)
buffer = {
enabled = true, -- Enable gitcommit buffer keymaps (default: true)
keymap = "<leader>gc", -- Keymap for generating commit message (default: "<leader>gc")
auto_generate = false, -- Automatically generate message on entering gitcommit buffer (default: false)
auto_generate_delay = 100, -- Delay in ms before auto-generating (default: 100)
}
}When enabled, adds /gitcommit slash command to CodeCompanion chat buffers.
When enabled, adds the @git_bot tool to CodeCompanion chat buffers. This allows you to perform Git operations through natural language in chat.
When enabled, adds :CodeCompanionGit and :CCGit commands that open a chat buffer with the git tool pre-loaded.
When enabled, automatically submits git tool error messages back to the LLM for analysis and suggestions.
When enabled, automatically submits git tool success messages back to the LLM to continue the workflow.
The LLM adapter to use for generating commit messages. If not specified, defaults to the adapter configured for CodeCompanion's chat strategy.
The specific model to use with the adapter. If not specified, defaults to the model configured for CodeCompanion's chat strategy.
A list of languages that can be used for generating commit messages. When specified, the extension will prompt you to select a language before generating the commit message. If not provided or empty, commit messages will be generated in English by default.
Example:
languages = { "English", "简体中文", "日本語", "Français", "Español" }A list of file patterns to exclude from git diff analysis when generating commit messages. Supports glob patterns using * and ? wildcards. This is useful for excluding generated files, minified files, or large files that don't need AI analysis.
Examples:
exclude_files = {
"*.pb.go", -- Protocol buffer generated files
"*.min.js", -- Minified JavaScript files
"package-lock.json", -- NPM lock file
"yarn.lock", -- Yarn lock file
"*.generated.ts", -- Generated TypeScript files
"dist/*", -- Distribution directory
"build/*" -- Build directory
}Controls whether gitcommit buffer keymap integration is enabled.
The keymap used in gitcommit buffers to trigger commit message generation.
When true, automatically generates a commit message upon entering a gitcommit buffer, but only if the buffer does not already contain a message (to avoid overwriting during an amend).
The delay in milliseconds before the automatic generation is triggered. This helps prevent race conditions with other plugins (like neogit) that manage UI elements. You can increase this value if you still experience issues.
Feel free to submit issues and enhancement requests!