### Developer Quick Start with Make

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/BUILD.md

For developers with CMake installed, use 'make' to build the project and generate standalone scripts, or 'make test' to run all tests.

```bash
make              # Build + generate standalone scripts
make test         # Run all tests
```

--------------------------------

### Example Diff Tool Usage

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/development/03-build-and-platform/vscode-extraction-tool.md

This example demonstrates creating test files and then running the diff tool to compare them.

```bash
# Create test files
echo "line1" > test1.txt
echo "line2" > test2.txt

# Run diff
node vscode-diff.mjs test1.txt test2.txt
```

--------------------------------

### Install Library

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/development/03-build-and-platform/automatic-installation.md

Use this command to install or update the library to match the version specified in the VERSION file.

```vim
:CodeDiff install
```

--------------------------------

### Verify Installation

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/development/03-build-and-platform/automatic-installation.md

Command to list the installed library files and verify that the correct version is present after installation.

```bash
ls -lh libvscode_diff_*
```

--------------------------------

### Initialize Codediff.nvim with Setup Function

Source: https://github.com/esmuellert/codediff.nvim/blob/main/doc/codediff.txt

The primary entry point for configuring codediff.nvim is the `setup` function. Pass your configuration options as a table.

```lua
require("codediff").setup({ ... })
```

--------------------------------

### Minimal codediff.nvim Installation with lazy.nvim

Source: https://github.com/esmuellert/codediff.nvim/blob/main/README.md

Use this minimal configuration for a quick setup of codediff.nvim with lazy.nvim. The plugin automatically adapts to your colorscheme's background.

```lua
{
  "esmuellert/codediff.nvim",
  cmd = "CodeDiff",
}
```

--------------------------------

### Manual Download and Installation of libgomp

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/dependency-distribution.md

Instructions for manually downloading and placing the libgomp library in the plugin directory. This is a fallback if system installation or automatic download is not feasible.

```bash
# Option 2: Manual download
cd ~/.local/share/nvim/lazy/codediff.nvim
curl -LO https://github.com/esmuellert/codediff.nvim/releases/download/v{VERSION}/libgomp_linux_{arch}_{VERSION}.so.1
mv libgomp_linux_* libgomp.so.1
```

--------------------------------

### Full Diff Rendering Example (Lua)

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/rendering-quick-reference.md

Sets up highlights, computes the diff between two lists of strings, creates Neovim buffers, and renders the diff results. This is a comprehensive example demonstrating the integration of diff computation and rendering.

```lua
local diff = require('vscode-diff.diff')
local render = require('vscode-diff.render')

render.setup_highlights()

local original = {"line 1", "line 2 to delete", "line 3"}
local modified = {"line 1", "line 3", "line 4 added"}

local diff_result = diff.compute_diff(original, modified)
local bufnr_left = vim.api.nvim_create_buf(false, true)
local bufnr_right = vim.api.nvim_create_buf(false, true)

render.render_diff(bufnr_left, bufnr_right, original, modified, diff_result)
-- Should show:
-- - Left: red backgrounds on lines 2-3
-- - Right: green backgrounds on lines 2-3, filler after line 1
```

--------------------------------

### Lazy.nvim Installation Configuration

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/development/01-origins/mvp-implementation-plan.md

This Lua configuration snippet is used within a Lazy.nvim setup to install the nvim-vscode-diff plugin. It specifies the repository, build command, and a placeholder for post-configuration logic.

```lua
{
  "yourusername/nvim-vscode-diff",
  build = "make",
  config = function()
    -- Plugin is ready to use
  end
}

```

--------------------------------

### Full CodeDiff.nvim Setup Configuration

Source: https://github.com/esmuellert/codediff.nvim/blob/main/doc/codediff.txt

Comprehensive setup for CodeDiff.nvim, including highlights, diff settings, explorer options, and extensive keymaps for various modes.

