feat(git-tool): add advanced Git operations and chat integration

.gitignore

@@ -0,0 +1 @@
+doc/tags

README.md

@@ -1,9 +1,34 @@
 # CodeCompanion Git Commit Extension
 
+### `tools/git.lua`
+
+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
+
+### `tools/git_bot.lua`
+
+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.
 
 ## Features
 
+### Core Features
 - 🤖 AI-powered commit message generation using CodeCompanion's LLM adapters
 - 📋 Interactive UI with copy to clipboard and yank register options
 - ✅ Conventional Commits specification compliance
@@ -14,6 +39,16 @@ A CodeCompanion extension that generates AI-powered git commit messages followin
 - 🔄 Support for both regular commits and `git commit --amend`
 - 📁 File filtering support with glob patterns to exclude files from diff analysis
 
+### Git Tool Features
+- 🛠️ **@git_read tool** - Read-only Git operations through CodeCompanion chat (status, log, diff, etc.)
+- ✍️ **@git_edit tool** - Write-access Git operations through CodeCompanion chat (stage, unstage, branch creation, etc.)
+- 📊 **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
+
 ## Installation
 
 ### As a CodeCompanion Extension
@@ -29,8 +64,11 @@ require("codecompanion").setup({
         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
+        languages = { "English", "Chinese", "Japanese", "French", "Spanish" }, -- 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_read and @git_edit tools to CodeCompanion (default: true)
+        add_git_commands = true,   -- Optional: add :CodeCompanionGit commands (default: true)
+        gitcommit_select_count = 100, -- Optional: number of recent commits for /gitcommit slash command (default: 100)
         buffer = {
           enabled = true,        -- Enable gitcommit buffer keymaps
           keymap = "<leader>gc", -- Keymap for generating commit message in gitcommit buffer
@@ -49,6 +87,123 @@ require("codecompanion").setup({
 
 - `: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
+### Git Tool Operations
+
+#### Interactive Git Assistant
+
+Use `:CodeCompanionGit` or `:CCGit` to open a CodeCompanion chat buffer. You can then use `@git_read` for read-only operations or `@git_edit` for operations that modify the repository.
+
+#### Chat Integration
+
+In any CodeCompanion chat buffer, use `@git_read` or `@git_edit` to perform Git operations:
+
+```
+@git_read help                    # Show available read-only operations
+@git_read status                  # Show git status
+@git_read log --count 5           # Show last 5 commits
+@git_read diff --staged           # Show staged changes
+@git_read branch                  # List all branches
+
+@git_edit help                    # Show available write-access operations
+@git_edit create_branch --branch_name feature/new-ui
+@git_edit stage --files ["src/main.lua", "README.md"]
+@git_edit stash --message "Work in progress"
+```
+
+#### Git Tool Commands Reference
+
+**@git_read: Read-only Git Operations**
+
+**Repository Status & Info**
+- `@git_read status` - Show repository status
+- `@git_read log [--count N] [--format FORMAT]` - Show commit history
+- `@git_read branch [--remote_only]` - List branches
+- `@git_read remotes` - Show remote repositories
+- `@git_read contributors [--count N]` - Show top contributors
+- `@git_read show [--commit_hash HASH]` - Show commit details
+- `@git_read diff_commits --commit1 HASH1 [--commit2 HASH2] [--file_path PATH]` - Compare commits
+- `@git_read search_commits --pattern "PATTERN" [--count N]` - Search commits
+- `@git_read stash_list` - List all stashes
+• `@git_read blame --file_path PATH [--line_start N] [--line_end N]` - Show blame info
+- `@git_read gitignore_get` - View current .gitignore content
+- `@git_read gitignore_check --gitignore_file "FILE"` - Check if file is ignored
+- `@git_read tags` - List all tags
+
+**@git_edit: Write-access Git Operations**
+
+**File Operations**
+- `@git_edit stage --files ["file1", "file2"]` - Stage files
+- `@git_edit unstage --files ["file1", "file2"]` - Unstage files
+
+**Branch Management**
+- `@git_edit create_branch --branch_name NAME [--checkout BOOL]` - Create new branch
+- `@git_edit checkout --target BRANCH_OR_COMMIT` - Switch branch/commit
+
+**Stash Operations**
+- `@git_edit stash [--message "MSG"] [--include_untracked]` - Stash changes
+- `@git_edit apply_stash [--stash_ref "stash@{0}"]` - Apply stash
+
+**Tag Management**
+- `@git_edit create_tag --tag_name NAME [--tag_message "MSG"] [--tag_commit_hash HASH]` - Create a new tag
+• `@git_edit delete_tag --tag_name NAME [--remote REMOTE]` - Delete a tag (from local and optionally remote)
+
+**Advanced Operations** (require approval)
+- `@git_edit reset --commit_hash HASH [--mode soft|mixed|hard]` - Reset to commit
+
+**GitIgnore Management**
+- `@git_edit gitignore_add --gitignore_rule "RULE"` - Add rule to .gitignore
+- `@git_edit gitignore_add --gitignore_rules ["rule1", "rule2"]` - Add multiple rules
+• `@git_edit gitignore_remove --gitignore_rule "RULE"` - Remove rule from .gitignore
+• `@git_edit push [--remote REMOTE] [--branch BRANCH] [--force BOOL] [--tags BOOL] [--tag_name NAME]` - Push changes to a remote repository.
+  WARNING: `force` push is dangerous and can overwrite remote history. Use with extreme caution.
+• `@git_edit rebase [--onto ONTO] [--base BASE] [--interactive BOOL]` - Rebase current branch onto another.
+  WARNING: `interactive` rebase opens an editor and is not suitable for automated environments. It can also rewrite history.
+• `@git_edit cherry_pick --cherry_pick_commit_hash HASH` - Apply the changes introduced by some existing commits.
+• `@git_edit revert --revert_commit_hash HASH` - Revert a commit.
+
+#### Safety Features
+
+The git tools include automatic safety features:
+- **Read-only operations** (via `@git_read`) do not require approval.
+- **Modifying operations** (via `@git_edit`) require user confirmation.
+- **Repository validation** ensures you're in a valid Git repository.
+- **Comprehensive error handling** with helpful error messages.
+
+#### Example Workflows
+
+**Code Review Workflow:**
+```
+@git_read status
+@git_read diff --staged
+/gitcommit  # Generate commit message
+```
+
+**Branch Management:**
+```
+@git_read branch
+@git_edit create_branch --branch_name feature/new-ui
+# ... make changes ...
+@git_edit stage --files ["src/ui.lua"]
+@git_read status
+```
+
+**Investigation Workflow:**
+```
+@git_read log --count 10
+@git_read show --commit_hash abc123
+@git_read blame --file_path src/main.lua --line_start 50 --line_end 60
+```
+
+**GitIgnore Management Workflow:**
+```
+@git_read gitignore_get                              # View current .gitignore
+@git_edit gitignore_add --gitignore_rule "*.log"     # Add single rule
+@git_edit gitignore_add --gitignore_rules ["dist/", "build/", "*.tmp"] # Add multiple rules
+@git_read gitignore_check --gitignore_file "temp.log" # Check if file is ignored
+@git_edit gitignore_remove --gitignore_rule "*.log"  # Remove rule
+```
 
 ### GitCommit Buffer Integration
 
@@ -96,6 +251,41 @@ 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")
 ```
 
 ## File Structure
@@ -108,7 +298,11 @@ lua/codecompanion/_extensions/gitcommit/
 ├── 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
+├── types.lua       # Type definitions and TypeScript-style annotations
+└── tools/          # Git tool implementations
+    ├── git.lua     # Core git operations and command execution
+    ├── git_read.lua # CodeCompanion chat tool for read-only Git operations
+    └── git_edit.lua # CodeCompanion chat tool for write-access Git operations
 ```
 
 ## Module Overview
@@ -174,6 +368,7 @@ Main extension coordinator:
 - Command registration (`:CodeCompanionGitCommit`, `:CCGitCommit`)
 - Slash command integration
 - Extension exports for programmatic usage
+- Git tool integration and command setup
 
 ## Requirements
 
@@ -231,8 +426,13 @@ 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
+  languages = { "English", "Chinese", "Japanese", "French", "Spanish" }, -- 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)
+  gitcommit_select_count = 100, -- Number of recent commits for /gitcommit slash command (default: 100)
   buffer = {
     enabled = true,        -- Enable gitcommit buffer keymaps (default: true)
     keymap = "<leader>gc", -- Keymap for generating commit message (default: "<leader>gc")
@@ -248,6 +448,25 @@ opts = {
 
 When enabled, adds `/gitcommit` slash command to CodeCompanion chat buffers.
 
+#### `add_git_tool` (boolean, default: `true`)
+
+When enabled, adds the `@git_read` and `@git_edit` tools to CodeCompanion chat buffers. This allows you to perform Git operations through natural language in chat.
+
+#### `add_git_commands` (boolean, default: `true`)
+
+When enabled, adds `:CodeCompanionGit` and `:CCGit` commands that open a chat buffer for Git assistance.
+
+#### `git_tool_auto_submit_errors` (boolean, default: `false`)
+
+When enabled, automatically submits git tool error messages back to the LLM for analysis and suggestions.
+
+#### `git_tool_auto_submit_success` (boolean, default: `false`)
+
+When enabled, automatically submits git tool success messages back to the LLM to continue the workflow.
+
+#### `gitcommit_select_count` (number, default: `100`)
+
+Number of recent commits to show when using the `/gitcommit` slash command. This controls how many commits are available for selection in the interactive commit selector.
 #### `adapter` (string, optional)
 
 The LLM adapter to use for generating commit messages. If not specified, defaults to the adapter configured for CodeCompanion's chat strategy.
@@ -263,7 +482,7 @@ A list of languages that can be used for generating commit messages. When specif
 Example:
 
 ```lua
-languages = { "English", "简体中文", "日本語", "Français", "Español" }
+languages = { "English", "Chinese", "Japanese", "French", "Spanish" }
 ```
 
 #### `exclude_files` (table, optional)

config_example.lua

@@ -0,0 +1,44 @@
+-- CodeCompanion GitCommit Extension Configuration Example
+-- This file demonstrates how to configure the GitCommit extension with git tools
+
+return {
+  -- Basic configuration
+  adapter = "anthropic", -- or "openai", "copilot", etc.
+  model = "claude-3-5-sonnet-20241022",
+
+  -- Languages for commit message generation
+  languages = { "English", "Chinese", "Japanese", "French" },
+
+  -- Files to exclude from git diff (supports glob patterns)
+  exclude_files = {
+    "*.pb.go", -- Protocol buffer files
+    "*.min.js", -- Minified JavaScript
+    "*.min.css", -- Minified CSS
+    "package-lock.json", -- NPM lock files
+    "yarn.lock", -- Yarn lock files
+    "*.log", -- Log files
+    "dist/*", -- Distribution directories
+    "build/*", -- Build directories
+    ".next/*", -- Next.js build
+    "node_modules/*", -- Node modules
+    "vendor/*", -- Vendor directories
+  },
+
+  -- Buffer configuration
+  buffer = {
+    enabled = true,
+    keymap = "<leader>gc",
+    auto_generate = true,
+    auto_generate_delay = 200,
+  },
+
+  -- Enable slash command in chat buffer
+  add_slash_command = true,
+
+  -- Git tool configuration
+  add_git_tool = true, -- Add @git_bot tool to CodeCompanion
+  add_git_commands = true, -- Add :CodeCompanionGit commands
+  git_tool_auto_submit_errors = false, -- Don't auto-submit errors to LLM
+  git_tool_auto_submit_success = false, -- Don't auto-submit success to LLM
+  gitcommit_select_count = 100, -- Number of recent commits for /gitcommit slash command
+}