diff-check

diff-check

A Git repository vs. file system diff analyzer.

Version: 1.0.0-rc.1
Last Updated: November 2, 2024

Table of Contents

• Features
• Usage
  • Basic Usage
  • Advanced Examples
  • Output Formats
• Command-Line Options
  • Required Arguments
  • Optional Arguments
• Output Files
• Use Cases
• Security Features
• Directory Structure
• How It Works
• Troubleshooting
• Development

Features

• ✅ Git-based comparison - Compare deployed files against any Git branch
• ✅ Multiple output formats - Full diff reports, summaries, artifact lists, and JSON
• ✅ Binary artifact detection - Automatically identifies .class, .jar files
• ✅ SSH key support - Works with private repositories using SSH keys
• ✅ Safe mode - Keeps temporary files for inspection (enabled by default)
• ✅ Production mode - Conservative logging for production environments
• ✅ Debug mode - Verbose output for troubleshooting
• ✅ Dry-run mode - Preview commands without execution
• ✅ Timestamped reports - Automatically dated output files
• ✅ Comprehensive validation - Input validation and error handling

Usage

Basic Usage

# Compare deployed app against main branch
./diff-check.sh --app-dir /var/www/myapp \
                --git-url git@github.com:user/repo.git \
                --branch main \
                --report ./reports

# Using HTTPS instead of SSH
./diff-check.sh --app-dir /opt/application \
                --git-url https://github.com/user/repo.git \
                --branch production \
                --report ./reports

Advanced Examples

# Private repository with SSH key
./diff-check.sh --app-dir /var/www/myapp \
                --git-url git@github.com:user/private-repo.git \
                --branch main \
                --ssh-key ~/.ssh/deploy_key \
                --report ./reports

# Generate JSON output for automation/CI
./diff-check.sh --app-dir /opt/app \
                --git-url git@github.com:user/repo.git \
                --branch production \
                --report ./reports \
                --json-file results.json

# Custom report file paths
./diff-check.sh --app-dir /var/www/app \
                --git-url git@github.com:user/repo.git \
                --branch main \
                --report-file ./custom-diff.log \
                --summary-file ./custom-summary.log \
                --artifact-file ./custom-artifacts.txt

# Debug mode for troubleshooting
./diff-check.sh --app-dir /opt/app \
                --git-url git@github.com:user/repo.git \
                --branch main \
                --report ./reports \
                --debug

# Production mode with safe cleanup
./diff-check.sh --app-dir /var/www/app \
                --git-url git@github.com:user/repo.git \
                --branch production \
                --report ./reports \
                --production \
                --no-safe-mode

# Dry-run to preview the diff command
./diff-check.sh --app-dir /opt/app \
                --git-url git@github.com:user/repo.git \
                --branch main \
                --dry-run

Output Formats

The tool generates multiple output formats to suit different needs:

1. Full Diff Report - Complete file-by-file comparison with tree-style formatting
2. Summary Report - Condensed list of changes (modified/added/deleted counts)
3. Artifact List - Binary artifacts (.class, .jar files) found
4. JSON Output - Machine-readable format for automation

Command-Line Options

Required Arguments

Option	Description
--app-dir PATH	Path to deployed application directory to analyze
--git-url URL	Git repository URL (supports both SSH and HTTPS)
--branch NAME	Branch name to compare against (e.g., main, production)

Optional Arguments

Option	Description	Default
--ssh-key PATH	SSH private key for Git clone (required for SSH URLs with private repos)	None
--report DIR	Directory to save all reports (creates timestamped files automatically)	None
--report-file PATH	Custom path for full diff report	{report-dir}/diff_{timestamp}.log
--summary-file PATH	Custom path for summary report	{report-dir}/summary_{timestamp}.log
--artifact-file PATH	Custom path for artifact list	{report-dir}/artifacts_{timestamp}.txt
--json-file PATH	Output results in JSON format for automation	None
--safe-mode	Keep temporary files for inspection	true
--no-safe-mode	Clean up temporary files after execution	-
--dry-run	Show commands without executing them	false
--debug	Enable verbose debug output	false
--production	Enable production mode logging (conservative output)	false
--help	Show help message and exit	-

