development · Command reference
qzx compareFiles
What it does
Compares text files line by line and binary files by exact bytes and SHA-256
Command maturity: Alpha
Available for real use and feedback while its interface and behavior can still evolve. This is the current development-checkout assessment. Every future immutable release tag preserves the exact assessment shipped by that version. Available in PyPI 0.2.2.0.15. This page documents the 0.2.2.0.15 alpha development checkout.
Behavior and built-in protections
Inspects without changing state
Direct execution for this operation
Works without invoking native programs
Works without network access
No elevation required by design
This safety classification was reviewed by Claude Opus 5.5 (Anthropic) against implementation digest sha256:4301a207b3295d83e9045f93e24392946d7bcc87f48dfcadac697b78455ecfb6 on 2026-10-08.
Exact syntax
qzx compareFiles <file1> <file2> [mode] [max_bytes] --jsonParameters
Swipe or use the horizontal scrollbar to see every column.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| file1 | str | Yes | Not declared | Path to the first file |
| file2 | str | Yes | Not declared | Path to the second file |
| mode | str | No | "full" | Comparison mode: "full", "summary", or "percent" |
| max_bytes | int | No | 1048576 | Maximum allowed size of each file in bytes (defaults to 1 MiB) |
Input examples
qzx compareFiles "file1.py" "file2.py"Compare two Python files and show every difference
qzx compareFiles "file1.txt" "file2.txt" "summary"Show a summary of differences between two text files
qzx compareFiles "version1.js" "version2.js" "percent"Show the similarity percentage between two JavaScript files
qzx compareFiles "image-a.png" "image-b.png"Check whether two binary files are exactly equal by bytes and SHA-256
For the complete structured payload, add --json: qzx compareFiles <file1> <file2> [mode] [max_bytes] --json
Observed output example
Captured with QZX 0.2.2.0.15 on Windows 11; exit code 0. Host-dependent values and duration can vary.
Example command: qzx compareFiles ../artifacts/qzx-evidence/compare-files/before.txt ../artifacts/qzx-evidence/compare-files/after.txt full --json
{
"success": true,
"file1": "../artifacts/qzx-evidence/compare-files/before.txt",
"file2": "../artifacts/qzx-evidence/compare-files/after.txt",
"identical": false,
"added_lines": 1,
"removed_lines": 1,
"total_changes": 2,
"diff": "Differences between '../artifacts/qzx-evidence/compare-files/before.txt' and '../artifacts/qzx-evidence/compare-files/after.txt':\n--- ../artifacts/qzx-evidence/compare-files/before.txt\n+++ ../artifacts/qzx-evidence/compare-files/after.txt\n@@ -1,2 +1,2 @@\n shared line\n-before\n+after\n\nStatistics:\n- Added lines: 1\n- Removed lines: 1\n- Total changes: 2",
"message": "Compared '../artifacts/qzx-evidence/compare-files/before.txt' with '../artifacts/qzx-evidence/compare-files/after.txt': 1 added and 1 removed lines.",
"content_type": "text",
"comparison_basis": "decoded_text_lines",
"byte_identical": false,
"bytes_file1": 21,
"bytes_file2": 20,
"encoding_file1": "utf-8",
"encoding_file2": "utf-8",
"encoding_confidence_file1": 1,
"encoding_confidence_file2": 1,
"sha256_file1": "66b132726d57d857c416bf212c2ac4758f8088ffd9144b01fca3f412dd0e163a",
"sha256_file2": "245ea69b327e3ad2ea5f90573f1a6357e076642171ad33720bd183fd7aed18f9",
"similarity_available": true,
"mode": "full",
"max_bytes": 1048576,
"meta": {
"command": "compareFiles",
"command_maturity": {
"stage": "alpha",
"label": "Alpha",
"sequence": 2,
"public_executable": true,
"stability": "interface_may_change",
"summary": "Available for real use and feedback while its interface and behavior can still evolve.",
"promotion_review_required": false,
"assessment_scope": "development_checkout"
},
"duration_ms": 5.065,
"schema_version": 1
}
}View the JSON result contract
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"error": {
"type": "string"
},
"error_code": {
"type": "string"
},
"remediation": {
"type": "string"
},
"file1": {
"type": "string"
},
"file2": {
"type": "string"
},
"mode": {
"type": "string",
"enum": [
"full",
"summary",
"percent"
]
},
"identical": {
"type": "boolean"
},
"added_lines": {
"type": "integer"
},
"removed_lines": {
"type": "integer"
},
"total_changes": {
"type": "integer"
},
"diff": {
"type": "string"
},
"similarity": {
"type": "number"
},
"lines_file1": {
"type": "integer"
},
"lines_file2": {
"type": "integer"
},
"identical_lines": {
"type": "integer"
},
"changes": {
"type": "integer"
},
"summary": {
"type": "string"
},
"content_type": {
"type": "string",
"enum": [
"text",
"binary"
]
},
"comparison_basis": {
"type": "string"
},
"byte_identical": {
"type": "boolean"
},
"bytes_file1": {
"type": "integer"
},
"bytes_file2": {
"type": "integer"
},
"max_bytes": {
"type": "integer"
},
"encoding_file1": {
"type": [
"string",
"null"
]
},
"encoding_file2": {
"type": [
"string",
"null"
]
},
"encoding_confidence_file1": {
"type": [
"number",
"null"
]
},
"encoding_confidence_file2": {
"type": [
"number",
"null"
]
},
"sha256_file1": {
"type": "string"
},
"sha256_file2": {
"type": "string"
},
"similarity_available": {
"type": "boolean"
},
"meta": {
"type": "object",
"required": [
"command",
"command_maturity",
"duration_ms",
"schema_version"
],
"properties": {
"command": {
"type": "string"
},
"command_maturity": {
"type": "object",
"required": [
"stage",
"label",
"sequence",
"public_executable",
"stability",
"summary",
"promotion_review_required",
"assessment_scope"
],
"properties": {
"stage": {
"type": "string"
},
"label": {
"type": "string"
},
"sequence": {
"type": "integer"
},
"public_executable": {
"type": "boolean"
},
"stability": {
"type": "string"
},
"summary": {
"type": "string"
},
"promotion_review_required": {
"type": "boolean"
},
"assessment_scope": {
"type": "string"
},
"note": {
"type": "string"
},
"review": {
"type": "object",
"required": [
"reviewed_on",
"rationale",
"evidence"
],
"properties": {
"reviewed_on": {
"type": "string",
"format": "date"
},
"rationale": {
"type": "string"
},
"evidence": {
"type": "array",
"minItems": 1,
"items": {
"type": "string"
}
},
"replacement": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": true
},
"duration_ms": {
"type": "number"
},
"schema_version": {
"type": "integer"
}
},
"additionalProperties": true
}
},
"additionalProperties": true,
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"message",
"meta",
"success"
]
}Errors and limits
The public contract requires success=false and a descriptive message on failure. This catalog does not yet declare a command-specific error taxonomy; inspect the result and do not invent error codes.
QZX is alpha software. Optional dependencies, permissions, and host capabilities can change the result.
Evidence workflow: captured and digest-validated.
Evidence and provenance
- Implementation
- src/qzx/commands/development/compare_files.py
- Documentation channel
- Development documentation 0.2.2.0.15 · main · sha256:b91acee86268edb7cb018a94e089ff8e95835eda3f2cf08b39796c0ab9654693
- Availability
- 0.2.2.0.15 or earlier
Keep exploring
Related commands
These commands also belong to the development category. Compare them to choose the operation that best fits your task.
qzx cleanDevelopmentArtifactsFinds development caches, dependency directories, and generated build artifacts; preview is the defaultqzx deployProjectPreviews or deploys one explicit artifact over SSH using a verified remote backup, SHA-256 validation, atomic promotion, health checks, and automatic rollbackqzx auditRepositoryRuns security and quality audits on a Git repository (secrets, large files, duplicates, .gitignore compliance, licenses)qzx diagnoseProjectInspects project technologies, dependencies, validation workflows, Git state, source quality, and large files without executing project scripts