feat: add .gitignore pattern support for repository analysis

- Implement hybrid .gitignore processing using git check-ignore with pathspec fallback
- Add --respect-gitignore CLI option to both config and generate commands
- Update configuration models to store gitignore preference persistently
- Enhance RepoAnalyzer with gitignore pattern matching and priority logic
- Add comprehensive test suite for gitignore verification including negation patterns
- Update documentation with detailed pattern behavior and processing logic
- Add pathspec dependency for robust gitignore pattern matching

The feature respects .gitignore patterns during file analysis while maintaining proper priority:
1. Git ignore patterns are checked first
2. User CLI exclude patterns override git tracking
3. Default ignore patterns are applied last
4. Include patterns filter the remaining files

Author: ShangHong-CAI

README.md

@@ -108,8 +108,8 @@ codewiki config set \
 # Configure max token settings
 codewiki config set --max-tokens 32768 --max-token-per-module 36369 --max-token-per-leaf-module 16000
 
-# Configure max depth for hierarchical decomposition
-codewiki config set --max-depth 3
+# Configure max depth for hierarchical decomposition and .gitignore support
+codewiki config set --max-depth 3 --respect-gitignore
 
 # Show current configuration
 codewiki config show
@@ -137,16 +137,16 @@ codewiki generate --github-pages
 codewiki generate --verbose
 
 # Full-featured generation
-codewiki generate --create-branch --github-pages --verbose
+codewiki generate --create-branch --github-pages --verbose --respect-gitignore
 ```
 
 ### Customization Options
 
 CodeWiki supports customization for language-specific projects and documentation styles:
 
 ```bash
-# C# project: only analyze .cs files, exclude test directories
-codewiki generate --include "*.cs" --exclude "Tests,Specs,*.test.cs"
+# C# project: only analyze .cs files, exclude test directories, respect .gitignore
+codewiki generate --include "*.cs" --exclude "Tests,Specs,*.test.cs" --respect-gitignore
 
 # Focus on specific modules with architecture-style docs
 codewiki generate --focus "src/core,src/api" --doc-type architecture
@@ -157,7 +157,7 @@ codewiki generate --instructions "Focus on public APIs and include usage example
 
 #### Pattern Behavior (Important!)
 
-- **`--include`**: When specified, **ONLY** these patterns are used (replaces defaults completely)
+- **`--include`**: When specified, **ONLY** these patterns are included from the remaining files (applied after exclusion)
   - Example: `--include "*.cs"` will analyze ONLY `.cs` files
   - If omitted, all supported file types are analyzed
   - Supports glob patterns: `*.py`, `src/**/*.ts`, `*.{js,jsx}`
@@ -170,6 +170,14 @@ codewiki generate --instructions "Focus on public APIs and include usage example
     - Glob patterns: `*.test.js`, `*_test.py`, `*.min.*`
     - Directory patterns: `build/`, `dist/`, `coverage/`
 
+- **`--respect-gitignore`**: Respect `.gitignore` patterns
+  - **Hybrid**: Uses `git check-ignore` for full recursive accuracy, falls back to pathspec if git unavailable
+  - **Processing Logic**:
+    1. **Git Check**: If matched by `.gitignore` → **Excluded**
+    2. **User Exclude**: If matched by CLI `--exclude` → **Excluded** (Overrides Git tracking)
+    3. **Defaults**: If no match above → Check default ignore patterns
+    4. **Inclusion**: Final check against `--include` patterns (if specified)
+
 #### Setting Persistent Defaults
 
 Save your preferred settings as defaults:
@@ -202,6 +210,7 @@ codewiki config agent --clear
 | `--doc-type` | Documentation style | Standalone option | `api`, `architecture`, `user-guide`, `developer` |
 | `--instructions` | Custom agent instructions | Standalone option | Free-form text |
 
+
 ### Token Settings
 
 CodeWiki allows you to configure maximum token limits for LLM calls. This is useful for:

codewiki/cli/adapters/doc_generator.py

@@ -141,6 +141,7 @@ def generate(self) -> DocumentationJob:
                 max_token_per_module=self.config.get('max_token_per_module', 36369),
                 max_token_per_leaf_module=self.config.get('max_token_per_leaf_module', 16000),
                 max_depth=self.config.get('max_depth', 2),
+                respect_gitignore=self.config.get('respect_gitignore', False),
                 agent_instructions=self.config.get('agent_instructions')
             )
 

codewiki/cli/commands/config.py

@@ -83,6 +83,12 @@ def config_group():
     type=int,
     help="Maximum depth for hierarchical decomposition (default: 2)"
 )
