gitflow-analytics 3.11.1__tar.gz → 3.12.5__tar.gz

{gitflow_analytics-3.11.1 → gitflow_analytics-3.12.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitflow-analytics
-Version: 3.11.1
+Version: 3.12.5
 Summary: Analyze Git repositories for developer productivity insights
 Author-email: Bob Matyas <bobmatnyc@gmail.com>
 License: MIT
@@ -235,6 +235,79 @@ gitflow-analytics -c config.yaml --weeks 8 --output ./reports
 
 > 💡 **Need more configuration options?** See the [Complete Configuration Guide](docs/guides/configuration.md) for advanced features, integrations, and customization.
 
+## 🎯 Excluding Merge Commits from Metrics
+
+GitFlow Analytics can exclude merge commits from filtered line count calculations, following DORA metrics best practices.
+
+### Why Exclude Merge Commits?
+
+Merge commits represent repository management, not original development work:
+- **Average merge commit**: 236.6 filtered lines vs 30.8 for regular commits (7.7x higher)
+- Merge commits can **skew productivity metrics** and velocity calculations
+- **DORA metrics best practice**: Focus on original development work, not repository management
+
+### Configuration
+
+Add this setting to your analysis configuration:
+
+```yaml
+analysis:
+  # Exclude merge commits from filtered line counts (DORA metrics best practice)
+  exclude_merge_commits: true  # Default: false
+```
+
+### Impact Example
+
+Real metrics from EWTN dataset analysis:
+
+| Metric | With Merge Commits | Without Merge Commits | Change |
+|--------|-------------------|----------------------|--------|
+| **Total Filtered Lines** | 138,730 | 54,808 | -60% |
+| **Merge Commits** | 355 commits | 355 commits | (excluded from line counts) |
+| **Regular Commits** | 1,426 commits | 1,426 commits | (unchanged) |
+
+### What Gets Excluded?
+
+When `exclude_merge_commits: true`:
+
+✅ **Filtered Stats**: Merge commits (2+ parents) have `filtered_insertions = 0` and `filtered_deletions = 0`
+✅ **Raw Stats**: Always preserved for all commits (accurate commit counts)
+✅ **Reports**: Line count metrics reflect only original development work
+
+❌ **Not affected**: Commit counts, developer activity tracking, ticket references
+
+### When to Use
+
+**✅ Enable when:**
+- You want DORA-compliant metrics for productivity tracking
+- Your workflow uses merge commits for pull requests
+- You need accurate developer velocity without repository overhead
+- You're comparing metrics across teams with different merge strategies
+
+**❌ Disable when:**
+- You want to track all repository activity including management overhead
+- Merge commits represent significant manual conflict resolution in your workflow
+- You're analyzing repositories without merge-heavy workflows
+- You need to measure total repository churn including merges
+
+### Example Configuration
+
+```yaml
+# Full configuration example
+analysis:
+  weeks_back: 8
+  include_weekends: true
+
+  # DORA-compliant metrics: exclude merge commits
+  exclude_merge_commits: true
+
+  # Analyze ALL branches to capture feature branch work
+  branch_patterns:
+    - "*"  # Include all branches (feature, develop, hotfix, etc.)
+```
+
+> 💡 **Pro Tip**: Combine `exclude_merge_commits: true` with `branch_patterns: ["*"]` to analyze all development work without merge overhead.
+
 ## 📊 Generated Reports
 
 GitFlow Analytics generates comprehensive reports for different audiences:

{gitflow_analytics-3.11.1 → gitflow_analytics-3.12.5}/README.md

@@ -177,6 +177,79 @@ gitflow-analytics -c config.yaml --weeks 8 --output ./reports
 
 > 💡 **Need more configuration options?** See the [Complete Configuration Guide](docs/guides/configuration.md) for advanced features, integrations, and customization.
 
+## 🎯 Excluding Merge Commits from Metrics
+
+GitFlow Analytics can exclude merge commits from filtered line count calculations, following DORA metrics best practices.
+
+### Why Exclude Merge Commits?
+
+Merge commits represent repository management, not original development work:
+- **Average merge commit**: 236.6 filtered lines vs 30.8 for regular commits (7.7x higher)
+- Merge commits can **skew productivity metrics** and velocity calculations
+- **DORA metrics best practice**: Focus on original development work, not repository management
+
+### Configuration
+
+Add this setting to your analysis configuration:
+
+```yaml
+analysis:
+  # Exclude merge commits from filtered line counts (DORA metrics best practice)
+  exclude_merge_commits: true  # Default: false
+```
+
+### Impact Example
+
+Real metrics from EWTN dataset analysis:
+
+| Metric | With Merge Commits | Without Merge Commits | Change |
+|--------|-------------------|----------------------|--------|
+| **Total Filtered Lines** | 138,730 | 54,808 | -60% |
+| **Merge Commits** | 355 commits | 355 commits | (excluded from line counts) |
+| **Regular Commits** | 1,426 commits | 1,426 commits | (unchanged) |
+
+### What Gets Excluded?
+
+When `exclude_merge_commits: true`:
+
+✅ **Filtered Stats**: Merge commits (2+ parents) have `filtered_insertions = 0` and `filtered_deletions = 0`
+✅ **Raw Stats**: Always preserved for all commits (accurate commit counts)
+✅ **Reports**: Line count metrics reflect only original development work
+
+❌ **Not affected**: Commit counts, developer activity tracking, ticket references
+
+### When to Use
+
+**✅ Enable when:**
+- You want DORA-compliant metrics for productivity tracking
+- Your workflow uses merge commits for pull requests
+- You need accurate developer velocity without repository overhead
+- You're comparing metrics across teams with different merge strategies
+
+**❌ Disable when:**
+- You want to track all repository activity including management overhead
+- Merge commits represent significant manual conflict resolution in your workflow
+- You're analyzing repositories without merge-heavy workflows
+- You need to measure total repository churn including merges
+
+### Example Configuration
+
+```yaml
+# Full configuration example
+analysis:
+  weeks_back: 8
+  include_weekends: true
+
+  # DORA-compliant metrics: exclude merge commits
+  exclude_merge_commits: true
+
+  # Analyze ALL branches to capture feature branch work
+  branch_patterns:
+    - "*"  # Include all branches (feature, develop, hotfix, etc.)
+```
+
+> 💡 **Pro Tip**: Combine `exclude_merge_commits: true` with `branch_patterns: ["*"]` to analyze all development work without merge overhead.
+
 ## 📊 Generated Reports
 
 GitFlow Analytics generates comprehensive reports for different audiences:

{gitflow_analytics-3.11.1 → gitflow_analytics-3.12.5}/src/gitflow_analytics/_version.py

@@ -1,4 +1,4 @@
 """Version information for gitflow-analytics."""
 
-__version__ = "3.11.1"
+__version__ = "3.12.5"
 __version_info__ = tuple(int(x) for x in __version__.split("."))

{gitflow_analytics-3.11.1 → gitflow_analytics-3.12.5}/src/gitflow_analytics/cli.py

@@ -967,6 +967,7 @@ def analyze(
                 branch_mapping_rules=cfg.analysis.branch_mapping_rules,
                 allowed_ticket_platforms=cfg.get_effective_ticket_platforms(),
                 exclude_paths=cfg.analysis.exclude_paths,
+                exclude_merge_commits=cfg.analysis.exclude_merge_commits,
             )
 
             # Get commits from all repositories
@@ -1162,6 +1163,7 @@ def analyze(
             ml_categorization_config=ml_config,
             llm_config=llm_config,
             branch_analysis_config=branch_analysis_config,
+            exclude_merge_commits=cfg.analysis.exclude_merge_commits,
         )
         orchestrator = IntegrationOrchestrator(cfg, cache)
 
@@ -1289,6 +1291,7 @@ def analyze(
                 "enable_qualitative": enable_qualitative,
                 "enable_pm": enable_pm,
                 "pm_platforms": list(pm_platform) if pm_platform else [],
+                "exclude_merge_commits": cfg.analysis.exclude_merge_commits,
             },
         )
 
