Skip to content

diffenv - Environment Diff Tool

Environment comparison and change detection tool for tracking system and configuration modifications.

Overview

diffenv compares environment states, configurations, and system settings between different points in time or across different systems. It helps identify changes, track modifications, and maintain environment consistency.

When to use: Tracking configuration changes, comparing system states, or identifying what changed between deployments.

Usage

diffenv [options] <source> <target>
diffenv [options] --baseline <baseline-file>
```bash

### Options

- `-o FILE`: Output file
- `-f FORMAT`: Output format (unified, context, json)
- `-t TYPE`: Comparison type (files, packages, config, all)
- `-i PATTERN`: Include pattern
- `-x PATTERN`: Exclude pattern
- `-c`: Color output
- `-s`: Summary only
- `-v`: Verbose output
- `-h`: Show help

### Comparison Types

- `files`: File system differences
- `packages`: Installed package differences
- `config`: Configuration file differences
- `services`: Service configuration differences
- `users`: User account differences
- `all`: All comparison types

## Examples

### Basic Comparisons

```bash
# Compare two directories
diffenv /path/to/baseline /path/to/current

# Compare with baseline file
diffenv --baseline baseline.json .

# Compare package states
diffenv -t packages baseline.txt current.txt
```bash

### System Comparisons

```bash
# Compare system configurations
diffenv -t config /etc/baseline /etc/current

# Compare installed packages
diffenv -t packages pkg-baseline.txt pkg-current.txt

# Full system comparison
diffenv -t all system1-snapshot system2-snapshot
```bash

### Change Tracking

```bash
# Track configuration changes
diffenv --baseline /etc/baseline.json /etc/

# Compare before/after updates
diffenv -t packages before-update.txt after-update.txt

# Monitor file changes
diffenv -t files ~/config-baseline ~/config-current
```bash

### Output Control

```bash
# Colored unified diff
diffenv -c -f unified baseline current

# JSON output for processing
diffenv -f json baseline current > changes.json

# Summary only
diffenv -s baseline current
```bash

## How It Works

### Comparison Methods

1. **File Comparison**: Content and metadata diff
2. **Package Comparison**: Installed software diff
3. **Config Comparison**: Configuration file analysis
4. **System State**: Environment variable and setting diff

### Diff Algorithms

- **Unified Diff**: Standard diff format with context
- **Context Diff**: Traditional diff with context lines
- **JSON Diff**: Structured difference representation
- **Summary**: High-level change overview

### Change Detection

- **Content Changes**: File content modifications
- **Metadata Changes**: Permissions, ownership, timestamps
- **Addition/Deletion**: New or removed files/packages
- **Configuration Drift**: Settings that differ from baseline

## Configuration

### Configuration File

```toml
# ~/.config/diffenv/config.toml
[comparison]
default_format = "unified"
context_lines = 3
ignore_whitespace = true
ignore_timestamps = false

[filters]
include_patterns = ["*.conf", "*.service", "*.toml"]
exclude_patterns = ["*.log", "*.tmp", "*cache*"]

[output]
color = true
summary_first = true
max_diff_size = "1MB"

[performance]
parallel_processing = true
memory_limit = "512MB"
timeout = 300
```bash

### Environment Variables

```bash
# Output settings
export DIFFENV_FORMAT="json"
export DIFFENV_COLOR="false"

# Comparison settings
export DIFFENV_CONTEXT_LINES="5"
export DIFFENV_IGNORE_WHITESPACE="true"

# Performance
export DIFFENV_TIMEOUT="600"
export DIFFENV_MEMORY_LIMIT="1GB"
```bash

## Dependencies

### Required

- **diff**: Core diff functionality
- **find**: File discovery
- **sort**: Output sorting
- **grep**: Pattern matching

### Optional

- **colordiff**: Colored diff output
- **wdiff**: Word-based diff
- **jq**: JSON processing
- **delta**: Enhanced diff viewer

## Troubleshooting

### Large Diffs

**Symptom:** Diff output is too large or slow

**Cause:** Comparing large directories or many files

**Fix:**

```bash
# Use summary mode
diffenv -s baseline current

# Limit file types
diffenv -i "*.conf" baseline current

# Exclude large files
diffenv -x "*.log" -x "*.db" baseline current
```bash

### Memory Issues

**Symptom:** Out of memory during comparison

**Cause:** Large files or many differences

**Fix:**

```bash
# Increase memory limit
export DIFFENV_MEMORY_LIMIT="2GB"

# Process in chunks
diffenv -t files --chunk-size 1000 baseline current