+@click.option(
+    '--respect-gitignore',
+    is_flag=True,
+    default=None,
+    help='Respect .gitignore patterns during analysis'
+)
 def config_set(
     api_key: Optional[str],
     base_url: Optional[str],
@@ -92,7 +98,8 @@ def config_set(
     max_tokens: Optional[int],
     max_token_per_module: Optional[int],
     max_token_per_leaf_module: Optional[int],
-    max_depth: Optional[int]
+    max_depth: Optional[int],
+    respect_gitignore: Optional[bool]
 ):
     """
     Set configuration values for CodeWiki.
@@ -127,7 +134,7 @@ def config_set(
     """
     try:
         # Check if at least one option is provided
-        if not any([api_key, base_url, main_model, cluster_model, fallback_model, max_tokens, max_token_per_module, max_token_per_leaf_module, max_depth]):
+        if not any([api_key, base_url, main_model, cluster_model, fallback_model, max_tokens, max_token_per_module, max_token_per_leaf_module, max_depth, respect_gitignore is not None]):
             click.echo("No options provided. Use --help for usage information.")
             sys.exit(EXIT_CONFIG_ERROR)
 
@@ -169,6 +176,9 @@ def config_set(
                 raise ConfigurationError("max_depth must be a positive integer")
             validated_data['max_depth'] = max_depth
 
+        if respect_gitignore is not None:
+            validated_data['respect_gitignore'] = respect_gitignore
+        
         # Create config manager and save
         manager = ConfigManager()
         manager.load()  # Load existing config if present
@@ -182,7 +192,8 @@ def config_set(
             max_tokens=validated_data.get('max_tokens'),
             max_token_per_module=validated_data.get('max_token_per_module'),
             max_token_per_leaf_module=validated_data.get('max_token_per_leaf_module'),
-            max_depth=validated_data.get('max_depth')
+            max_depth=validated_data.get('max_depth'),
+            respect_gitignore=validated_data.get('respect_gitignore')
         )
 
         # Display success messages
@@ -231,6 +242,9 @@ def config_set(
         if max_depth:
             click.secho(f"✓ Max depth: {max_depth}", fg="green")
 
+        if respect_gitignore is not None:
+            click.secho(f"✓ Respect gitignore: {respect_gitignore}", fg="green")
+        
         click.echo("\n" + click.style("Configuration updated successfully.", fg="green", bold=True))
 
     except ConfigurationError as e:
@@ -291,6 +305,7 @@ def config_show(output_json: bool):
                 "max_token_per_module": config.max_token_per_module if config else 36369,
                 "max_token_per_leaf_module": config.max_token_per_leaf_module if config else 16000,
                 "max_depth": config.max_depth if config else 2,
+                "respect_gitignore": config.respect_gitignore if config else False,
                 "agent_instructions": config.agent_instructions.to_dict() if config and config.agent_instructions else {},
                 "config_file": str(manager.config_file_path)
             }
@@ -335,7 +350,7 @@ def config_show(output_json: bool):
             click.secho("Decomposition Settings", fg="cyan", bold=True)
             if config:
                 click.echo(f"  Max Depth:               {config.max_depth}")
-            
+                click.echo(f"  Respect Gitignore:       {config.respect_gitignore}")
             click.echo()
             click.secho("Agent Instructions", fg="cyan", bold=True)
             if config and config.agent_instructions and not config.agent_instructions.is_empty():

codewiki/cli/commands/generate.py

@@ -126,6 +126,12 @@ def parse_patterns(patterns_str: str) -> List[str]:
     default=None,
     help="Maximum depth for hierarchical decomposition (overrides config)",
 )
+@click.option(
+    '--respect-gitignore',
+    is_flag=True,
+    default=None,
+    help='Respect .gitignore patterns during analysis'
+)
 @click.pass_context
 def generate_command(
     ctx,
@@ -142,7 +148,8 @@ def generate_command(
     max_tokens: Optional[int],
     max_token_per_module: Optional[int],
     max_token_per_leaf_module: Optional[int],
-    max_depth: Optional[int]
+    max_depth: Optional[int],
+    respect_gitignore: Optional[bool]
 ):
     """
     Generate comprehensive documentation for a code repository.
@@ -290,7 +297,8 @@ def generate_command(
             create_branch=create_branch,
             github_pages=github_pages,
             no_cache=no_cache,
-            custom_output=output if output != "docs" else None
+            custom_output=output if output != "docs" else None,
+            respect_gitignore=respect_gitignore if respect_gitignore is not None else config.respect_gitignore
         )
 
         # Create runtime agent instructions from CLI options
@@ -322,10 +330,12 @@ def generate_command(
             effective_max_token_per_module = max_token_per_module if max_token_per_module is not None else config.max_token_per_module
             effective_max_token_per_leaf = max_token_per_leaf_module if max_token_per_leaf_module is not None else config.max_token_per_leaf_module
             effective_max_depth = max_depth if max_depth is not None else config.max_depth
+            effective_respect_gitignore = respect_gitignore if respect_gitignore is not None else config.respect_gitignore
             logger.debug(f"Max tokens: {effective_max_tokens}")
             logger.debug(f"Max token/module: {effective_max_token_per_module}")
             logger.debug(f"Max token/leaf module: {effective_max_token_per_leaf}")
             logger.debug(f"Max depth: {effective_max_depth}")
+            logger.debug(f"Respect gitignore: {effective_respect_gitignore}")
 
         # Get agent instructions (merge runtime with persistent)
         agent_instructions_dict = None
@@ -359,6 +369,8 @@ def generate_command(
                 'max_token_per_leaf_module': max_token_per_leaf_module if max_token_per_leaf_module is not None else config.max_token_per_leaf_module,
                 # Max depth setting (runtime override takes precedence)
                 'max_depth': max_depth if max_depth is not None else config.max_depth,
+                # Gitignore setting (runtime override takes precedence)
+                'respect_gitignore': respect_gitignore if respect_gitignore is not None else config.respect_gitignore,
             },
             verbose=verbose,
             generate_html=github_pages

codewiki/cli/config_manager.py

@@ -92,7 +92,8 @@ def save(
         max_tokens: Optional[int] = None,
         max_token_per_module: Optional[int] = None,
         max_token_per_leaf_module: Optional[int] = None,
-        max_depth: Optional[int] = None
+        max_depth: Optional[int] = None,
+        respect_gitignore: Optional[bool] = None,
     ):
         """
         Save configuration to file and keyring.
@@ -108,6 +109,7 @@ def save(
             max_token_per_module: Maximum tokens per module for clustering
             max_token_per_leaf_module: Maximum tokens per leaf module
             max_depth: Maximum depth for hierarchical decomposition
+            respect_gitignore: Respect .gitignore patterns during analysis
         """
         # Ensure config directory exists
         try:
@@ -149,7 +151,9 @@ def save(
             self._config.max_token_per_leaf_module = max_token_per_leaf_module
         if max_depth is not None:
             self._config.max_depth = max_depth
-        
+        if respect_gitignore is not None:
+            self._config.respect_gitignore = respect_gitignore
+
         # Validate configuration (only if base fields are set)
         if self._config.base_url and self._config.main_model and self._config.cluster_model:
             self._config.validate()

codewiki/cli/models/config.py

@@ -118,6 +118,7 @@ class Configuration:
         max_token_per_leaf_module: Maximum tokens per leaf module (default: 16000)
         max_depth: Maximum depth for hierarchical decomposition (default: 2)
         agent_instructions: Custom agent instructions for documentation generation
+        respect_gitignore: Respect .gitignore patterns during analysis
     """
     base_url: str
     main_model: str
@@ -129,6 +130,7 @@ class Configuration:
     max_token_per_leaf_module: int = 16000
     max_depth: int = 2
     agent_instructions: AgentInstructions = field(default_factory=AgentInstructions)
+    respect_gitignore: bool = False
 
     def validate(self):
         """
@@ -153,6 +155,7 @@ def to_dict(self) -> dict:
             'max_token_per_module': self.max_token_per_module,
             'max_token_per_leaf_module': self.max_token_per_leaf_module,
             'max_depth': self.max_depth,
+            'respect_gitignore': self.respect_gitignore,
         }
         if self.agent_instructions and not self.agent_instructions.is_empty():
             result['agent_instructions'] = self.agent_instructions.to_dict()
@@ -184,6 +187,7 @@ def from_dict(cls, data: dict) -> 'Configuration':
             max_token_per_leaf_module=data.get('max_token_per_leaf_module', 16000),
             max_depth=data.get('max_depth', 2),
             agent_instructions=agent_instructions,
+            respect_gitignore=data.get('respect_gitignore', False),
         )
 
     def is_complete(self) -> bool:
@@ -237,6 +241,7 @@ def to_backend_config(self, repo_path: str, output_dir: str, api_key: str, runti
             max_token_per_module=self.max_token_per_module,
             max_token_per_leaf_module=self.max_token_per_leaf_module,
             max_depth=self.max_depth,
-            agent_instructions=final_instructions.to_dict() if final_instructions else None
+            agent_instructions=final_instructions.to_dict() if final_instructions else None,
+            respect_gitignore=self.respect_gitignore,
         )
 

codewiki/cli/models/job.py

@@ -25,6 +25,7 @@ class GenerationOptions:
     github_pages: bool = False
     no_cache: bool = False
     custom_output: Optional[str] = None
+    respect_gitignore: Optional[bool] = None
 
 
 @dataclass