{"id":6406,"library":"pdiff","title":"Pdiff: Pretty side-by-side diff","description":"Pdiff is a command-line utility for generating pretty side-by-side differences between two text files. It is inspired by `ydiff` and `icdiff`, focusing on enhancing readability with color highlighting. The current version is 1.1.5, and it is actively maintained with infrequent but consistent updates.","status":"active","version":"1.1.5","language":"en","source_language":"en","source_url":"https://github.com/nkouevda/pdiff","tags":["diff","command-line","cli","text comparison","pretty print"],"install":[{"cmd":"pip install pdiff","lang":"bash","label":"PyPI"},{"cmd":"brew install nkouevda/nkouevda/pdiff","lang":"bash","label":"Homebrew (macOS)"}],"dependencies":[],"imports":[{"note":"Pdiff is designed as a standalone command-line utility for console usage, not a Python library with a direct `import`able API.","symbol":"pdiff (command-line)","correct":"This library is primarily a command-line tool and does not expose a Python API for direct import and programmatic use within Python scripts. It should be invoked via a subprocess if used from Python."}],"quickstart":{"code":"import subprocess\nimport os\n\n# Create dummy files for demonstration\nfile1_content = \"\"\"Line 1: Hello world\nLine 2: This is a test file.\nLine 3: Some text that is different.\nLine 4: Common line.\n\"\"\"\n\nfile2_content = \"\"\"Line 1: Hello world!\nLine 2: This is a modified test file.\nLine 3: Completely new line here.\nLine 4: Common line.\nLine 5: An extra line in file2.\n\"\"\"\n\nwith open('file1.txt', 'w') as f:\n    f.write(file1_content)\n\nwith open('file2.txt', 'w') as f:\n    f.write(file2_content)\n\nprint(\"Running pdiff on file1.txt and file2.txt:\\n\")\n\ntry:\n    # Execute pdiff as a subprocess\n    # Use text=True (or universal_newlines=True for older Python) to capture stdout as string\n    # The '--' separates options from filenames, useful if filenames start with '-' or similar.\n    result = subprocess.run(['pdiff', '--', 'file1.txt', 'file2.txt'], capture_output=True, text=True, check=True)\n    print(result.stdout)\nexcept subprocess.CalledProcessError as e:\n    print(f\"Error running pdiff: {e.stderr}\")\nexcept FileNotFoundError:\n    print(\"Error: 'pdiff' command not found. Please ensure pdiff is installed and in your PATH.\")\nfinally:\n    # Clean up dummy files\n    if os.path.exists('file1.txt'):\n        os.remove('file1.txt')\n    if os.path.exists('file2.txt'):\n        os.remove('file2.txt')\n","lang":"python","description":"Pdiff is invoked from the command line. This quickstart demonstrates how to use `subprocess.run` in Python to execute `pdiff` and capture its output, comparing two temporary text files. Remember to have `pdiff` installed and available in your system's PATH for this to work."},"warnings":[{"fix":"Use `subprocess.run()` to execute `pdiff` as an external command, passing file paths as arguments, and capture its `stdout` for processing.","message":"Pdiff is fundamentally a command-line interface (CLI) tool. It does not provide a Python API for direct programmatic interaction (e.g., `import pdiff` to use functions or classes). Users expecting a traditional Python library for in-script diffing should be aware that `pdiff` must be invoked via `subprocess` or similar methods.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If piping, use tools that support ANSI escape codes (e.g., `less -R`). For programmatic capture, be prepared to strip ANSI codes if plain text is desired, or ensure the receiving environment can interpret them.","message":"The output of `pdiff` utilizes ANSI escape codes for color highlighting, which are intended for terminal display. When piping the output to other tools or redirecting it to a file, these color codes may not render correctly or might appear as raw control characters. Using `less -R` is often recommended for viewing piped output.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always quote filenames (e.g., `pdiff \"file with spaces.txt\" other_file.txt`). When using `subprocess.run` in Python, pass filenames as separate elements in a list, which handles quoting automatically (e.g., `['pdiff', 'file with spaces.txt', 'other_file.txt']`).","message":"When invoking `pdiff` from the command line, especially with filenames containing spaces or special characters, proper shell escaping or quoting is crucial. Failure to do so can lead to `FileNotFoundError` or incorrect file parsing.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}