Command Line Interface Guide
Relevant source files
The following files were used as context for generating this wiki page:
The Command Line Interface (CLI) of the Duplicate Code Detection Tool provides a powerful entry point for developers to analyze source code for similarities without writing custom scripts. It allows users to scan specific files, entire directories, or full projects with configurable thresholds for reporting and failure.
The CLI is registered as a console script named duplicate-code-detection, which maps directly to the main() function in the duplicate_code_detection.py module. It supports various output formats including human-readable console text, JSON for machine processing, and CSV for reporting.
Sources: pyproject.toml:58, setup.py:50, duplicate_code_detection.py:126-218
CLI Architecture and Execution Flow
The CLI is built using the argparse module to handle user inputs and options. When executed, the tool follows a structured sequence: parsing arguments, identifying target source files, processing code (optionally stripping comments), calculating TF-IDF based similarity, and finally generating the requested output format.
Execution Process
This diagram illustrates the high-level logic within the run function called by the CLI entry point.
Sources: duplicate_code_detection.py:221-419
Command Line Arguments
The tool provides several options to control the scope and sensitivity of the duplication analysis.
Required Arguments
Users must provide either a list of directories or a list of specific files to analyze.
| Argument | Short | Description |
|---|---|---|
--directories | -d | Space-separated list of directories to scan for similarities. |
--files | -f | Space-separated list of specific files to compare (minimum 2). |
Sources: duplicate_code_detection.py:141-152
Configuration Options
These parameters allow users to tune the detection engine and define pass/fail criteria for CI/CD environments.
| Argument | Default | Description |
|---|---|---|
--fail-threshold | 100 | The maximum allowed similarity (%) before exiting with error code 2. |
--ignore-threshold | 0 | Similarities below this percentage are omitted from the report. |
--file-extensions | h, c, cpp, cc, java, py, cs | List of extensions to include in the scan. |
--ignore-directories | [] | List of directories to exclude from analysis. |
--ignore-files | [] | List of specific files to exclude from analysis. |
--only-code | False | If set, strips docstrings and comments from Python files before analysis. |
--show-loc | False | Includes Line of Code (LoC) counts in the output. |
Sources: duplicate_code_detection.py:133-189, duplicate_code_detection.py:31-35
Output Formats
The CLI supports three primary output methods to accommodate different use cases, from manual inspection to automated quality gates.
1. Standard Console Output
The default output provides a color-coded table in the terminal. It uses ANSI escape codes to highlight different similarity levels:
- Green: Low similarity (< 10%)
- Yellow: Moderate similarity (< 20%)
- Red: High similarity (>= 20%)
Sources: duplicate_code_detection.py:44-53, duplicate_code_detection.py:365-373
2. JSON Output
Enabled via the -j or --json flag. This outputs a structured JSON object to stdout, which is ideal for integration with other tools or CI/CD pipelines.
{
"file1.py": {
"file2.py": 85.5,
"#LoC": 120
}
}
Sources: duplicate_code_detection.py:161, duplicate_code_detection.py:392-394
3. CSV Output
Enabled via the --csv-output flag followed by a file path. This generates a spreadsheet-compatible file containing pairs of files and their similarity percentages.
Sources: duplicate_code_detection.py:182-186, duplicate_code_detection.py:396-424
Return Codes
The CLI returns specific integer codes upon completion, allowing for programmatic handling of results in shell scripts or GitHub Actions.
| Code | Name | Description |
|---|---|---|
| 0 | SUCCESS | Analysis completed and all similarities are within the fail threshold. |
| 1 | BAD_INPUT | The tool was provided with invalid paths or insufficient files (< 2). |
| 2 | THRESHOLD_EXCEEDED | At least one file pair exceeded the similarity limit defined by --fail-threshold. |
Sources: duplicate_code_detection.py:38-41, duplicate_code_detection.py:257-268
GitHub Actions Integration
The CLI is also wrapped for use as a GitHub Action. In this context, the CLI parameters are mapped to GitHub Action inputs defined in action.yml. The run_action.py script acts as a secondary wrapper that translates these inputs into a call to the main run() function and formats the results as a Markdown comment on Pull Requests.
Conclusion
The Command Line Interface provides a flexible and robust way to detect code duplication. By supporting multiple output formats and configurable thresholds, it serves as both a developer tool for local refactoring and a critical component in automated quality assurance workflows.
Sources: README.md:55-70