```lua
require("codediff").setup({
  highlights = {
    line_insert = "DiffAdd",
    line_delete = "DiffDelete",
    char_insert = nil,
    char_delete = nil,
    char_brightness = nil,
    conflict_sign = nil,
    conflict_sign_resolved = nil,
    conflict_sign_accepted = nil,
    conflict_sign_rejected = nil,
  },
  diff = {
    layout = "side-by-side",
    disable_inlay_hints = true,
    max_computation_time_ms = 5000,
    hide_merge_artifacts = false,
    conflict_result_position = "bottom",
    conflict_result_height = 30,
    conflict_result_width_ratio = { 1, 1, 1 },
    jump_to_first_change = true,
    highlight_priority = 100,
    compute_moves = false,
    compact_context_lines = 3,
    compact_sync_folds = true,
    cycle_hunks_across_files = false,
  },
  explorer = {
    position = "left",
    hidden = false,
    width = 40,
    height = 15,
    auto_refresh = true,
    auto_open_on_cursor = false,
    indent_markers = true,
    icons = {
      folder_closed = "",
      folder_open = "",
    },
    view_mode = "list",
    flatten_dirs = true,
    file_filter = {
      ignore = { ".git/**", ".jj/**" },
    },
    status_right_margin = 1,
    visible_groups = {
      staged = true,
      unstaged = true,
      conflicts = true,
    },
  },
  keymaps = {
    view = {
      quit = "q",
      toggle_explorer = "<leader>b",
      focus_explorer = "<leader>e",
      next_hunk = "]c",
      prev_hunk = "[c",
      next_file = "]f",
      prev_file = "[f",
      diff_get = "do",
      diff_put = "dp",
      open_in_prev_tab = "gf",
      close_on_open_in_prev_tab = false,
      toggle_stage = "-",
      hunk_textobject = "ih",
      show_help = "g?",
      align_move = "gm",
      toggle_layout = "t",
      toggle_compact = "gc",
    },
    explorer = {
      select = "<CR>",
      hover = "K",
      refresh = "R",
      toggle_view_mode = "i",
      stage_all = "S",
      unstage_all = "U",
      restore = "X",
      toggle_changes = "gu",
      toggle_staged = "gs",
      fold_open = "zo",
      fold_open_recursive = "zO",
      fold_close = "zc",
      fold_close_recursive = "zC",
      fold_toggle = "za",
      fold_toggle_recursive = "zA",
      fold_open_all = "zR",
      fold_close_all = "zM",
    },
    history = {
      select = "<CR>",
      toggle_view_mode = "i",
      fold_open = "zo",
      fold_open_recursive = "zO",
      fold_close = "zc",
      fold_close_recursive = "zC",
      fold_toggle = "za",
      fold_toggle_recursive = "zA",
      fold_open_all = "zR",
      fold_close_all = "zM",
    },
    conflict = {
      accept_incoming = "<leader>ct",
      accept_current = "<leader>co",
      accept_both = "<leader>cb",
      discard = "<leader>cx",
      next_conflict = "]x",
      prev_conflict = "[x",
      diffget_incoming = "2do",
      diffget_current = "3do",
    },
  },
})
```

--------------------------------

### Conditionally Install libgomp

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/dependency-distribution.md

Downloads and installs the bundled libgomp.so.1 if the system does not already have it, ensuring the plugin can run.

```lua
local function install_libgomp_if_needed(opts)
  -- Check if already bundled
  if bundled then return true end
  
  -- Check if system has it
  if check_system_libgomp() then
    return true  -- No need to bundle
  end
  
  -- Download from releases
  local url = "https://github.com/.../libgomp_linux_{arch}_{version}.so.1"
  download_file(url, "libgomp.so.1")
  
  return true  -- Never fail installation
end
```

--------------------------------

### Manual Version Bumping and Tagging

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/VERSION_MANAGEMENT.md

A step-by-step guide for manually bumping the version, committing changes, and tagging the release.

```bash
make bump-minor

git add VERSION
git commit -m "Bump version to $(cat VERSION)"
git tag v$(cat VERSION)
```

--------------------------------

### CodeDiff Setup

Source: https://github.com/esmuellert/codediff.nvim/blob/main/doc/codediff.txt

The primary entry point for setting up the CodeDiff plugin. Accepts a table for configuration options.

```APIDOC
## require("codediff").setup({ ... })

### Description
This is the main function to initialize and configure the CodeDiff plugin. It accepts a table of options to customize its behavior.

### Method
`require("codediff").setup

### Parameters
- `options` (table) - Optional - A table containing configuration options for CodeDiff.
```

--------------------------------

### Feature Release Example

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/VERSION_MANAGEMENT.md

Example workflow for releasing a new feature, including committing the feature, bumping the minor version, and creating the release tag.

```bash
# Add feature
git commit -m "Add async git diff support"

# Bump minor version (0.3.1 → 0.4.0)
make bump-minor

# Release
git add VERSION
git commit -m "Release v0.4.0"
git tag v0.4.0
git push && git push --tags
```

--------------------------------

### Install Neo-tree with lazy.nvim

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/development/04-lua-features/file-sidebar-research.md

This Lua code snippet shows how to install the Neo-tree plugin using the lazy.nvim package manager, including recommended dependencies.

```lua
-- Using lazy.nvim
{
  "nvim-neo-tree/neo-tree.nvim",
  branch = "v3.x",
  dependencies = {
    "nvim-lua/plenary.nvim",
    "MunifTanjim/nui.nvim",
    "nvim-tree/nvim-web-devicons", -- optional but recommended
  }
}
```

--------------------------------

### User Quick Start without CMake

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/BUILD.md

Users without CMake can directly execute the pre-generated standalone build scripts for their respective platforms.

```bash
./libvscode-diff/build.sh       # Unix/Linux/macOS
libvscode-diff\build.cmd        # Windows
```

--------------------------------

### Integrate libgomp Installation into Plugin Install

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/dependency-distribution.md

Ensures that libgomp is checked and installed if necessary after the main plugin library has been installed.

```lua
function M.install(opts)
  -- ... install main library ...
  
  -- Also check and install libgomp if needed
  install_libgomp_if_needed(opts)
  
  return true
