Improved Colored Diff

2.0.10 · active · verified Thu Apr 09

icdiff is a Python library and command-line utility for displaying diffs with improved colorization, making it easier to read changes side-by-side. It aims to be a more user-friendly alternative to traditional `diff` output. The current version is 2.0.10, and it maintains a fairly active release cadence with updates typically every few months.

Warnings

gotcha `icdiff` is primarily a command-line tool. While it offers a Python API, its main strength is interactive visualization. For purely programmatic diff parsing or generating diffs in non-console contexts, Python's built-in `difflib` might be more suitable or efficient, especially if raw diff data (not colored output) is needed.
Fix: Consider `difflib` for non-visual, programmatic diffing or when fine-grained control over diff algorithm is required without console-specific formatting.
gotcha The `fromfile` and `tofile` arguments in `ConsoleDiff.make_table()` are purely for display labels in the diff header (e.g., `--- old_version.txt`). They do not instruct `icdiff` to read content from actual files. You must provide the file content as lists of strings.
Fix: Always pass the actual content of the files as lists of strings (e.g., `file1.readlines()`) to `make_table()`. The `fromfile` and `tofile` arguments are just metadata for the output header.
gotcha By default, `ConsoleDiff` tries to output ANSI color codes. If you redirect `icdiff`'s output to a file or pipe it to another command, you might end up with escape codes in the output. While `icdiff`'s CLI often detects non-TTY, the Python API might require explicit handling.
Fix: When using `ConsoleDiff` programmatically and outputting to a non-TTY (like a file), instantiate it with `color=False` (e.g., `ConsoleDiff(color=False)`) to prevent ANSI escape codes from being included in the output.

Install

pip install icdiff Install latest version

Imports

ConsoleDiff
```
from icdiff import ConsoleDiff
```
This is the main class for programmatic diff generation with console-style output.

Quickstart

This quickstart demonstrates how to use `ConsoleDiff` to generate a colored, side-by-side diff between two lists of strings. It configures the diff for a specific column width, includes line numbers, and sets custom file labels for the header.

from icdiff import ConsoleDiff

old_text = [
    "line 1: hello world",
    "line 2: foo bar",
    "line 3: baz qux"
]

new_text = [
    "line 1: hello earth",
    "line 2: foo baz",
    "line 3: baz qux",
    "line 4: new line"
]

differ = ConsoleDiff(
    cols=80,  # Specify number of columns for display
    line_numbers=True, # Show line numbers
    color=True # Enable color output
)

diff_lines = differ.make_table(
    old_text,
    new_text,
    fromfile='old_version.txt',
    tofile='new_version.txt',
    context=True # Show context lines
)

for line in diff_lines:
    print(line)

view raw JSON →