Pre-commit Hook
Relevant source files
The following files were used as context for generating this wiki page:
The Pre-commit Hook is a quality assurance mechanism integrated into the development workflow to identify potential code duplications before changes are committed to the repository. It serves as a local gatekeeper, leveraging the duplicate-code-detection-tool library to analyze staged files and provide immediate feedback to developers regarding code similarity levels.
Within the project architecture, this hook utilizes the DuplicateCodeDetector class to perform analysis on specific Python files, ensuring that new code meets the project's refactoring standards. It is designed to be non-blocking by default (warning instead of failing) but can be configured to enforce strict similarity thresholds as part of a CI/CD Pipeline Integration.
Sources: README.md:167-171, core.py:12-21, examples/flext_integration_example.py:167-170
Hook Logic and Execution Flow
The pre-commit hook operates by intercepting the commit process, identifying the files currently staged in Git, and passing them to the detection engine. It specifically filters for supported file extensions (primarily .py) before initiating a similarity comparison against the existing codebase or among the staged files themselves.
Execution Workflow
The following diagram illustrates the lifecycle of a pre-commit check:
The flow ensures that the analysis only runs when relevant files are modified, minimizing overhead during the development process.
Sources: README.md:175-204, duplicate_code_detection.py:270-285
Core Components
The hook relies on several internal classes and methods to perform its analysis:
| Component | Description | Reference |
|---|---|---|
DuplicateCodeDetector | The main engine used to configure thresholds and run the analysis. | core.py:100-119 |
detect_in_files | Method used to analyze the specific list of staged files provided by the git hook. | core.py:168-195 |
only_code | Configuration flag used in hooks to strip comments/docstrings for more accurate logic comparison. | duplicate_code_detection.py:73-108 |
DetectionResult | The object returned by the detector, containing similarity reports and return codes. | core.py:65-97 |
Sources: core.py:100-195, duplicate_code_detection.py:73-108, README.md:244-270
Implementation Details
The implementation utilizes the DuplicateCodeDetector with specific parameters tailored for local developer feedback. Unlike CI/CD environments which might fail a build, the pre-commit hook typically uses a high fail_threshold to avoid blocking commits, while using a lower ignore_threshold to provide visibility into similarities.
# Configuration used in the pre-commit hook implementation
detector = DuplicateCodeDetector(
fail_threshold=100, # Don't fail, just warn
ignore_threshold=30, # Only report significant duplications
only_code=True, # Analyze logic, ignore comments
)
result = detector.detect_in_files(python_files)
Sources: README.md:188-195, core.py:177-194
Similarity Data Structure
The analysis results are structured into a hierarchy of reports and individual file similarities:
Sources: core.py:24-97
Configuration Options
The pre-commit hook can be customized using parameters supported by the DuplicateCodeDetector class.
| Parameter | Recommended Hook Value | Purpose |
|---|---|---|
fail_threshold | 100 | Prevents the hook from exiting with a non-zero code, ensuring commits are not blocked. |
ignore_threshold | 30 | Filters out minor similarities to prevent "noise" in the terminal. |
only_code | True | Uses astor and ast to strip docstrings, focusing on functional duplication. |
show_loc | True | Provides context on the size of the duplicated blocks. |
Sources: README.md:231-237, core.py:110-120, duplicate_code_detection.py:73-108
Summary
The Pre-commit Hook provides a critical first line of defense for code quality. By utilizing the DuplicateCodeDetector locally, it enables developers to identify and refactor redundant code before it reaches the shared repository. The integration is designed to be lightweight, focusing only on staged .py files and providing actionable warnings rather than strict failures.
Sources: README.md:167-208, pyproject.toml:44-52