end
```

--------------------------------

### Virtual File URL Example

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/development/04-lua-features/virtual-file-implementation.md

Provides a concrete example of a codediff:// URL, showing how a specific file in a project at a given commit is represented.

```text
codediff:////home/user/project///HEAD/src/file.lua
```

--------------------------------

### Lua Configuration and Functions

Source: https://github.com/esmuellert/codediff.nvim/blob/main/scripts/test_pairs/block_moved_down/modified.txt

Defines configuration variables and basic functions for setup, running, and cleanup operations.

```lua
local config = {}

function run()
    print("running")
end

function cleanup()
    print("done")
end

function setup()
    config.enabled = true
    config.debug = false
    config.timeout = 5000
end
```

--------------------------------

### Install System libgomp

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/dependency-distribution.md

Provides commands to install the libgomp system package on various Linux distributions. This is a primary solution if the automatic download fails.

```bash
# Option 1: Install system package
sudo apt install libgomp1          # Debian/Ubuntu
sudo yum install libgomp           # CentOS/RHEL
sudo pacman -S gcc-libs            # Arch Linux
```

--------------------------------

### Error Message: No Download Tool Found

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/development/03-build-and-platform/automatic-installation.md

Example error message indicating that no compatible download tool (curl, wget, or PowerShell) is available.

```text
No download tool found. Please install curl or wget.
```

--------------------------------

### Versioned Library Filename Example

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/development/03-build-and-platform/automatic-installation.md

Illustrates how library filenames include the version number for easy identification and management.

```text
libvscode_diff_0.8.0.so
```

--------------------------------

### Direct Output Comparison Example

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/development/03-build-and-platform/vscode-extraction-tool.md

This command shows how to directly compare the output of the VSCode diff tool and a C implementation using process substitution and the diff command.

```bash
diff <(node vscode-diff.mjs f1 f2) <(./build/diff f1 f2)
```

--------------------------------

### File History Mode Examples

Source: https://github.com/esmuellert/codediff.nvim/blob/main/doc/codediff.txt

Displays the history of changes for a file. Supports various Git revisions and range specifications.

```vim
:CodeDiff history
:CodeDiff history HEAD~10
:CodeDiff history origin/main..HEAD
:CodeDiff history HEAD~20 %
:CodeDiff history HEAD~20 --reverse
```

--------------------------------

### Windows Standalone Build

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/BUILD.md

Execute the standalone build script on Windows for users who do not have CMake installed.

```cmd
build.cmd
```

--------------------------------

### Build codediff.nvim

Source: https://github.com/esmuellert/codediff.nvim/blob/main/README.md

Use this command to clean previous builds and compile the project. Ensure you have the necessary build tools installed.

```bash
make clean && make
```

--------------------------------

### Lua Configuration and Functions

Source: https://github.com/esmuellert/codediff.nvim/blob/main/scripts/test_pairs/block_moved_down/original.txt

Defines a configuration table and three functions for setup, execution, and cleanup. Useful for structuring simple Lua applications or modules.

```lua
-- Header comment
local config = {}

function setup()
    config.enabled = true
    config.debug = false
    config.timeout = 5000
end

function run()
    print("running")
end

function cleanup()
    print("done")
end
```

--------------------------------

### Add Plugin to Neovim Runtime Path

Source: https://github.com/esmuellert/codediff.nvim/blob/main/README.md

Append the manually installed plugin directory to Neovim's runtime path in your init.lua configuration.

```lua
vim.opt.rtp:append("~/.local/share/nvim/codediff.nvim")
```

--------------------------------

### Extmarks Layering Example

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/development/04-lua-features/rendering-evolution.md

Illustrates the layering of line and character highlight groups, showing how the top layer (character highlight) can stand out against the bottom layer (line highlight).

```text
Layer 1 (bottom):  line_hl_group
                   ┌─────────────────────────────┐
                   │ DARK BACKGROUND            │
                   └─────────────────────────────┘

Layer 2 (top):     hl_group (on text only)
                   ┌──────┐
                   │BRIGHT│ (empty) (empty)
                   └──────┘

Final render:      [BRIGHT][DARK][DARK][DARK]
                    ^^^^^^^ ← This stands out!
