Strengthen clang-format with Git validation and comprehensive documentation

- Add Git repo validation in CLI
- Add comprehensive English/Chinese comments
- Improve error handling with detailed messages
- Update README with detailed usage examples and important notes
- Update dependencies in go.mod and go.sum

Author: yyle88

.github/workflows/release.yml

@@ -27,7 +27,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        go: [ "1.22.x", "1.23.x", "1.24.x", "stable" ]
+        go: [ "1.22.x", "1.23.x", "1.24.x", "1.25.x", "stable" ]
     steps:
       - uses: actions/checkout@v4
 

README.md

@@ -1,13 +1,13 @@
 [![GitHub Workflow Status (branch)](https://img.shields.io/github/actions/workflow/status/go-xlan/clang-format/release.yml?branch=main&label=BUILD)](https://github.com/go-xlan/clang-format/actions/workflows/release.yml?query=branch%3Amain)
 [![GoDoc](https://pkg.go.dev/badge/github.com/go-xlan/clang-format)](https://pkg.go.dev/github.com/go-xlan/clang-format)
 [![Coverage Status](https://img.shields.io/coveralls/github/go-xlan/clang-format/main.svg)](https://coveralls.io/github/go-xlan/clang-format?branch=main)
-[![Supported Go Versions](https://img.shields.io/badge/Go-1.22-lightgrey.svg)](https://go.dev/)
+[![Supported Go Versions](https://img.shields.io/badge/Go-1.22--1.25-lightgrey.svg)](https://github.com/go-xlan/clang-format)
 [![GitHub Release](https://img.shields.io/github/release/go-xlan/clang-format.svg)](https://github.com/go-xlan/clang-format/releases)
 [![Go Report Card](https://goreportcard.com/badge/github.com/go-xlan/clang-format)](https://goreportcard.com/report/github.com/go-xlan/clang-format)
 
 # clang-format
 
-Go package for clang-format with Protocol Buffers and C/C++ batch formatting capabilities.
+Go package supporting clang-format with Protocol Buffers and C/C++ batch formatting capabilities.
 
 ---
 
@@ -17,12 +17,12 @@ Go package for clang-format with Protocol Buffers and C/C++ batch formatting cap
 [中文说明](README.zh.md)
 <!-- TEMPLATE (EN) END: LANGUAGE NAVIGATION -->
 
-## Key Features
+## Main Features
 
-🎯 **Intelligent Proto Formatting**: Smart clang-format package with Google style defaults  
-⚡ **Two Operation Modes**: Both preview (DryRun) and in-place formatting support  
-🔄 **Batch Processing**: Recursive project-wide .proto file formatting  
-🌍 **Configurable Styles**: Customizable formatting styles with JSON configuration  
+🎯 **Smart Proto Formatting**: Intelligent clang-format package with Google style defaults
+⚡ **Two Operation Modes**: Both preview (DryRun) and in-place formatting support
+🔄 **Batch Processing**: Project-wide .proto file formatting using recursive approach
+🌍 **Configurable Styles**: Customizable formatting with JSON configuration
 📋 **Comprehensive Logging**: Detailed operation logs with structured output
 
 ## Installation
@@ -50,16 +50,22 @@ brew install clang-format
 # Ubuntu/Debian
 sudo apt-get install clang-format
 
-# Verify installation
+# Check setup
 clang-format --version
 ```
 
 ## Quick Start
 
 ### Command Line Usage
 
+The `clang-format-batch` command formats files in Git projects. It requires:
+- Running from within a Git repo
+- Valid file extensions specified via `--extensions` flag
+
+**Basic Examples:**
+
 ```bash
-# Format all .proto files in current project
+# Format .proto files in current project
 clang-format-batch --extensions=".proto"
 
 # Format C/C++ files
@@ -72,9 +78,23 @@ clang-format-batch --extensions=".proto,.c,.cpp,.h"
 clang-format-batch -e ".proto,.cc,.hh"
 ```
 
-## Library Usage
+**Supported File Extensions:**
+- `.proto` - Protocol Buffer files
+- `.c`, `.cpp`, `.cxx`, `.cc` - C/C++ source files
+- `.h`, `.hpp`, `.hxx` - C/C++ headers
+
+**Important Notes:**
+- Command must be run from within a Git repo
+- Command processes matching files in project using recursive approach
+- Hidden files and paths (starting with `.`) are skipped
+- Source files are modified in-place (use version management!)
+
+
+## Package Usage
 
-### Protocol Buffers Formatting (Primary Use Case)
+### Protocol Buffers Formatting (Main Use Case)
+
+The `protoformat` package provides high-end API when formatting Protocol Buffer files:
 
 ```go
 package main
@@ -88,72 +108,162 @@ import (
 )
 
 func main() {
+    // Create execution configuration
     execConfig := osexec.NewExecConfig()
+
+    // Create default Proto style (Google-based, 2-space indent)
     style := protoformat.NewStyle()
-    
+
     // Preview .proto file formatting (DryRun)
+    // Returns formatted content without modifying the file
     output := rese.V1(protoformat.DryRun(execConfig, "example.proto", style))
     fmt.Println(string(output))
-    
-    // Format single .proto file
-	rese.V1(protoformat.Format(execConfig, "example.proto", style))
-    
+
+    // Format single .proto file in-place
+    // Modifies the file with formatted content
+    output = rese.V1(protoformat.Format(execConfig, "example.proto", style))
+
     // Format entire project (batch processing)
+    // Formats .proto files in DIR using recursive approach
     must.Done(protoformat.FormatProject(execConfig, "./proto-project", style))
 }
 ```
 
+**Main Points:**
+- `DryRun()` - Preview changes without modifying files (safe to use)
+- `Format()` - Commit changes to single file (modifies file in-place)
+- `FormatProject()` - Batch process .proto files in DIR
+- Uses Google Proto style as default (2-space indentation, no width limit)
+
+
 ### Custom Style Configuration
 
+You can customize formatting to match the project's coding standards:
+
 ```go
+// Create custom style based on LLVM conventions
 customStyle := &clangformat.Style{
-    BasedOnStyle:                "LLVM",
-    IndentWidth:                 4,
-    ColumnLimit:                 80,
-    AlignConsecutiveAssignments: true,
+    BasedOnStyle:                "LLVM",        // Base style template
+    IndentWidth:                 4,             // 4 spaces at each indent
+    ColumnLimit:                 80,            // Maximum line width
+    AlignConsecutiveAssignments: true,         // Align = signs in columns
 }
 
+// Use custom style when formatting
 output := rese.V1(protoformat.DryRun(execConfig, "example.proto", customStyle))
 ```
 
-### General File Formatting (C/C++ Support)
+**Available Base Styles:**
+- `"Google"` - Google C++ Style Guide (default)
+- `"LLVM"` - LLVM coding standards
+- `"Chromium"` - Chromium project style
+- `"Mozilla"` - Mozilla style guide
+- `"WebKit"` - WebKit style guide
+
+**Common Style Options:**
+- `IndentWidth` - Count of spaces when indenting (common: 2 and 4)
+- `ColumnLimit` - Maximum line width (0 = no limit)
+- `AlignConsecutiveAssignments` - Align assignment operators in columns
+
+
+### Wide File Formatting (C/C++ Support)
+
+The `clangformat` package provides foundation API when formatting clang-format supported files:
 
 ```go
 import "github.com/go-xlan/clang-format/clangformat"
 
-// Format C/C++ files
+// Create execution config and style
+execConfig := osexec.NewExecConfig()
+style := clangformat.NewStyle()
+
+// Preview C++ file formatting
 output := rese.V1(clangformat.DryRun(execConfig, "example.cpp", style))
-must.Done(clangformat.Format(execConfig, "example.cpp", style))
+
+// Format C++ file in-place
+output = rese.V1(clangformat.Format(execConfig, "example.cpp", style))
+
+// Batch format .cpp files in project
+must.Done(clangformat.FormatProject(execConfig, "./src", ".cpp", style))
+```
+
+**Note:** Unlike `protoformat.FormatProject()`, the `clangformat.FormatProject()` needs
+a single file extension. To format multiple kinds, make multiple invocations:
+
+```go
+// Format both .cpp and .h files
+must.Done(clangformat.FormatProject(execConfig, "./src", ".cpp", style))
+must.Done(clangformat.FormatProject(execConfig, "./src", ".h", style))
 ```
 
+
 ## API Reference
 
 ### clangformat Package
 
-- `NewStyle()` - Creates default Google-based style configuration
-- `DryRun(config, path, style)` - Preview formatting without file modification
-- `Format(config, path, style)` - Use formatting on file
+**Core Functions:**
+
+- `NewStyle() *Style`
+  - Creates default Google-based style configuration
+  - Returns style with 2-space indentation and no width limit
+  - Safe to change the data structure when customizing
+
+- `DryRun(config *osexec.ExecConfig, path string, style *Style) ([]byte, error)`
+  - Preview formatting without file modification
+  - Returns formatted content as byte sequence
+  - Source file stays unchanged
+  - Use this when validating changes before commit
+
+- `Format(config *osexec.ExecConfig, path string, style *Style) ([]byte, error)`
+  - Commit formatting changes to file in-place
+  - Modifies the file on disk
+  - Returns zero-length byte sequence on success (clang-format action)
+  - **Warning:** Source file is overwritten
+
+- `FormatProject(config *osexec.ExecConfig, projectPath string, extension string, style *Style) error`
+  - Batch format files with specific extension in project
+  - Walks through DIR tree using recursive approach
+  - Skips hidden files and paths (starting with `.`)
+  - Processes one extension at a time
 
 ### protoformat Package
 
-- `NewStyle()` - Creates Protocol Buffers optimized style configuration
-- `DryRun(config, path, style)` - Preview .proto file formatting
-- `Format(config, path, style)` - Format single .proto file
-- `FormatProject(config, path, style)` - Batch format all .proto files in project
+**Core Functions:**
+
+- `NewStyle() *clangformat.Style`
+  - Creates Protocol Buffers optimized style configuration
+  - Same as `clangformat.NewStyle()` but provides Proto-specific context
+  - Returns Google-based style tuned when formatting .proto files
+
+- `DryRun(config *osexec.ExecConfig, protoPath string, style *clangformat.Style) ([]byte, error)`
+  - Preview .proto file formatting without modification
+  - Wraps `clangformat.DryRun()` with proto-specific context
+  - Returns formatted Proto content
+
+- `Format(config *osexec.ExecConfig, protoPath string, style *clangformat.Style) ([]byte, error)`
+  - Commit formatting changes to single .proto file in-place
+  - Wraps `clangformat.Format()` with proto-specific context
+  - Modifies file on disk
+
+- `FormatProject(config *osexec.ExecConfig, projectPath string, style *clangformat.Style) error`
+  - Batch format .proto files in project
+  - Targets `.proto` extension as default
+  - Shows green success message on completion
+  - Provides detailed logging when processing each file
 
 ### Style Configuration
 
 ```go
 type Style struct {
     BasedOnStyle                string // "Google", "LLVM", "Chromium", etc.
-    IndentWidth                 int    // Count of spaces for indentation
-    ColumnLimit                 int    // Maximum line length (0 = no limit)
+    IndentWidth                 int    // Count of spaces when indenting
+    ColumnLimit                 int    // Maximum line width (0 = no limit)
     AlignConsecutiveAssignments bool   // Align assignments at assignment signs
 }
 ```
 
 <!-- TEMPLATE (EN) BEGIN: STANDARD PROJECT FOOTER -->
-<!-- VERSION 2025-09-06 04:53:24.895249 +0000 UTC -->
+<!-- VERSION 2025-09-26 07:39:27.188023 +0000 UTC -->
 
 ## 📄 License
 
@@ -165,7 +275,7 @@ MIT License. See [LICENSE](LICENSE).
 
 Contributions are welcome! Report bugs, suggest features, and contribute code:
 
-- 🐛 **Found a bug?** Open an issue on GitHub with reproduction steps
+- 🐛 **Found a mistake?** Open an issue on GitHub with reproduction steps
 - 💡 **Have a feature idea?** Create an issue to discuss the suggestion
 - 📖 **Documentation confusing?** Report it so we can improve
 - 🚀 **Need new features?** Share the use cases to help us understand requirements
@@ -191,7 +301,7 @@ New code contributions, follow this process:
 8. **Stage**: Stage changes (`git add .`)
 9. **Commit**: Commit changes (`git commit -m "Add feature xxx"`) ensuring backward compatible code
 10. **Push**: Push to the branch (`git push origin feature/xxx`).
-11. **PR**: Open a pull request on GitHub (on the GitHub webpage) with detailed description.
+11. **PR**: Open a merge request on GitHub (on the GitHub webpage) with detailed description.
 
 Please ensure tests pass and include relevant documentation updates.
 
@@ -208,7 +318,7 @@ Welcome to contribute to this project via submitting merge requests and reportin
 - 📝 **Write tech blogs** about development tools and workflows - we provide content writing support
 - 🌟 **Join the ecosystem** - committed to supporting open source and the (golang) development scene
 
-**Have Fun Coding with this package!** 🎉
+**Have Fun Coding with this package!** 🎉🎉🎉
 
 <!-- TEMPLATE (EN) END: STANDARD PROJECT FOOTER -->