Output Files

When you specify --report ./reports, the tool creates:

reports/
├── diff_20241102_143022.log        # Full diff report
├── summary_20241102_143022.log     # Summary (counts and lists)
└── artifacts_20241102_143022.txt   # Binary artifacts found

Full Diff Report Format

diff-check Report
═════════════════════════════════════════════════════════════════

Generated: 2024-11-02 14:30:22
App Directory: /var/www/myapp
Git Repository: git@github.com:user/repo.git
Branch: main

─────────────────────────────────────────────────────────────────

File Changes Summary
─────────────────────────────────────────────────────────────────
M  3 modified files
A  2 added files
D  1 deleted files
─────────────────────────────────────────────────────────────────

Modified Files:
  M  src/main/java/com/example/Application.java
  M  pom.xml
  M  config/application.properties

Added Files:
  A  src/main/java/com/example/NewFeature.java
  A  src/test/java/com/example/NewFeatureTest.java

Deleted Files:
  D  deprecated/OldClass.java

Binary Artifacts (3):
  target/classes/com/example/Application.class
  target/classes/com/example/NewFeature.class
  target/myapp-1.0.0.jar

JSON Output Format

{
  "timestamp": "20241102_143022",
  "full_diff_report": "./reports/diff_20241102_143022.log",
  "summary_report": "./reports/summary_20241102_143022.log",
  "artifact_report": "./reports/artifacts_20241102_143022.txt",
  "added_files": [
    "src/main/java/com/example/NewFeature.java",
    "src/test/java/com/example/NewFeatureTest.java"
  ],
  "modified_files": [
    "src/main/java/com/example/Application.java",
    "pom.xml",
    "config/application.properties"
  ],
  "deleted_files": [
    "deprecated/OldClass.java"
  ],
  "artifact_files": [
    "target/classes/com/example/Application.class",
    "target/classes/com/example/NewFeature.class",
    "target/myapp-1.0.0.jar"
  ]
}

Use Cases

1. Deployment Verification

Verify that your production deployment matches the expected Git branch:

./diff-check.sh --app-dir /var/www/production \
                --git-url git@github.com:company/app.git \
                --branch v2.3.1 \
                --report ./deployment-check \
                --production

2. Configuration Drift Detection

Check if deployed configurations have drifted from source control:

./diff-check.sh --app-dir /opt/application \
                --git-url https://github.com/company/config.git \
                --branch production \
                --report ./drift-reports \
                --json-file drift.json

3. Pre-Deployment Comparison

Preview what will change before deploying:

./diff-check.sh --app-dir /var/www/staging \
                --git-url git@github.com:company/app.git \
                --branch release-candidate \
                --report ./pre-deploy-checks

4. CI/CD Integration

Integrate into CI/CD pipelines with JSON output:

#!/bin/bash
./diff-check.sh --app-dir /deploy/target \
                --git-url "${GIT_REPO_URL}" \
                --branch "${DEPLOY_BRANCH}" \
                --json-file results.json \
                --report ./ci-reports

# Parse JSON and fail if unexpected changes detected
if jq -e '.modified_files | length > 0' results.json > /dev/null; then
  echo "WARNING: Modified files detected in deployment"
  jq '.modified_files[]' results.json
fi

5. Audit Trail

Create timestamped audit records of deployment states:

./diff-check.sh --app-dir /var/www/app \
                --git-url git@github.com:company/app.git \
                --branch production \
                --report /var/log/deployment-audits \
                --production

Security Features