```

--------------------------------

### Error Message: Missing VERSION File

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/development/03-build-and-platform/automatic-installation.md

Example error message when the VERSION file is missing, preventing download URL construction.

```text
Failed to build download URL: Failed to read VERSION file at: /path/to/VERSION
```

--------------------------------

### Column Numbering Example

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/DIFF_NOTATION.md

Demonstrates the 1-based indexing used for character positions (columns) in diff notation, aligning with text editor cursor positions.

```text
Text:     "hello"
Position:  12345
Column:    C1 C2 C3 C4 C5
```

--------------------------------

### C Unit Test Output Example

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/development/01-origins/mvp-implementation-plan.md

This output shows the expected results from running C unit tests for the diffing functionality, indicating successful completion of various tests.

```text
# Expected output:
# Running C unit tests...
# ✓ Version test passed: 0.1.0
# ✓ Render plan lifecycle test passed
# ✓ Simple diff test passed
# ✓ Character-level diff test passed (LCS working!)
# All tests passed!
```

--------------------------------

### Setup Default Configuration (Quality Priority)

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/performance.md

Use this configuration when maximum detail is desired and occasional 1-2 second waits on huge diffs are acceptable. This sets the maximum computation time to 5 seconds.

```lua
require("vscode-diff").setup({
  diff = {
    max_computation_time_ms = 5000,  -- 5 seconds (VSCode default)
  }
})
```

--------------------------------

### Vim Command for CodeDiff Usage

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/development/01-origins/mvp-implementation-plan.md

This is an example of how to use the ':CodeDiff' command interactively within Vim or Neovim after the plugin is installed. It takes two file paths as arguments.

```vim
:CodeDiff file_a.txt file_b.txt

```

--------------------------------

### Lua Example: Gap Alignment Between Mappings

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/development/04-lua-features/rendering-evolution.md

Illustrates how gap alignments are formed between diff mappings to account for offsets in unchanged regions. This is crucial for correctly positioning fillers when there are discrepancies between the start of one mapping and the end of the previous one.

```lua
Alignment {
  orig: [36, 1216)   -- 1180 lines
  mod: [39, 1219)    -- 1180 lines
}
```

--------------------------------

### Character-Level Diff: Concrete Text Example

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/DIFF_NOTATION.md

Provides a concrete text example illustrating the character-level mapping for a word change.

```plaintext
Original: "hello world"
           123456789...
                 ^^^^^     (columns 7-11: "world")
                 
Modified: "hello universe"
           123456789...
                 ^^^^^^^^  (columns 7-14: "universe")
```

--------------------------------

### Build and Test Instructions

Source: https://github.com/esmuellert/codediff.nvim/blob/main/CMakeLists.txt

Prints status messages to the console, providing instructions on how to build the plugin, run C tests, and run Lua tests.

```cmake
message(STATUS "===========================================")
message(STATUS "  vscode-diff.nvim Plugin")
message(STATUS "===========================================")
message(STATUS "  Build the plugin:")
message(STATUS "    cmake -B build")
message(STATUS "    cmake --build build")
message(STATUS "")
message(STATUS "  Run C tests:")
message(STATUS "    cmake --build build --target test")
message(STATUS "    ctest --test-dir build")
message(STATUS "")
message(STATUS "  Run Lua tests:")
message(STATUS "    ./tests/run_tests.sh")
message(STATUS "    make test-lua")
message(STATUS "===========================================")
```

--------------------------------

### Revision Mode Examples

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/development/04-lua-features/explorer-mode.md

Examples of how to use the `:CodeDiff` command with a revision argument to compare the working tree against a specific commit, branch, or tag.

```lua
:CodeDiff HEAD~5
:CodeDiff main
:CodeDiff abc123
```

--------------------------------

### Download Method: PowerShell

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/development/03-build-and-platform/automatic-installation.md

Uses PowerShell as a fallback method on Windows to download the library binary.

```lua
{
  "powershell", "-NoProfile", "-Command",
  "Invoke-WebRequest -Uri 'url' -OutFile 'dest_path'"
}
```

--------------------------------

### Developer Build Options with Make

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/BUILD.md

Provides various 'make' targets for developers, including building, generating scripts, running specific tests, and cleaning the project.

```bash
make                    # Build + generate scripts
make generate-scripts   # Only generate scripts (no build)
make test              # Run all tests
make test-c            # C tests only
make test-lua          # Lua tests only
make clean             # Clean everything
```

--------------------------------

### Run All Tests

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/development/01-origins/development-notes.md

Execute all project tests using the make command. For verbose output during testing, use the nvim --headless command with the appropriate test file and the -v flag.

```bash
make test
```

```bash
nvim --headless -c "luafile tests/e2e_test.lua" -- -v
```

```bash
nvim --headless -c "luafile tests/test_filler.lua" -- -v
```

--------------------------------

### Show Current Version

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/VERSION_MANAGEMENT.md

Use this command to display the current version of the project.

```bash
make version
```

--------------------------------

### Setup Fast Mode Configuration (Speed Priority)

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/performance.md

Use this configuration for fast response times with minimal quality loss, retaining approximately 99% of the detail. This is recommended for most users, especially those working with large codebases, and sets the timeout to 1 second.

```lua
require("vscode-diff").setup({
  diff = {
    max_computation_time_ms = 1000,  -- 1 second
  }
})
```

--------------------------------

### Recommended File Operations

Source: https://github.com/esmuellert/codediff.nvim/blob/main/AGENTS.md

Use native 'create' or 'str_replace' tools for all file operations, including creating temporary script files.

```shell
create /tmp/experiment.sh
```

```shell
bash /tmp/experiment.sh
```

--------------------------------

### Breaking Change Release Example

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/VERSION_MANAGEMENT.md

Example workflow for releasing a breaking change, including committing the change, bumping the major version, and creating the release tag.

```bash
# Make breaking API change
git commit -m "Refactor: Change API structure"