@@ -1386,6 +1389,7 @@ def analyze(
                         cfg.analysis, "ticket_platforms", ["jira", "github", "clickup", "linear"]
                     ),
                     exclude_paths=getattr(cfg.analysis, "exclude_paths", None),
+                    exclude_merge_commits=cfg.analysis.exclude_merge_commits,
                 )
 
                 # Initialize integrations for ticket fetching
@@ -1780,6 +1784,7 @@ def analyze(
                             ["jira", "github", "clickup", "linear"],
                         ),
                         exclude_paths=getattr(cfg.analysis, "exclude_paths", None),
+                        exclude_merge_commits=cfg.analysis.exclude_merge_commits,
                     )
 
                     # Initialize integrations for ticket fetching
@@ -4321,6 +4326,7 @@ def fetch(
             branch_mapping_rules=getattr(cfg.analysis, "branch_mapping_rules", {}),
             allowed_ticket_platforms=cfg.get_effective_ticket_platforms(),
             exclude_paths=getattr(cfg.analysis, "exclude_paths", None),
+            exclude_merge_commits=cfg.analysis.exclude_merge_commits,
         )
 
         # Initialize integrations for ticket fetching
@@ -5015,6 +5021,7 @@ def identities(config: Path, weeks: int, apply: bool) -> None:
             ml_categorization_config=ml_config,
             llm_config=llm_config,
             branch_analysis_config=branch_analysis_config,