# Use external diff
export DIFFENV_EXTERNAL_DIFF="true"
```bash

### Permission Differences

**Symptom:** Many permission differences reported

**Cause:** Different users or systems

**Fix:**

```bash
# Ignore permissions
export DIFFENV_IGNORE_PERMISSIONS="true"

# Compare as specific user
sudo -u targetuser diffenv baseline current

# Filter permission diffs
diffenv baseline current | grep -v "permissions"
```bash

### No Differences Found

**Symptom:** Reports no changes when there should be

**Cause:** Incorrect paths or filtering

**Fix:**

```bash
# Check paths exist
ls -la baseline/
ls -la current/

# Verify with simple diff
diff baseline/file current/file

# Check filters
diffenv -v baseline current
```bash

## Performance

### Comparison Times

| Scenario         | Files | Time | Memory |
| ---------------- | ----- | ---- | ------ |
| Small config     | 100   | 2s   | 50MB   |
| Medium system    | 1000  | 30s  | 200MB  |
| Large filesystem | 10000 | 5min | 1GB    |

### Optimization Tips

- **Filter Early**: Use include/exclude patterns
- **Summary Mode**: For large comparisons
- **Parallel Processing**: Enable for multi-core systems
- **External Tools**: Use specialized diff tools for large files

## Integration

### With Version Control

```bash
# Track configuration changes
diffenv --baseline .git/config-baseline .git/config

# Compare branches
git show branch1:file > file1
git show branch2:file > file2
diffenv file1 file2
```bash

### With Backup Systems

```bash
# Compare backup integrity
diffenv -t files /original /backup/restore

# Track backup changes
diffenv --baseline last-backup-manifest.json current-backup/
```bash

### With Deployment

```bash
# Pre/post deployment comparison
diffenv -t config pre-deploy.json post-deploy.json

# Environment drift detection
diffenv -t all production-baseline.json current-production.json
```bash

### With Monitoring

```bash
# Automated change detection
diffenv -s --baseline /etc/baseline /etc/ > /var/log/config-changes.log

# Alert on changes
if [ -s /var/log/config-changes.log ]; then
    mail -s "Configuration Changes Detected" admin@example.com < /var/log/config-changes.log
fi
```bash

## Output Formats

### Unified Format (default)

```diff
--- baseline/etc/ssh/sshd_config
+++ current/etc/ssh/sshd_config
@@ -13,7 +13,7 @@
 #PermitRootLogin prohibit-password
 PermitRootLogin no
 #StrictModes yes
-#MaxAuthTries 6
+MaxAuthTries 3
 #MaxSessions 10

 #PubkeyAuthentication yes
```bash

### Context Format

```diff
*** baseline/etc/ssh/sshd_config
--- current/etc/ssh/sshd_config
***************
*** 13,19 ****
  #PermitRootLogin prohibit-password
  PermitRootLogin no
  #StrictModes yes
- #MaxAuthTries 6
+ MaxAuthTries 3
  #MaxSessions 10

  #PubkeyAuthentication yes
```bash

### JSON Format

```json
{
  "comparison": {
    "source": "baseline",
    "target": "current",
    "timestamp": "2024-01-01T12:00:00Z",
    "type": "files"
  },
  "changes": [
    {
      "file": "/etc/ssh/sshd_config",
      "type": "modified",
      "changes": [
        {
          "line": 16,
          "old": "#MaxAuthTries 6",
          "new": "MaxAuthTries 3"
        }
      ]
    }
  ],
  "summary": {
    "files_changed": 1,
    "additions": 1,
    "deletions": 1,
    "modifications": 1
  }
}
```bash

## Technical Details

### Diff Algorithms

- **Myers Algorithm**: Default diff algorithm
- **Patience Diff**: Alternative for common sequences
- **Histogram Diff**: Good for large files
- **Word Diff**: Word-level differences

### File Comparison

- **Content Diff**: Text file content comparison
- **Binary Diff**: Binary file change detection
- **Metadata Diff**: Permission, ownership, timestamp comparison
- **Hash Comparison**: Quick change detection for large files

### Filtering System

- **Glob Patterns**: `*.conf`, `*.service`
- **Path Patterns**: `/etc/ssh/*`, `~/.*rc`
- **Size Filters**: Skip files over size limit
- **Type Filters**: Text, binary, or specific types

### Performance Optimizations

- **Parallel Processing**: Multiple files simultaneously
- **Memory Mapping**: Large file handling
- **Incremental Diff**: Resume interrupted comparisons
- **Caching**: Hash caching for repeated comparisons

## See Also

- **[auditenv](auditenv.md)** - Environment auditing
- **[syssnap](syssnap.md)** - System snapshots
- **[Change Tracking](../../README.md#change-tracking)** - Change management guide