# Bump major version (0.4.0 → 1.0.0)
make bump-major

# Release
git add VERSION
git commit -m "Release v1.0.0"
git tag v1.0.0
git push && git push --tags
```

--------------------------------

### Bug Fix Release Example

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/VERSION_MANAGEMENT.md

Example workflow for releasing a bug fix, including committing the fix, bumping the patch version, and creating the release tag.

```bash
# Fix a bug
git commit -m "Fix column offset calculation"

# Bump patch version (0.3.0 → 0.3.1)
make bump-patch

# Release
git add VERSION
git commit -m "Release v0.3.1"
git tag v0.3.1
git push && git push --tags
```

--------------------------------

### Update Start Positions in merge_diffs() for C

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/development/02-c-diff-algorithm/utf8-and-vscode-parity.md

Ensures that both start and end positions are correctly updated when merging overlapping diffs in the `merge_diffs` function. This resolves incorrect column offsets in character-level diffs.

```c
SequenceDiff merged = {
    .seq1_range = {
        .start_exclusive = min_int(a->seq1_range.start_exclusive, b->seq1_range.start_exclusive),  // ✅ Added
        .end_exclusive = max_int(a->seq1_range.end_exclusive, b->seq1_range.end_exclusive)
    },
    .seq2_range = {
        .start_exclusive = min_int(a->seq2_range.start_exclusive, b->seq2_range.start_exclusive),  // ✅ Added
        .end_exclusive = max_int(a->seq2_range.end_exclusive, b->seq2_range.end_exclusive)
    }
};
```

--------------------------------

### Download Method: wget

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/development/03-build-and-platform/automatic-installation.md

Uses wget as a fallback method to download the library binary.

```lua
{ "wget", "-q", "-O", dest_path, url }
```

--------------------------------

### VSCode Range Translation Logic

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/development/02-c-diff-algorithm/parity-evaluation-journey.md

Illustrates VSCode's behavior for translating offsets and ranges, highlighting the 'left' and 'right' preference for handling whitespace at line starts. The 'left' preference omits trimmed whitespace at the line start, while 'right' includes it.

```typescript
public translateOffset(offset: number, preference: 'left' | 'right' = 'right'): Position {
    const lineOffset = offset - this.firstElementOffsetByLineIdx[i];
    return new Position(
        this.range.startLineNumber + i,
        1 + this.lineStartOffsets[i] + lineOffset +
            ((lineOffset === 0 && preference === 'left') ? 0 : this.trimmedWsLengthsByLineIdx[i])
    );
}

public translateRange(range: OffsetRange): Range {
    const pos1 = this.translateOffset(range.start, 'right');   // Start: always add ws
    const pos2 = this.translateOffset(range.endExclusive, 'left'); // End: omit ws at line start
    if (pos2.isBefore(pos1)) {
        return Range.fromPositions(pos2, pos2);
    }
    return Range.fromPositions(pos1, pos2);
}
```

--------------------------------

### Linux Build with Make

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/BUILD.md

Build the project on Linux using 'make'. CMake and build-essential are only required for developers; users do not need them as utf8proc is bundled.

```bash
# No dependencies needed! utf8proc is bundled.
sudo apt-get install build-essential cmake   # Only for CMake build

