Struct CodeDiff 

pub struct CodeDiff {
    pub file_path: Option<String>,
    pub hunks: Vec<DiffHunk>,
    pub config: DiffConfig,
    pub scroll_offset: usize,
    pub file_tree: DiffFileTree,
    pub file_diffs: HashMap<String, Vec<DiffHunk>>,
    pub show_sidebar: bool,
    pub sidebar_split: ResizableSplit,
    pub sidebar_focused: bool,
    pub theme: AppTheme,
}

A widget for displaying code diffs in a terminal UI.

CodeDiff renders diff hunks in a side-by-side format (like VS Code) or unified format, with support for syntax highlighting, line numbers, and visual markers for added/removed lines.

Layout

In side-by-side mode:

• Left panel shows the old/original version
• Right panel shows the new/modified version
• Lines are aligned horizontally for easy comparison
• Empty spaces fill gaps where lines were added/removed

When sidebar is enabled:

• Left panel shows file tree with status markers
• Right panel shows the diff for the selected file
• [ key toggles sidebar visibility
• h/l keys switch focus between sidebar and diff

Visual Elements

• Green background for added lines (+)
• Red background for removed lines (-)
• Gray header bars for hunk information
• Line numbers on each side

Fields

• file_path - Optional path to the file being diffed (for single-file mode)
• hunks - Collection of diff hunks to display (for single-file mode)
• config - Display configuration (colors, style, sidebar options)
• scroll_offset - Current vertical scroll position
• file_tree - Internal file tree widget for sidebar
• file_diffs - Map of file paths to their diff hunks (for multi-file mode)
• show_sidebar - Whether sidebar is currently visible
• sidebar_split - Resizable split for sidebar/diff area division with mouse drag support
• sidebar_focused - Whether sidebar has focus (vs diff view)

Fields

file_path: Option<String>

Optional path to the file being diffed (single-file mode).

hunks: Vec<DiffHunk>

The diff hunks to display (single-file mode).

config: DiffConfig

Display configuration.

scroll_offset: usize

Current vertical scroll offset.

file_tree: DiffFileTree

Internal file tree widget for sidebar.

file_diffs: HashMap<String, Vec<DiffHunk>>

Map of file paths to their diff hunks (multi-file mode).

show_sidebar: bool

Whether the sidebar is currently visible.

sidebar_split: ResizableSplit

Resizable split for sidebar/diff area division with mouse drag support.

sidebar_focused: bool

Whether the sidebar has focus (vs diff view).

theme: AppTheme

Application theme for styling.

Implementations

impl CodeDiff

pub fn from_git() -> Self

Create a CodeDiff from the current git repository’s diff.

Tries in order:

1. Unstaged changes (git diff)
2. Staged changes (git diff --cached)
3. Last commit (git diff HEAD~1)

Returns an empty CodeDiff if not in a git repo or no changes found.

Example

use ratatui_toolkit::code_diff::CodeDiff;

// Create a diff widget from current git changes
let diff = CodeDiff::from_git();

pub fn from_git_with_config(config: DiffConfig) -> Self

Create a CodeDiff from git with custom config.

This is a convenience method that combines from_git() with with_config().

Example

use ratatui_toolkit::code_diff::{CodeDiff, DiffConfig};

let diff = CodeDiff::from_git_with_config(
    DiffConfig::new()
        .sidebar_enabled(true)
        .show_line_numbers(true)
);

impl CodeDiff

pub fn from_multi_file_diff(diff_text: &str) -> Self

Creates a diff widget by parsing multi-file git diff output.

Parses output from git diff that may contain multiple files:

diff --git a/file1.rs b/file1.rs
--- a/file1.rs
+++ b/file1.rs
@@ -1,4 +1,5 @@
...
diff --git a/file2.rs b/file2.rs
--- a/file2.rs
+++ b/file2.rs
@@ -1,3 +1,4 @@
...

The sidebar is automatically enabled when multiple files are detected.

Arguments

• diff_text - The multi-file diff text to parse

Returns

A new CodeDiff instance with parsed files and sidebar enabled

Example

use ratatui_toolkit::code_diff::CodeDiff;

let diff_text = r#"diff --git a/src/lib.rs b/src/lib.rs
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,4 @@
 fn main() {
+    println!("Hello");
 }
diff --git a/src/utils.rs b/src/utils.rs
new file mode 100644
--- /dev/null
+++ b/src/utils.rs
@@ -0,0 +1,3 @@
+pub fn helper() {
+}
"#;

let widget = CodeDiff::from_multi_file_diff(diff_text);

impl CodeDiff

pub fn from_unified_diff(diff_text: &str) -> Self

Creates a diff widget by parsing unified diff format text.

Parses the standard unified diff format used by git diff, diff -u, etc.

Arguments

• diff_text - The unified diff text to parse

Returns

A new CodeDiff instance with parsed hunks

Example

use ratatui_toolkit::code_diff::CodeDiff;

let diff_text = r#"
--- a/file.txt
+++ b/file.txt
@@ -1,4 +1,5 @@
 context line
-removed line
+added line
 more context
"#;

let diff = CodeDiff::from_unified_diff(diff_text);
assert!(!diff.hunks.is_empty());

impl CodeDiff

pub fn new() -> Self

Creates a new empty diff widget.

Returns

A new CodeDiff instance with no hunks and default configuration

Example

use ratatui_toolkit::code_diff::CodeDiff;

let diff = CodeDiff::new();
assert!(diff.hunks.is_empty());

impl CodeDiff

pub fn with_config(self, config: DiffConfig) -> Self

Sets the configuration for this diff widget.

This also updates the sidebar state based on the new config:

• show_sidebar is set from config.sidebar_enabled
• sidebar_width_percent is set from config.sidebar_default_width

Arguments

• config - The display configuration to use

Returns

Self for method chaining

Example

use ratatui_toolkit::code_diff::{CodeDiff, DiffConfig};

let config = DiffConfig::new()
    .show_line_numbers(false)
    .sidebar_enabled(true);
let diff = CodeDiff::new().with_config(config);

impl CodeDiff

pub fn with_file(self, path: &str, status: FileStatus, diff_text: &str) -> Self

Adds a file with its diff to the widget.

This is used for multi-file diffs. The file will appear in the sidebar file tree with the specified status, and its diff content will be stored for display when selected.

Arguments

• path - The file path to display
• status - The file’s modification status (Modified, Added, Deleted, Renamed)
• diff_text - The unified diff text for this file

Returns

Self for method chaining

Example

use ratatui_toolkit::code_diff::{CodeDiff, DiffConfig};
use ratatui_toolkit::widgets::code_diff::diff_file_tree::FileStatus;

let diff_text = r#"--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,4 @@
 fn main() {
+    println!("Hello");
 }
"#;

let widget = CodeDiff::new()
    .with_config(DiffConfig::new().sidebar_enabled(true))
    .with_file("src/lib.rs", FileStatus::Modified, diff_text);

impl CodeDiff

pub fn with_file_path(self, path: impl Into<String>) -> Self

Sets the file path for this diff.

Arguments

• path - The file path to display in the header

Returns

Self for method chaining

Example

use ratatui_toolkit::code_diff::CodeDiff;

let diff = CodeDiff::new().with_file_path("src/main.rs");

impl CodeDiff

pub fn with_theme(self, theme: &AppTheme) -> Self

Sets the application theme for styling.

This method applies the theme colors to the diff widget, including borders, backgrounds, and text colors.

Arguments

• theme - The application theme to use

Returns

Self for method chaining

Example

use ratatui_toolkit::code_diff::CodeDiff;
use ratatui_toolkit::services::theme::AppTheme;

let theme = AppTheme::default();
let diff = CodeDiff::new().with_theme(&theme);

pub fn apply_theme(&mut self, theme: &AppTheme)

Applies a theme to the existing widget (non-consuming).

Arguments

• theme - The application theme to apply

impl CodeDiff

pub fn add_hunk(&mut self, hunk: DiffHunk)

Adds a diff hunk to this widget.

Arguments

• hunk - The diff hunk to add

Example

use ratatui_toolkit::code_diff::{CodeDiff, DiffHunk, DiffLine};

let mut diff = CodeDiff::new();
let mut hunk = DiffHunk::new(1, 2, 1, 3);
hunk.add_line(DiffLine::context("unchanged", 1, 1));
diff.add_hunk(hunk);

impl CodeDiff

pub fn added_count(&self) -> usize

Returns the total number of added lines across all hunks.

Returns

The count of all added lines

Example

use ratatui_toolkit::code_diff::CodeDiff;

let diff = CodeDiff::from_unified_diff("@@ -1 +1,2 @@\n+added");
assert_eq!(diff.added_count(), 1);

impl CodeDiff

pub fn handle_key(&mut self, key: KeyCode) -> bool

Handles a keyboard event and returns whether it was consumed.

Key Bindings

• [ - Toggle sidebar visibility
• Tab - Switch focus between sidebar and diff
• / - Enter filter mode (sidebar only)
• h - Collapse expanded directory, or go to parent if collapsed (sidebar only, no-op on files)
• l - Expand collapsed directory, or show diff for files (sidebar only)
• j / Down - Navigate down (files in sidebar, scroll in diff)
• k / Up - Navigate up (files in sidebar, scroll in diff)
• g - Go to top (first file or top of diff)
• G - Go to bottom (last file or bottom of diff)
• Space / Enter - Toggle directory expand / select file (sidebar only)
• H / < - Decrease sidebar width
• L / > - Increase sidebar width
• r - Refresh diff from git

Filter Mode

When filter mode is active (triggered by /):

• Esc - Clear filter and exit filter mode
• Enter - Exit filter mode (keep filter active)
• Backspace - Delete last character
• Any character - Append to filter

Arguments

• key - The key code that was pressed

Returns

true if the key was handled, false otherwise

Example

use crossterm::event::KeyCode;
use ratatui_toolkit::code_diff::{CodeDiff, DiffConfig};

let mut diff = CodeDiff::new()
    .with_config(DiffConfig::new().sidebar_enabled(true));

// Toggle sidebar
diff.handle_key(KeyCode::Char('['));

// Navigate
diff.handle_key(KeyCode::Char('j'));

// Enter filter mode
diff.handle_key(KeyCode::Char('/'));

impl CodeDiff

pub fn handle_mouse(&mut self, event: MouseEvent, area: Rect) -> bool

Handles mouse events for sidebar resizing.

Supports mouse drag to resize the sidebar divider using ResizableSplit’s built-in drag handling.

Arguments

• event - The mouse event to handle
• area - The area the widget is rendered in

Returns

true if the event was handled (consumed), false otherwise

Example

use crossterm::event::{Event, MouseEvent};
use ratatui::layout::Rect;
use ratatui_toolkit::code_diff::{CodeDiff, DiffConfig};

let mut diff = CodeDiff::new()
    .with_config(DiffConfig::new().sidebar_enabled(true));

// In your event loop:
// if let Event::Mouse(mouse) = event {
//     let area = Rect::new(0, 0, 100, 50);
//     if diff.handle_mouse(mouse, area) {
//         // Mouse event was handled
//     }
// }

impl CodeDiff

pub fn is_sidebar_dragging(&self) -> bool

Returns whether the sidebar divider is currently being dragged.

This can be used to adjust polling rate for smooth dragging.

impl CodeDiff

pub fn is_sidebar_hovering(&self) -> bool

Returns whether the mouse is hovering over the sidebar divider.

This can be used to change the cursor style.

impl CodeDiff

pub fn refresh(&mut self)

Refresh the diff from the current git repository.

This re-fetches the git diff and updates the widget state while preserving the current configuration and sidebar visibility.

Example

use ratatui_toolkit::code_diff::CodeDiff;

let mut diff = CodeDiff::from_git();

// User makes changes to files...

// Refresh to pick up new changes
diff.refresh();

impl CodeDiff

pub fn refresh_if_changed(&mut self, watcher: &mut RepoWatcher) -> bool

Refresh the diff if the repository watcher detected changes.

Returns true when a refresh occurred.

Example

use ratatui_toolkit::code_diff::CodeDiff;
use ratatui_toolkit::services::repo_watcher::RepoWatcher;
use std::path::Path;

let mut diff = CodeDiff::from_git();
let mut watcher = RepoWatcher::new().unwrap();
watcher.watch(Path::new("."))?;

if diff.refresh_if_changed(&mut watcher) {
    println!("Diff updated");
}

impl CodeDiff

pub fn removed_count(&self) -> usize

Returns the total number of removed lines across all hunks.

Returns

The count of all removed lines

Example

use ratatui_toolkit::code_diff::CodeDiff;

let diff = CodeDiff::from_unified_diff("@@ -1,2 +1 @@\n-removed");
assert_eq!(diff.removed_count(), 1);

impl CodeDiff

pub fn resize_sidebar(&mut self, delta: i16)

Adjusts the sidebar width by a delta percentage.

Positive delta increases width, negative decreases. The width is clamped to the ResizableSplit’s min/max values.

Arguments

• delta - The change in width percentage (positive = wider, negative = narrower)

Example

use ratatui_toolkit::code_diff::{CodeDiff, DiffConfig};

let mut diff = CodeDiff::new()
    .with_config(DiffConfig::new().sidebar_enabled(true));

diff.resize_sidebar(5);  // Make 5% wider
diff.resize_sidebar(-3); // Make 3% narrower

impl CodeDiff

pub fn scroll_down(&mut self, lines: usize)

Scrolls down by the specified number of lines.

The scroll is clamped to the maximum scrollable position.

Arguments

• lines - Number of lines to scroll down

Example

use ratatui_toolkit::code_diff::CodeDiff;

let mut diff = CodeDiff::new();
diff.scroll_down(5);
// scroll_offset is now 5 (or less if content is shorter)

impl CodeDiff

pub fn scroll_up(&mut self, lines: usize)

Scrolls up by the specified number of lines.

Arguments

• lines - Number of lines to scroll up

Example

use ratatui_toolkit::code_diff::CodeDiff;

let mut diff = CodeDiff::new();
diff.scroll_offset = 10;
diff.scroll_up(3);
assert_eq!(diff.scroll_offset, 7);

impl CodeDiff

pub fn select_next_file(&mut self)

Selects the next file in the sidebar file tree.

This also updates the current diff hunks to show the selected file. If already at the last file, stays at the last file.

Example

use ratatui_toolkit::code_diff::{CodeDiff, DiffConfig};
use ratatui_toolkit::widgets::code_diff::diff_file_tree::FileStatus;

let mut diff = CodeDiff::new()
    .with_config(DiffConfig::new().sidebar_enabled(true))
    .with_file("file1.rs", FileStatus::Modified, "")
    .with_file("file2.rs", FileStatus::Added, "");

diff.select_next_file();

impl CodeDiff

pub fn select_prev_file(&mut self)

Selects the previous file in the sidebar file tree.

This also updates the current diff hunks to show the selected file. If already at the first file, stays at the first file.

Example

use ratatui_toolkit::code_diff::{CodeDiff, DiffConfig};
use ratatui_toolkit::widgets::code_diff::diff_file_tree::FileStatus;

let mut diff = CodeDiff::new()
    .with_config(DiffConfig::new().sidebar_enabled(true))
    .with_file("file1.rs", FileStatus::Modified, "")
    .with_file("file2.rs", FileStatus::Added, "");

diff.select_next_file();
diff.select_prev_file(); // Back to first file

impl CodeDiff

pub fn set_scroll(&mut self, offset: usize)

Sets the scroll offset to a specific value.

The offset is clamped to valid bounds.

Arguments

• offset - The scroll offset to set

Example

use ratatui_toolkit::code_diff::CodeDiff;

let mut diff = CodeDiff::new();
diff.set_scroll(10);

impl CodeDiff

pub fn stats_text(&self) -> String

Returns a formatted stats string (e.g., “+5 -3”).

Returns

A string showing the added and removed line counts

Example

use ratatui_toolkit::code_diff::{CodeDiff, DiffHunk, DiffLine};

let mut diff = CodeDiff::new();
let mut hunk = DiffHunk::new(1, 1, 1, 2);
hunk.add_line(DiffLine::removed("old", 1));
hunk.add_line(DiffLine::added("new1", 1));
hunk.add_line(DiffLine::added("new2", 2));
diff.add_hunk(hunk);
assert_eq!(diff.stats_text(), "+2 -1");

impl CodeDiff

pub fn toggle_focus(&mut self)

Toggles focus between the sidebar and diff view.

When sidebar is focused, navigation keys move through files. When diff view is focused, navigation keys scroll the diff.

Example

use ratatui_toolkit::code_diff::{CodeDiff, DiffConfig};

let mut diff = CodeDiff::new()
    .with_config(DiffConfig::new().sidebar_enabled(true));

assert!(diff.sidebar_focused);
diff.toggle_focus();
assert!(!diff.sidebar_focused);

impl CodeDiff

pub fn toggle_sidebar(&mut self)

Toggles the sidebar visibility.

When toggled off, the entire area is used for the diff display. When toggled on, the file tree sidebar appears on the left.

This method only has an effect when config.sidebar_enabled is true.

Example

use ratatui_toolkit::code_diff::{CodeDiff, DiffConfig};

let mut diff = CodeDiff::new()
    .with_config(DiffConfig::new().sidebar_enabled(true));

assert!(diff.show_sidebar);
diff.toggle_sidebar();
assert!(!diff.show_sidebar);

impl CodeDiff

pub fn total_lines(&self) -> usize

Returns the total number of lines to display.

This includes all lines from all hunks plus hunk header lines.

Returns

The total line count for rendering

Example

use ratatui_toolkit::code_diff::CodeDiff;

let diff = CodeDiff::new();
assert_eq!(diff.total_lines(), 0);

Trait Implementations

impl Clone for CodeDiff

fn clone(&self) -> CodeDiff

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CodeDiff

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for CodeDiff

fn default() -> Self

Creates a default empty diff widget.

Returns

A new CodeDiff instance with no hunks and default configuration

impl Widget for &CodeDiff

fn render(self, area: Rect, buf: &mut Buffer)

Renders the diff widget from a reference.

impl Widget for CodeDiff

fn render(self, area: Rect, buf: &mut Buffer)

Renders the diff widget to the given buffer.

The widget renders:

1. If sidebar enabled and visible: file tree on left, diff on right
2. Otherwise: just the diff content

Each panel includes:

• A header bar with file path and stats (if file path is set)
• Diff hunks in the configured style (side-by-side or unified)

Arguments

• area - The area to render the widget in
• buf - The buffer to render to