Skip to content

README.md

Latest commit

 

History

History
228 lines (171 loc) · 5.29 KB

README.md

File metadata and controls

228 lines (171 loc) · 5.29 KB

go-config-diff

A semantic configuration comparison tool for infrastructure and application configs. Compare YAML, JSON, TOML, and INI files intelligently - detecting meaningful differences while ignoring formatting and ordering variations.

Features

  • 🎯 Semantic Comparison: Compares configuration semantics, not just text
  • 📝 Multiple Formats: Supports YAML, JSON, TOML, and INI files
  • 🎨 Colored Output: Beautiful, easy-to-read colored diffs in terminal
  • 📊 Machine-Readable: JSON output for integration with other tools
  • 🔄 Order-Independent: Ignores key ordering in maps/objects
  • 🧩 Nested Structures: Deep comparison of nested configurations
  • 📈 Change Summary: Quick overview of additions, removals, and modifications

Installation

From Source

go install github.com/BaseMax/go-config-diff/cmd/go-config-diff@latest

Build Locally

git clone https://github.com/BaseMax/go-config-diff.git
cd go-config-diff
go build -o go-config-diff ./cmd/go-config-diff

Usage

Basic Usage

go-config-diff config1.yaml config2.yaml

Output Formats

Colored Output (default)

Displays changes with color-coded indicators:

  • 🟢 Green + for additions
  • 🔴 Red - for removals
  • 🟡 Yellow ~ for modifications
go-config-diff config1.yaml config2.yaml

Plain Text Output

For environments without color support:

go-config-diff -format=plain config1.json config2.json

JSON Output

Machine-readable format for automation:

go-config-diff -format=json config1.toml config2.toml

Show Summary

Display a summary of changes:

go-config-diff -summary config1.ini config2.ini

Version Information

go-config-diff -version

Examples

YAML Comparison

$ go-config-diff examples/config1.yaml examples/config2.yaml
~ database.credentials.password
  - "secret123"
  + "newsecret456"
~ database.name
  - "myapp"
  + "myapp_prod"
+ features[3]
  + "caching"
+ server.timeout
  + 60

JSON Output Format

$ go-config-diff -format=json examples/config1.json examples/config2.json
{
  "has_changes": true,
  "changes": [
    {
      "type": "modified",
      "path": "database.name",
      "old_value": "myapp",
      "new_value": "myapp_prod"
    },
    {
      "type": "added",
      "path": "server.timeout",
      "new_value": 60
    }
  ]
}

With Summary

$ go-config-diff -summary examples/config1.toml examples/config2.toml
Summary: 2 added, 5 modified

~ database.name
  - "myapp"
  + "myapp_prod"
+ features[3]
  + {"name":"caching"}

Supported File Formats

Format Extensions Description
YAML .yaml, .yml YAML Ain't Markup Language
JSON .json JavaScript Object Notation
TOML .toml Tom's Obvious, Minimal Language
INI .ini, .conf Initialization files

How It Works

  1. Parse: Each configuration file is parsed using format-specific parsers
  2. Normalize: Data is converted to a unified internal AST (Abstract Syntax Tree)
  3. Compare: Semantic comparison detects actual differences
  4. Report: Changes are formatted for human or machine consumption

Key Capabilities

  • Semantic Comparison: Compares actual values, not file formatting
  • Type Awareness: Understands different data types (strings, numbers, booleans, arrays, maps)
  • Deep Traversal: Compares nested structures at any depth
  • Path Tracking: Shows exact location of changes using dot notation
  • Order Independence: Map/object key ordering doesn't affect comparison

Exit Codes

  • 0: No differences found
  • 1: Differences found or error occurred

Command Line Options

Usage: go-config-diff [options] <file1> <file2>

Options:
  -format string
        Output format: colored, plain, json (default "colored")
  -summary
        Show summary of changes
  -version
        Show version information

Use Cases

  • 🔧 DevOps: Compare configuration files across environments
  • 🚀 CI/CD: Validate configuration changes in pipelines
  • 🔍 Auditing: Review configuration differences for compliance
  • 🐛 Debugging: Identify configuration drift between systems
  • 📦 Releases: Verify configuration changes before deployment

Development

Running Tests

go test ./... -v

Project Structure

go-config-diff/
├── cmd/
│   └── go-config-diff/     # CLI application
│       └── main.go
├── pkg/
│   ├── ast/                # Unified AST model
│   │   ├── ast.go
│   │   └── ast_test.go
│   ├── parser/             # Format parsers
│   │   ├── parser.go
│   │   └── parser_test.go
│   ├── diff/               # Comparison logic
│   │   ├── diff.go
│   │   └── diff_test.go
│   └── output/             # Output formatters
│       └── output.go
├── examples/               # Sample config files
└── README.md

License

This project is licensed under the GPL-3.0 License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Author

Max Base

Repository

https://github.com/BaseMax/go-config-diff