+            exclude_merge_commits=cfg.analysis.exclude_merge_commits,
         )
 
         click.echo("🔍 Analyzing repositories for developer identities...")
@@ -5252,6 +5259,7 @@ def aliases_command(
             ml_categorization_config=ml_config,
             llm_config=llm_config,
             branch_analysis_config=branch_analysis_config,
+            exclude_merge_commits=cfg.analysis.exclude_merge_commits,
         )
 
         all_commits = []

{gitflow_analytics-3.11.1 → gitflow_analytics-3.12.5}/src/gitflow_analytics/config/loader.py

@@ -593,6 +593,7 @@ class ConfigLoader:
             ),
             exclude_message_patterns=analysis_data.get("exclude", {}).get("message_patterns", []),
             exclude_paths=exclude_paths,
+            exclude_merge_commits=analysis_data.get("exclude_merge_commits", False),
             similarity_threshold=analysis_data.get("identity", {}).get(
                 "similarity_threshold", 0.85
             ),

{gitflow_analytics-3.11.1 → gitflow_analytics-3.12.5}/src/gitflow_analytics/config/schema.py

@@ -299,6 +299,7 @@ class AnalysisConfig:
     exclude_authors: list[str] = field(default_factory=list)
     exclude_message_patterns: list[str] = field(default_factory=list)
     exclude_paths: list[str] = field(default_factory=list)
+    exclude_merge_commits: bool = False  # Exclude merge commits from filtered line counts
     similarity_threshold: float = 0.85
     manual_identity_mappings: list[dict[str, Any]] = field(default_factory=list)
     aliases_file: Optional[Path] = None  # Path to shared aliases.yaml file

{gitflow_analytics-3.11.1 → gitflow_analytics-3.12.5}/src/gitflow_analytics/core/analyzer.py

@@ -14,6 +14,8 @@ from git import Repo
 
 from ..extractors.story_points import StoryPointExtractor
 from ..extractors.tickets import TicketExtractor
+from ..types import FilteredCommitStats
+from ..utils.commit_utils import is_merge_commit
 from .branch_mapper import BranchToProjectMapper
 from .cache import GitAnalysisCache
 from .progress import get_progress_service
@@ -45,6 +47,7 @@ class GitAnalyzer:
         llm_config: Optional[dict[str, Any]] = None,
         classification_config: Optional[dict[str, Any]] = None,
         branch_analysis_config: Optional[dict[str, Any]] = None,
