Qaren (قارن)

English | 中文 | Русский | العربية | فارسی | 日本語 | Deutsch | Français

The Next Generation of Configuration and System Backup Comparison.
Built for the modern DevOps era: Semantic, Secure, and Blazingly Fast.

---

Why Qaren?    

Standard POSIX diff has served us for 50 years, but it was designed for source code, not for the complex, order-agnostic configuration files and massive system backups of today.

Qaren (Arabic for "Compare") is a multi-paradigm tool that understands your data.

• Semantic Key-Value Parsing: Order doesn't matter. Formatting doesn't matter. Only the data matters.
• Zero-Trust Security: Secrets like API keys, passwords, and connection strings are masked by default (***MASKED***).
• Blazingly Fast: Optimized in Rust to handle GB-scale backups and 100k+ keys up to 200x faster than traditional diff pipelines.
• ANSI-Aware: Automatically cleans terminal color codes from "polluted" files (like pm2 env output) for clean comparison.
• Intelligent Patching: Generate production-ready .env patches to synchronize environments in seconds.

---

Documentation

For detailed guides, API reference, and advanced configuration, visit our documentation:

https://qaren.me/docs

---

Key Features

1. Semantic KV mode

Understand .env, .yaml, and .ini files regardless of key order.

2. Enhanced Literal Output

Qaren provides much clearer line-by-line diffs than POSIX diff, specifically optimized for system backup analysis.

Traditional POSIX Diff

Qaren Enhanced Diff

3. Smart Noise Reduction

Comparing JSON-based backups in KV mode? Qaren automatically suppresses duplicate key and permission warnings by default to keep your terminal clean. If you need assistance debugging, run qaren config advisor toggle to enable helpful alerts.

---

Installation

Quick Install (Automated)

Platform	Command
Linux / macOS	`curl -sSfL https://qaren.me/install
Windows	`irm https://qaren.me/install.ps1
Homebrew	brew tap qaren-cli/qaren && brew install qaren

Alternative Methods

# Via Cargo
cargo install qaren

---

Usage & Examples

Qaren's kv mode is designed for real-world DevOps tasks. All the following examples are tested using the data shown in these two environment files:

1. Basic Semantic Diff

Compare two files semantically, ignoring line order.

qaren kv -Q --d2 ":" dev.env staging.env

2. Summary Mode

Get a high-level overview of differences without detailed line changes.

qaren kv -Q --d2 ":" dev.env staging.env -s

3. JSON Export

Export results in machine-readable format for automation.

qaren kv -Q --d2 ":" dev.env staging.env -o json

4. Show Secrets

Bypass automatic masking to see raw sensitive values.

qaren kv -Q --d2 ":" dev.env staging.env -S

5. Ignore Specific Keys

Exclude known dynamic or irrelevant keys from comparison.

qaren kv -Q --d2 ":" dev.env staging.env -x API_KEY

6. Ignore by Keyword

Exclude all keys containing a specific substring.

qaren kv --ignore-keyword MAX ...

7. Quiet Mode

Check compatibility in scripts via exit codes only.

qaren kv -Q --d2 ":" dev.env staging.env -q

8. Patch Generation

Create a patch file to synchronize missing keys.

qaren kv ... -g missing.env

9. Secure Patching

Generate patches with sensitive data automatically masked.

qaren kv ... -g missing.env --mask-patches

---

Literal Comparison (Diff)

1. Basic Diff

Standard line-by-line comparison with enhanced readability.

qaren diff file1.txt file2.txt

2. Unified format

POSIX-compliant unified diff output.

qaren diff file1.txt file2.txt -u

3. Recursive Directory Diff

Compare entire directory structures, identifying orphan files and differences in existing ones.

qaren diff -r old-backup/ new-backup/

4. Advanced Options

# Strip ANSI colors from system snapshots before diffing
qaren diff backup_polluted.txt backup_clean.txt -A

# Ignore whitespace and blank lines
qaren diff f1.txt f2.txt -w -B

# Only show which files differ (recursive mode)
qaren diff -r old-backup/ new-backup/ --files-only

---

Configuration

Qaren remembers your preferences.

# Toggle pipeline-friendly mode (always exit 0)
qaren config exit toggle

# Toggle color output
qaren config color toggle

# Toggle advisor (warnings)
qaren config advisor toggle

# Toggle secret masking
qaren config masking toggle

# View current settings
qaren config show

---

Performance Benchmarks

Scenario	Winner	Margin
Large Backups (100MB)	Qaren	200x+
Recursive Directory	Qaren	3x
Massive Changes (1M Lines)	Qaren	50x+

---

Contributing & Support

We are Open for Contributions! Please read our Contributing Guide before submitting a Pull Request.

• Fork the repo.
• Improve or Add features (avoid deletions).
• Ensure Zero Warnings (clippy & tests).
• Update Docs and --help for new flags.

Please star the project if you find it useful!

• Official Website: https://qaren.me/
• Full Documentation: https://qaren.me/docs
• Bug Reports: Go to https://qaren.me/community and click "Open Issue".

---

License

This project is licensed under the MIT License. See the LICENSE file for details.

---