# Build
make
```

--------------------------------

### C translate_range Implementation

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/development/02-c-diff-algorithm/parity-evaluation-journey.md

Implements the `char_sequence_translate_range` function in C, which mirrors VSCode's `translateRange` by using 'right' preference for the start offset and 'left' preference for the end offset. It also correctly handles collapsed ranges where the end position might be before the start.

```c
// This function is described in the text but the code is not provided.
```

--------------------------------

### Build C Library with build.sh/build.cmd

Source: https://github.com/esmuellert/codediff.nvim/blob/main/README.md

Use the provided build scripts to compile the C library from source. These scripts automatically place the compiled library in the correct plugin directory.

```bash
# Linux/macOS/BSD
./build.sh

# Windows
build.cmd
```

--------------------------------

### Windows Build with MSVC

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/BUILD.md

Configure and build the project on Windows using MSVC by opening the Developer Command Prompt and using CMake commands.

```cmd
REM Open "Developer Command Prompt for VS"
cmake -B build
cmake --build build
```

--------------------------------

### HTTPS Download URL

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/development/03-build-and-platform/automatic-installation.md

Example of a secure HTTPS download URL from GitHub releases.

```text
https://github.com/esmuellert/vscode-diff.nvim/releases/download/...
```

--------------------------------

### Get Git Root

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/git-integration.md

Retrieves the root directory of the Git repository for a given file path.

```APIDOC
## git.get_git_root(file_path)

### Description
Finds and returns the path to the top-level directory of the Git repository containing the specified file.

### Parameters
#### Parameters
- **file_path** (string) - Required - The path to a file within the Git repository.

### Returns
- `string` or `nil` - The path to the Git root directory, or `nil` if the file is not in a Git repository.
```

--------------------------------

### Build and Run Diff Core FFI Test

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/development/01-origins/mvp-implementation-plan.md

This bash script outlines the steps to build the C diffing module and then run the Lua test script using Neovim in headless mode. It includes commands for cleaning, building, and executing the test, along with the expected output for validation.

```bash
# Build C module
make clean && make

# Run Lua test (using nvim headless)
nvim --headless -c "luafile tests/test_render.lua" -c "quit"

# Expected output:
# Testing Lua FFI...
# Version: 0.1.0
# Left line metadata count: 4
# Right line metadata count: 4
# ✓ Lua FFI test passed

```

--------------------------------

### Get File from Git Revision (Async)

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/git-integration.md

Asynchronously fetches the content of a file at a specific Git revision.

```APIDOC
## git.get_file_at_revision(revision, file_path, callback)

### Description
Fetches the content of a file from a given Git revision asynchronously. The result is passed to a callback function.

### Parameters
#### Parameters
- **revision** (string) - Required - The Git revision (e.g., `HEAD`, commit hash, branch name).
- **file_path** (string) - Required - The path to the file within the repository.
- **callback** (function) - Required - A function to be called with the result. It receives two arguments: `err` (string or nil) and `lines` (table of strings or nil).

### Example
```lua
git.get_file_at_revision("HEAD~1", "path/to/file.lua", function(err, lines)
  if err then
    -- Handle error
    return
  end
  -- Process lines
end)
```
```

--------------------------------

### Setup Minimal Timeout Configuration (Maximum Speed)

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/performance.md

Use this configuration when prioritizing speed above all else. You will still see character-level detail in most places, as the timeout primarily skips expensive edge cases. This sets the timeout to 100ms.

```lua
require("vscode-diff").setup({
  diff = {
    max_computation_time_ms = 100,  -- 100ms
  }
})
```

--------------------------------

### Configure Codediff Explorer Panel with lazy.nvim

Source: https://github.com/esmuellert/codediff.nvim/blob/main/README.md

Set up the explorer panel's appearance, behavior, and filtering. Customize icons and visibility of file groups.

```lua
-- Explorer panel configuration
explorer = {
  position = "left",  -- "left" or "bottom"
  hidden = false,  -- Initial visibility state
  width = 40,         -- Width when position is "left" (columns)
  height = 15,        -- Height when position is "bottom" (lines)
  auto_refresh = true,  -- Auto-refresh file list on focus / git index changes (set false to avoid lag in huge repos; R still refreshes manually)
  indent_markers = true,  -- Show indent markers in tree view (│, ├, └)
  initial_focus = "explorer",  -- Initial focus: "explorer", "original", or "modified"
  icons = {
    folder_closed = "",  -- Nerd Font folder icon (customize as needed)
    folder_open = "",    -- Nerd Font folder-open icon
  },
  view_mode = "list",    -- "list" or "tree"
  flatten_dirs = true,   -- Flatten single-child directory chains in tree view
  file_filter = {
    ignore = { ".git/**", ".jj/**" },  -- Glob patterns to hide (e.g., {"*.lock", "dist/*"})
  },
  focus_on_select = false,  -- Jump to modified pane after selecting a file (default: stay in explorer)
  auto_open_on_cursor = false, -- Rebind j/k/Down/Up in the explorer to also open the file under the cursor
  status_right_margin = 1,  -- Trailing cells between status symbol (M/A/D) and right edge; increase if Nerd Font icons clip it
  visible_groups = {       -- Which groups to show (can be toggled at runtime)
    staged = true,
    unstaged = true,
    conflicts = true,
  },
},