+        exclude_merge_commits: bool = False,
     ):
         """Initialize analyzer with cache and optional ML categorization and commit classification.
 
@@ -59,9 +62,11 @@ class GitAnalyzer:
             llm_config: Configuration for LLM-based commit classification
             classification_config: Configuration for commit classification
             branch_analysis_config: Configuration for branch analysis optimization
+            exclude_merge_commits: Exclude merge commits from filtered line count calculations
         """
         self.cache = cache
         self.batch_size = batch_size
+        self.exclude_merge_commits = exclude_merge_commits
         self.story_point_extractor = StoryPointExtractor(patterns=story_point_patterns)
 
         # Initialize ticket extractor (ML or standard based on config and availability)
@@ -1149,7 +1154,11 @@ class GitAnalyzer:
                 return dir_name in path.parts
             else:
                 # File pattern like *.min.js
-                return fnmatch.fnmatch(path.name, suffix_pattern)
+                # Check both filename AND full path to handle patterns like **/pnpm-lock.yaml
+                # matching root-level files (e.g., pnpm-lock.yaml)
+                return fnmatch.fnmatch(path.name, suffix_pattern) or fnmatch.fnmatch(
+                    filepath, suffix_pattern
+                )
 
         elif pattern.endswith("/**"):
             # Pattern like vendor/** or docs/build/** - matches files inside directory at root level
@@ -1224,9 +1233,22 @@ class GitAnalyzer:
 
         return False
 
-    def _calculate_filtered_stats(self, commit: git.Commit) -> dict[str, int]:
-        """Calculate commit statistics excluding boilerplate/generated files using git diff --numstat."""
-        filtered_stats = {"files": 0, "insertions": 0, "deletions": 0}
+    def _calculate_filtered_stats(self, commit: git.Commit) -> FilteredCommitStats:
+        """Calculate commit statistics excluding boilerplate/generated files using git diff --numstat.
+
+        When exclude_merge_commits is enabled, merge commits (commits with 2+ parents) will have
+        their filtered line counts set to 0 to exclude them from productivity metrics.
+        """
+        filtered_stats: FilteredCommitStats = {"files": 0, "insertions": 0, "deletions": 0}
+
+        # Check if this is a merge commit and we should exclude it from filtered counts
+        is_merge = is_merge_commit(commit)
+        if self.exclude_merge_commits and is_merge:
+            logger.debug(
+                f"Excluding merge commit {commit.hexsha[:8]} from filtered line counts "
+                f"(has {len(commit.parents)} parents)"
+            )
+            return filtered_stats  # Return zeros for merge commits
 
         # For initial commits or commits without parents
         parent = commit.parents[0] if commit.parents else None

{gitflow_analytics-3.11.1 → gitflow_analytics-3.12.5}/src/gitflow_analytics/core/data_fetcher.py

@@ -15,6 +15,7 @@ from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Any, Optional
 
+import git
 from sqlalchemy import func
 from sqlalchemy.orm import Session
 
@@ -28,6 +29,8 @@ from ..models.database import (
     DailyCommitBatch,
     DetailedTicketData,
 )
+from ..types import CommitStats
+from ..utils.commit_utils import is_merge_commit
 from .branch_mapper import BranchToProjectMapper
 from .cache import GitAnalysisCache
 from .git_timeout_wrapper import GitOperationTimeout, GitTimeoutWrapper, HeartbeatLogger
@@ -60,6 +63,7 @@ class GitDataFetcher:
         allowed_ticket_platforms: Optional[list[str]] = None,
         exclude_paths: Optional[list[str]] = None,
         skip_remote_fetch: bool = False,
+        exclude_merge_commits: bool = False,
     ) -> None:
         """Initialize the data fetcher.
 
@@ -69,9 +73,11 @@ class GitDataFetcher:
             allowed_ticket_platforms: List of allowed ticket platforms
             exclude_paths: List of file paths to exclude from analysis
             skip_remote_fetch: If True, skip git fetch/pull operations
+            exclude_merge_commits: Exclude merge commits from filtered line count calculations
         """
         self.cache = cache
         self.skip_remote_fetch = skip_remote_fetch