• ✅ SSH key validation - Checks key existence and permissions
• ✅ Path validation - Validates all directory paths before use
• ✅ Secure temporary files - Uses process-specific temp directories
• ✅ Strict error handling - Exits on errors (set -e)
• ✅ Input sanitization - Validates Git URLs and branch names
• ✅ Safe mode by default - Preserves temp files for inspection
• ✅ No automatic execution - Explicit flags required for operations
• ✅ Git shallow clone - Uses --depth=1 for security and performance

Directory Structure

diff-check/
├── diff-check.sh           # Main script
├── README.md              # This file
├── diagnostics.sh         # Diagnostic utilities
└── lib/                   # Helper libraries
    └── diff_helpers.sh    # Core comparison and formatting functions

How It Works

1. Validation - Validates all required inputs (app directory, Git URL, branch)
2. Git Clone - Clones the specified Git branch into a temporary directory
3. Comparison - Uses diff -r -q to compare deployed files vs Git HEAD
4. Parsing - Parses diff output to categorize changes (modified/added/deleted)
5. Artifact Detection - Identifies binary artifacts (.class, .jar files)
6. Report Generation - Creates multiple output formats (full report, summary, JSON)
7. Cleanup - Removes temporary files (unless --safe-mode is enabled)

Excluded Patterns

The following directories are automatically excluded from comparison:

• .git - Git metadata
• logs - Log files
• tmp - Temporary files
• target - Build outputs (Maven/Gradle)

Troubleshooting

Common Issues

Error: SSH key file not found

# Check key exists
ls -la ~/.ssh/deploy_key

# Fix permissions if needed
chmod 600 ~/.ssh/deploy_key

# Specify correct path
./diff-check.sh --ssh-key ~/.ssh/deploy_key ...

Error: Git clone failed

# Test SSH connection
ssh -i ~/.ssh/deploy_key -T git@github.com

# Try HTTPS instead of SSH
./diff-check.sh --git-url https://github.com/user/repo.git ...

# Enable debug mode to see exact error
./diff-check.sh --debug ...

Error: App directory does not exist

# Verify path is correct
ls -la /var/www/myapp

# Use absolute path
./diff-check.sh --app-dir "$(pwd)/myapp" ...

Error: Failed to create directory

# Check write permissions
ls -ld ./reports

# Create directory manually
mkdir -p ./reports
chmod 755 ./reports

Debug Mode

Enable debug mode to see detailed execution information:

./diff-check.sh --app-dir /var/www/app \
                --git-url git@github.com:user/repo.git \
                --branch main \
                --report ./reports \
                --debug

Debug mode shows:

• Full diff commands
• Git clone commands
• File parsing details
• Path resolution
• Temporary directory contents

Safe Mode

Safe mode (enabled by default) keeps temporary files for inspection:

# Temp files preserved in /tmp/app-diff-{pid}/
ls -la /tmp/app-diff-*/

# View cloned repository
ls -la /tmp/app-diff-*/repo/

# View raw diff output
cat /tmp/app-diff-*/raw_diff.tmp

Development

Testing

The tool includes comprehensive testing capabilities:

# Run unit tests (if available)
cd tests
./run_unit_tests.sh

# Test with dry-run mode
./diff-check.sh --app-dir /test/path \
                --git-url https://github.com/test/repo.git \
                --branch main \
                --dry-run

Adding Features

To extend diff-check functionality:

1. Edit helper library: lib/diff_helpers.sh
2. Add new output formats: Extend generate_*_report() functions
3. Customize exclusions: Modify EXCLUDE_PATTERNS array
4. Add new detectors: Extend artifact detection patterns

Contributing

Contributions are welcome! Please:

1. Test changes with --debug and --dry-run modes
2. Verify all output formats (report, summary, JSON)
3. Check with both SSH and HTTPS Git URLs
4. Test with safe mode on and off
5. Ensure backward compatibility

License

MIT License - See LICENSE file for details

Author

Mina Demian mina@minademian.com

Related Tools

• server-audit - Multi-server auditing tool for binary version checking
• Part of the server-utilities collection

---