```

--------------------------------

### Project Structure Overview

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/development/01-origins/mvp-implementation-plan.md

This tree outlines the directory structure for the Neovim plugin, detailing the placement of C source files, Lua modules, build automation scripts, and test fixtures.

```tree
nvim-vscode-diff/
├── README.md                      # Installation & usage instructions
├── Makefile                       # Build automation for C module
├── plugin/
│   └── vscode-diff.lua           # Lazy.nvim entry point
├── lua/
│   └── vscode-diff/
│       ├── init.lua              # Main Lua interface
│       ├── render.lua            # Buffer rendering logic
│       └── config.lua            # Plugin configuration
├── c-diff-core/
│   ├── diff_core.c               # C implementation (diff + render plan)
│   ├── diff_core.h               # C header file
│   └── test_diff_core.c          # C unit tests
└── tests/
    ├── test_render.lua           # Lua rendering tests
    └── fixtures/
        ├── file_a.txt            # Test input file A
        └── file_b.txt            # Test input file B
```

--------------------------------

### Check for Empty Range (Lua)

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/rendering-quick-reference.md

Determines if a given range is empty by checking if the start and end lines and columns are identical.

```lua
return range.start_line == range.end_line and 
       range.start_col == range.end_col
```

--------------------------------

### Test Output Example for Line Optimization

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/development/02-c-diff-algorithm/step2-step3-optimization-devlog.md

Demonstrates the output of a test case for the line optimization pipeline, showing the number and details of diffs after each step (Myers, optimize, removeVeryShort). This output helps verify the correctness of the diff computation and optimization stages.

```text
=== Test 4: Blank Line Separators with Large Diff ===
  After Step 1 (Myers): 2 diff(s)
    [0] seq1[0,4) -> seq2[0,4)
    [1] seq1[6,7) -> seq2[6,7)
  Step 1 (Myers): verified
  
  After Step 2 (optimize): 2 diff(s)
    [0] seq1[0,4) -> seq2[0,4)
    [1] seq1[6,7) -> seq2[6,7)
  Step 2 (optimize): verified
  
  After Step 3 (removeVeryShort): 1 diff(s)
    [0] seq1[0,7) -> seq2[0,7)
  Step 3 (removeVeryShort): verified
  ✓ Line optimization pipeline complete
```

--------------------------------

### C Project Structure for Diff Algorithm

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/development/02-c-diff-algorithm/implementation-plan.md

Illustrates a recommended flat C project layout for the diff algorithm implementation, including directories for include, source, tests, and the main header file.

```c
c-diff-core/
├── include/
│   └── types.h                    # All public type definitions
├── src/
│   ├── myers.c                    # Step 1: Myers diff algorithm
│   ├── optimize.c                 # Steps 2-3: Diff optimization (generic, used by both line & char)
│   ├── refine.c                   # Step 4: Character-level refinement
│   ├── mapping.c                  # Step 5: Line range mapping construction
│   ├── moved_lines.c              # Step 6: Move detection (optional)
│   ├── render_plan.c              # Step 7: Convert to render plan (STUB FIRST)
│   ├── utils.c                    # Utility functions (string, memory, etc.)
│   └── diff_core.c                # Main orchestrator + Lua FFI entry point
├── tests/
│   ├── test_myers.c
│   ├── test_optimize.c
│   ├── test_refine.c
│   ├── test_mapping.c
│   ├── test_moved_lines.c
│   ├── test_render_plan.c
│   └── test_integration.c
├── diff_core.h                    # Public API for Lua FFI
└── Makefile                       # Build system
```

--------------------------------

### Lua API: Get Git Root

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/git-integration.md

Retrieves the root directory of the Git repository for a given file path using `git.get_git_root`.

```lua
local git = require("vscode-diff.git")

local git_root = git.get_git_root("/path/to/file.lua")
if git_root then
  print("Git root:", git_root)
end
```

--------------------------------

### Simple Text Change Comparison

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/development/03-build-and-platform/vscode-extraction-tool.md

Use this example to compare simple text file differences between VSCode's diff tool and a C implementation. It first creates two test files with modifications and then runs both diff tools for comparison.

```bash
# Input files
echo -e "Hello World\nThis is a test file\nLine 3\nLine 4\nLine 5" > test1.txt
echo -e "Hello World\nThis is a modified test file\nLine 3 modified\nLine 4\nLine 6 added" > test2.txt

# VSCode output
node vscode-diff.mjs test1.txt test2.txt