+        self.exclude_merge_commits = exclude_merge_commits
         self.repository_status = {}  # Track status of each repository
         # CRITICAL FIX: Use the same database instance as the cache to avoid session conflicts
         self.database = cache.db
@@ -646,7 +652,7 @@ class GitDataFetcher:
         return daily_commits
 
     def _extract_commit_data(
-        self, commit: Any, branch_name: str, project_key: str, repo_path: Path
+        self, commit: git.Commit, branch_name: str, project_key: str, repo_path: Path
     ) -> Optional[dict[str, Any]]:
         """Extract comprehensive data from a Git commit.
 
@@ -1792,13 +1798,16 @@ class GitDataFetcher:
         finally:
             session.close()
 
-    def _calculate_commit_stats(self, commit: Any) -> dict[str, int]:
+    def _calculate_commit_stats(self, commit: git.Commit) -> CommitStats:
         """Calculate commit statistics using reliable git diff --numstat with exclude_paths filtering.
 
+        When exclude_merge_commits is enabled, merge commits (commits with 2+ parents) will have
+        their filtered line counts set to 0 to exclude them from productivity metrics.
+
         Returns:
-            Dictionary with both raw and filtered statistics:
-            - 'files', 'insertions', 'deletions': filtered counts
-            - 'raw_insertions', 'raw_deletions': unfiltered counts
+            CommitStats dictionary with both raw and filtered statistics:
+            - 'files', 'insertions', 'deletions': filtered counts (0 for merge commits if excluded)
+            - 'raw_insertions', 'raw_deletions': unfiltered counts (always calculated)
 
         THREAD SAFETY: This method is thread-safe as it works with commit objects
         that have their own repo references.
@@ -1809,6 +1818,16 @@ class GitDataFetcher:
         raw_stats = {"files": 0, "insertions": 0, "deletions": 0}
         excluded_stats = {"files": 0, "insertions": 0, "deletions": 0}
 
+        # Check if this is a merge commit and we should exclude it from filtered counts
+        is_merge = is_merge_commit(commit)
+        if self.exclude_merge_commits and is_merge:
+            logger.debug(
+                f"Excluding merge commit {commit.hexsha[:8]} from filtered line counts "
+                f"(has {len(commit.parents)} parents)"
+            )
+            # Still need to calculate raw stats for the commit, but filtered stats will be 0
+            # Continue with calculation but will return zeros for filtered stats at the end
+
         # For initial commits or commits without parents
         parent = commit.parents[0] if commit.parents else None
 
@@ -1839,7 +1858,14 @@ class GitDataFetcher:
                 )
             except GitOperationTimeout:
                 logger.warning(f"⏱️ Timeout calculating stats for commit {commit.hexsha[:8]}")
-                return stats  # Return zeros
+                timeout_result: CommitStats = {
+                    "files": 0,
+                    "insertions": 0,
+                    "deletions": 0,
+                    "raw_insertions": 0,
+                    "raw_deletions": 0,
+                }
+                return timeout_result
 
             # Parse the numstat output: insertions\tdeletions\tfilename
             for line in diff_output.strip().split("\n"):
@@ -1902,10 +1928,27 @@ class GitDataFetcher:
             # Log the error for debugging but don't crash
             logger.warning(f"Error calculating commit stats for {commit.hexsha[:8]}: {e}")
 
+        # If this is a merge commit and we're excluding them, return zeros for filtered stats
+        # but keep the raw stats
+        if self.exclude_merge_commits and is_merge:
+            result: CommitStats = {
+                "files": 0,
+                "insertions": 0,
+                "deletions": 0,
+                "raw_insertions": raw_stats["insertions"],
+                "raw_deletions": raw_stats["deletions"],
+            }
+            return result
+
         # Return both raw and filtered stats
