Metadata-Version: 2.4
Name: difflicious
Version: 0.11.0
Summary: A sleek web-based git diff visualization tool for developers
Project-URL: Homepage, https://github.com/insipid/difflicious
Project-URL: Repository, https://github.com/insipid/difflicious
Project-URL: Issues, https://github.com/insipid/difflicious/issues
Project-URL: Documentation, https://github.com/insipid/difflicious#readme
Project-URL: Changelog, https://github.com/insipid/difflicious/blob/main/CHANGELOG.md
Author: Drew
License: MIT
License-File: LICENSE
Keywords: development,diff,git,visualization,web
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Flask
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: Text Processing :: General
Requires-Python: >=3.9
Requires-Dist: click<9.0,>=8.0.0
Requires-Dist: flask<3.0,>=2.3.0
Requires-Dist: gitpython<4.0,>=3.1.40
Requires-Dist: jinja-partials<1.0,>=0.2.0
Requires-Dist: markupsafe<3.0,>=2.1.0
Requires-Dist: pygments<3.0,>=2.17.0
Requires-Dist: unidiff<1.0,>=0.7.5
Requires-Dist: watchdog<4.0,>=3.0.0
Description-Content-Type: text/markdown

# Difflicious

[![PyPI version](https://img.shields.io/pypi/v/difflicious.svg)](https://pypi.org/project/difflicious/)
[![Python versions](https://img.shields.io/pypi/pyversions/difflicious.svg)](https://pypi.org/project/difflicious/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A sleek web-based git diff visualization tool used when working locally on branches. Difflicious provides a lightweight local web application that transforms git diffs into an intuitive, interactive experience.

<!-- TODO: Add screenshots showing light and dark mode side-by-side diff views -->
<!-- ![Difflicious Screenshot](docs/screenshots/difflicious-demo.png) -->

## What is Difflicious?

Difflicious is a developer-focused tool that runs locally and provides a beautiful interface for viewing git changes. Instead of squinting at terminal output, you get a clean, searchable, and toggleable view of your work-in-progress changes.

Perfect for:
- Reviewing changes before committing
- Understanding complex diffs across multiple files
- Quickly navigating through modifications in your current branch
- Getting a bird's-eye view of your development progress

## Features

- **Side-by-Side Diff Visualization**: Professional-grade side-by-side view with accurate line numbering
- **Syntax Highlighting**: Beautiful code highlighting for 100+ programming languages using Pygments
- **Intelligent Diff Parsing**: Advanced git diff parser with proper alignment of additions and deletions
- **Smart UI Controls**: Expand/collapse all buttons with intelligent disabled states
- **Interactive Interface**: Toggle visibility, search through changes, and filter content
- **Clean File Paths**: Automatic removal of git diff artifacts (a/, b/ prefixes)
- **Secure Git Integration**: Safe git command execution with subprocess sanitization
- **Real-time Status**: Live git repository status and branch information
- **Modern UI**: Clean Tailwind CSS design with responsive layout
- **Lightweight**: Minimal infrastructure using Flask backend and Alpine.js frontend
- **Developer-Friendly**: Designed by developers, for developers

## Installation & Quick Start

### Option 1: Install from PyPI (Recommended)
```bash
# Install via pip
pip install difflicious

# Run the application
difflicious

# Open your browser to localhost:5000
```

### Option 2: Docker (Containerized)
```bash
# Pull and run the Docker image
docker run -p 5000:5000 -v $(pwd):/workspace insipid/difflicious:latest

# Open your browser to localhost:5000
```

### Option 3: From Source (Development)
```bash
# Clone the repository
git clone https://github.com/insipid/difflicious.git
cd difflicious

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install dependencies
uv sync

# Run the application
uv run difflicious
```

## Font Customization

Difflicious supports beautiful programming fonts via Google Fonts CDN integration. You can customize the font used for code and diff content.

### Available Fonts

- **JetBrains Mono** (default) - Designed specifically for developers
- **Fira Code** - Popular programming font with ligatures
- **Source Code Pro** - Adobe's professional programming font
- **IBM Plex Mono** - Modern, clean monospace design
- **Roboto Mono** - Google's versatile monospace font
- **Inconsolata** - Humanist monospace font

### Font Configuration

Set the `DIFFLICIOUS_FONT` environment variable to choose your preferred font:

```bash
# Use Fira Code
export DIFFLICIOUS_FONT=fira-code
difflicious

# Use Source Code Pro
export DIFFLICIOUS_FONT=source-code-pro
difflicious

# List all available fonts
difflicious --list-fonts
```

### Available Font Keys

- `jetbrains-mono` - JetBrains Mono (default)
- `fira-code` - Fira Code
- `source-code-pro` - Source Code Pro  
- `ibm-plex-mono` - IBM Plex Mono
- `roboto-mono` - Roboto Mono
- `inconsolata` - Inconsolata

### Disable Google Fonts

If you prefer to use system fonts only (no external CDN requests):

```bash
export DIFFLICIOUS_DISABLE_GOOGLE_FONTS=true
difflicious
```

This will fall back to system monospace fonts like SF Mono, Cascadia Code, Monaco, and Consolas.

## Technology Stack

- **Backend**: Python Flask for minimal setup and excellent git integration
- **Frontend**: Alpine.js + Tailwind CSS for lightweight, declarative UI
- **Real-time**: Server-Sent Events for live git status updates
- **Security**: Proper subprocess sanitization for safe git command execution
- **Distribution**: Modern Python packaging (PyPI) and Docker containers
- **Development**: uv for fast Python package management and virtual environments

## Design System

Difflicious uses a themeable Tailwind-driven design system with semantic tokens.

- Design system overview: `docs/tailwind-design-system.md`
- CSS style guide: `docs/CSS-STYLE-GUIDE.md`

## Development Status

✅ **Production-ready diff visualization** - Advanced side-by-side interface implemented!

### Completed ✅
- Modern Python project structure with pyproject.toml and uv
- Flask backend with comprehensive API endpoints and blueprints
- Advanced git diff parser with side-by-side structure
- Professional side-by-side diff visualization interface
- Secure git command execution wrapper with subprocess sanitization
- Interactive Alpine.js frontend with modular architecture
- Tailwind CSS styling with light/dark theme support
- Syntax highlighting with Pygments for 100+ languages
- Docker containerization with multi-platform support
- PyPI package publishing with automated CI/CD
- Comprehensive test suite (135+ tests, 70%+ coverage)
- Real git integration (status, diff, branch detection, parsing)
- Context expansion for viewing more code around hunks
- Font customization with 6 programming fonts
- Real-time auto-reload with Server-Sent Events

### Future Enhancements 🚧
- Advanced search and filtering capabilities
- Keyboard shortcuts and accessibility improvements
- Sticky file headers during scroll

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on:

- Setting up the development environment
- Running tests and quality checks
- Code style and conventions
- Submitting pull requests

## License

MIT License - see LICENSE file for details.