# C output
./build/diff test1.txt test2.txt
```

--------------------------------

### Clone codediff.nvim Repository

Source: https://github.com/esmuellert/codediff.nvim/blob/main/README.md

Clone the plugin repository to the specified Neovim plugin directory if you prefer manual installation without a plugin manager.

```bash
git clone https://github.com/esmuellert/codediff.nvim ~/.local/share/nvim/codediff.nvim
```

--------------------------------

### Test in Clean Environment with Docker

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/dependency-distribution.md

Simulate a clean environment without libgomp to test the plugin's automatic download functionality. This ensures the plugin installs and functions correctly even when the dependency is not pre-installed.

```bash
docker run --rm -it -v $(pwd):/plugin ubuntu:latest bash -c "
  apt update && apt install -y neovim curl
  # Don't install libgomp1 package
  cd /plugin
  nvim --headless -c 'lua require("vscode-diff").setup()' -c quit
"
```

--------------------------------

### Manual Line Diff Pipeline (Before)

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/development/02-c-diff-algorithm/parity-evaluation-journey.md

Illustrates the manual, multi-step process for computing line diffs before API consolidation. Requires explicit creation of sequence objects and manual application of diff and optimization algorithms.

```c
StringHashMap* hash_map = string_hash_map_create();
ISequence* seq1 = line_sequence_create(lines_a, len_a, false, hash_map);
ISequence* seq2 = line_sequence_create(lines_b, len_b, false, hash_map);
bool timeout = false;
SequenceDiffArray* diffs = myers_diff_algorithm(seq1, seq2, 5000, &timeout);
diffs = optimize_sequence_diffs(seq1, seq2, diffs);
diffs = remove_very_short_matching_lines_between_diffs(seq1, seq2, diffs);
// Cleanup…
```

--------------------------------

### Line-Level Diff: Insertion Point Example

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/DIFF_NOTATION.md

Illustrates how empty ranges like [n,n) represent insertion points within an array.

```plaintext
Array indices:  0      1      2
Array values:  'a'    'b'    'c'
Insertion pts:    [0,0) [1,1) [2,2) [3,3)
                    ↓     ↓     ↓      ↓
                 before before before after
                   'a'   'b'   'c'    'c'
```

--------------------------------

### Setup Inline Diff Layout

Source: https://github.com/esmuellert/codediff.nvim/blob/main/doc/codediff.txt

Configures the diff layout to 'inline', which displays deleted lines as virtual overlays within a single pane.

```lua
require("codediff").setup({
  diff = { layout = "inline" },
})
```

--------------------------------

### Run Individual Spec Test

Source: https://github.com/esmuellert/codediff.nvim/blob/main/tests/README.md

Execute a specific integration test file (e.g., ffi_integration_spec.lua) using Neovim in headless mode.

```bash
nvim --headless --noplugin -u tests/init.lua \
  -c "lua require('plenary.test_harness').test_directory('tests/ffi_integration_spec.lua')"
```

--------------------------------

### Basic Neo-tree Usage Commands

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/development/04-lua-features/file-sidebar-research.md

These Vim commands illustrate basic usage of Neo-tree for Git status, including opening in the sidebar, a floating window, and comparing with a specific branch.

```vim
:Neotree git_status           " Open in sidebar
```

```vim
:Neotree float git_status     " Open in floating window
```

```vim
:Neotree git_status git_base=main  " Compare with branch
```

--------------------------------

### macOS Build with Make

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/BUILD.md

Build the project on macOS using 'make'. CMake is only required for developers; users do not need it as utf8proc is bundled.

```bash
# No dependencies needed! utf8proc is bundled.
brew install cmake   # Only for CMake build

# Build
make
```

--------------------------------

### C Implementation of Diff Core API Functions

Source: https://github.com/esmuellert/codediff.nvim/blob/main/docs/development/01-origins/mvp-implementation-plan.md

Provides implementations for getting the version, creating, and freeing the diff render plan structures.

```c
#include "diff_core.h"
#include <stdlib.h>
#include <string.h>

const char* diff_core_get_version(void) {
    return DIFF_CORE_VERSION;
}

DiffRenderPlan* diff_render_plan_create(void) {
    DiffRenderPlan* plan = (DiffRenderPlan*)calloc(1, sizeof(DiffRenderPlan));
    if (!plan) return NULL;
    
    memset(plan, 0, sizeof(DiffRenderPlan));
    return plan;
}

void diff_render_plan_free(DiffRenderPlan* plan) {
    if (!plan) return;
    
    free(plan->left.char_highlights);
    free(plan->left.filler_lines);
    free(plan->left.line_metadata);
    
    free(plan->right.char_highlights);
    free(plan->right.filler_lines);
    free(plan->right.line_metadata);
    
    free(plan);
}
```