-        stats["raw_insertions"] = raw_stats["insertions"]
-        stats["raw_deletions"] = raw_stats["deletions"]
-        return stats
+        result: CommitStats = {
+            "files": stats["files"],
+            "insertions": stats["insertions"],
+            "deletions": stats["deletions"],
+            "raw_insertions": raw_stats["insertions"],
+            "raw_deletions": raw_stats["deletions"],
+        }
+        return result
 
     def _store_day_commits_incremental(
         self, repo_path: Path, date_str: str, commits: list[dict[str, Any]], project_key: str
@@ -1922,9 +1965,36 @@ class GitDataFetcher:
             project_key: Project identifier
         """
         try:
+            # Collect summary statistics for INFO-level logging
+            merge_count = 0
+            excluded_file_count = 0
+            total_excluded_insertions = 0
+            total_excluded_deletions = 0
+
             # Transform commits to cache format
             cache_format_commits = []
             for commit in commits:
+                # Track merge commits for summary logging
+                if commit.get("is_merge", False):
+                    merge_count += 1
+
+                # Track excluded file statistics
+                raw_insertions = commit.get("raw_insertions", commit.get("lines_added", 0))
+                raw_deletions = commit.get("raw_deletions", commit.get("lines_deleted", 0))
+                filtered_insertions = commit.get(
+                    "filtered_insertions", commit.get("lines_added", 0)
+                )
+                filtered_deletions = commit.get(
+                    "filtered_deletions", commit.get("lines_deleted", 0)
+                )
+
+                excluded_insertions = raw_insertions - filtered_insertions
+                excluded_deletions = raw_deletions - filtered_deletions
+                if excluded_insertions > 0 or excluded_deletions > 0:
+                    excluded_file_count += 1
+                    total_excluded_insertions += excluded_insertions
+                    total_excluded_deletions += excluded_deletions
+
                 cache_format_commit = {
                     "hash": commit["commit_hash"],
                     "author_name": commit.get("author_name", ""),
@@ -1935,15 +2005,11 @@ class GitDataFetcher:
                     "is_merge": commit.get("is_merge", False),
                     "files_changed_count": commit.get("files_changed_count", 0),
                     # Store raw unfiltered values
-                    "insertions": commit.get("raw_insertions", commit.get("lines_added", 0)),
-                    "deletions": commit.get("raw_deletions", commit.get("lines_deleted", 0)),
+                    "insertions": raw_insertions,
+                    "deletions": raw_deletions,
                     # Store filtered values
-                    "filtered_insertions": commit.get(
-                        "filtered_insertions", commit.get("lines_added", 0)
-                    ),
-                    "filtered_deletions": commit.get(
-                        "filtered_deletions", commit.get("lines_deleted", 0)
-                    ),
+                    "filtered_insertions": filtered_insertions,
+                    "filtered_deletions": filtered_deletions,
                     "story_points": commit.get("story_points"),
                     "ticket_references": commit.get("ticket_references", []),
                 }
@@ -1956,6 +2022,21 @@ class GitDataFetcher:
                     f"Incrementally stored {bulk_stats['inserted']} commits for {date_str} "
                     f"({bulk_stats['skipped']} already cached)"
                 )
+
+            # Summary logging at INFO level for user-facing visibility
+            if self.exclude_merge_commits and merge_count > 0:
+                logger.info(
+                    f"{date_str}: Excluded {merge_count} merge commits from filtered line counts "
+                    f"(exclude_merge_commits enabled)"
+                )
+
+            if self.exclude_paths and excluded_file_count > 0:
+                logger.info(
+                    f"{date_str}: Excluded changes from {excluded_file_count} commits "
+                    f"(+{total_excluded_insertions} -{total_excluded_deletions} lines) "
+                    f"due to path exclusions"
+                )
+
         except Exception as e:
             # Log error but don't fail - commits will be stored again in batch at the end
             logger.warning(f"Failed to incrementally store commits for {date_str}: {e}")

gitflow_analytics-3.12.5/src/gitflow_analytics/types/__init__.py

@@ -0,0 +1,5 @@
+"""Type definitions for GitFlow Analytics."""
+
+from .commit_types import CommitStats, FilteredCommitStats
+
+__all__ = ["CommitStats", "FilteredCommitStats"]

gitflow_analytics-3.12.5/src/gitflow_analytics/types/commit_types.py

@@ -0,0 +1,50 @@
+"""Type definitions for commit-related data structures."""
+
+from typing import TypedDict
+
+
+class CommitStats(TypedDict):
+    """Statistics for a single commit.
+
+    This type is used by DataFetcher._calculate_commit_stats() which provides
+    both filtered and raw (unfiltered) statistics. The filtered statistics
+    exclude files matching exclude_paths patterns, while raw statistics include
+    all changed files.
+
+    When exclude_merge_commits is enabled, merge commits will have filtered
+    counts set to 0 while raw counts reflect actual changes.
+
+    Attributes:
+        files: Number of files changed (filtered by exclude_paths)
+        insertions: Lines added (filtered by exclude_paths)
+        deletions: Lines removed (filtered by exclude_paths)
+        raw_insertions: Lines added (unfiltered, all files)
+        raw_deletions: Lines removed (unfiltered, all files)
+    """
+
+    files: int
+    insertions: int
+    deletions: int
+    raw_insertions: int
+    raw_deletions: int
+
+
+class FilteredCommitStats(TypedDict):
+    """Filtered statistics for a single commit.
+
+    This type is used by GitAnalyzer._calculate_filtered_stats() which only
+    provides filtered statistics (no raw counts). The filtered statistics
+    exclude files matching exclude_paths patterns.
+
+    When exclude_merge_commits is enabled, merge commits will have all
+    counts set to 0 to exclude them from productivity metrics.
+
+    Attributes:
+        files: Number of files changed (filtered by exclude_paths)
+        insertions: Lines added (filtered by exclude_paths)
+        deletions: Lines removed (filtered by exclude_paths)
+    """
+
+    files: int
+    insertions: int
+    deletions: int

gitflow_analytics-3.12.5/src/gitflow_analytics/utils/__init__.py

@@ -0,0 +1,5 @@
+"""Utility modules for GitFlow Analytics."""
+
+from .commit_utils import get_parent_count, is_initial_commit, is_merge_commit
+
+__all__ = ["is_merge_commit", "get_parent_count", "is_initial_commit"]

gitflow_analytics-3.12.5/src/gitflow_analytics/utils/commit_utils.py

@@ -0,0 +1,53 @@
+"""Utilities for working with Git commit objects."""
+
+import git
+
+
+def is_merge_commit(commit: git.Commit) -> bool:
+    """Determine if a commit is a merge commit.
+
+    A merge commit is one with 2 or more parent commits. This includes:
+    - Standard merges (2 parents)
+    - Octopus merges (3+ parents)
+
+    Args:
+        commit: GitPython Commit object to check
+
+    Returns:
+        True if commit has 2 or more parents, False otherwise
+
+    Examples:
+        >>> is_merge_commit(regular_commit)  # 1 parent
+        False
+        >>> is_merge_commit(merge_commit)    # 2 parents
+        True
+        >>> is_merge_commit(octopus_merge)   # 3+ parents
+        True
+        >>> is_merge_commit(initial_commit)  # 0 parents
+        False
+    """
+    return len(commit.parents) > 1
+
+
+def get_parent_count(commit: git.Commit) -> int:
+    """Get the number of parent commits.
+
+    Args:
+        commit: GitPython Commit object
+
+    Returns:
+        Number of parent commits (0 for initial commit, 1 for regular, 2+ for merge)
+    """
+    return len(commit.parents)
+
+
+def is_initial_commit(commit: git.Commit) -> bool:
+    """Determine if a commit is an initial commit (has no parents).
+
+    Args:
+        commit: GitPython Commit object to check
+
+    Returns:
+        True if commit has no parents, False otherwise
+    """
+    return len(commit.parents) == 0