### Example: Get File Content

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-main.md

Demonstrates how to use `get_file_content` to fetch file content and handle potential errors.

```lua
local git = require('diffs.git')
local content, err = git.get_file_content('HEAD', 'src/main.py')
if err then print(err) end
```

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

### Example Configuration Table

Source: https://github.com/barrettruth/diffs.nvim/blob/main/doc/diffs.nvim.txt

This is a sample configuration table showing various settings for diffs.nvim.

```lua
enabled = true,
algorithm = 'default',
max_lines = 500,
overrides = {},
conflict = {
  enabled = true,
  disable_diagnostics = true,
  show_virtual_text = true,
  show_actions = false,
  keymaps = false,
}
```

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

### Enable diffs.nvim with Defaults

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/README.md

Use this snippet to enable the diffs.nvim plugin with its default settings. This is the simplest way to get started.

```lua
require('diffs').attach()
```

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

### Install diffs.nvim with luarocks

Source: https://github.com/barrettruth/diffs.nvim/blob/main/README.md

Install the plugin using luarocks for a global or project-specific installation.

```bash
luarocks install diffs.nvim
```

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

### Example: Running Large Reviews

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-review.md

Demonstrates how to execute the :Diff review command, including considerations for performance with large diffs or specific branches.

```lua
-- Can be slow for very large reviews
:Diff review

-- Faster with specific branch
:Diff review origin/develop

-- Or restrict to specific files
-- Not directly supported, use git commands first
```

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

### Basic Diffs.nvim Setup

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/configuration.md

A fundamental configuration for diffs.nvim, enabling basic integrations and conflict resolution features. Remember to attach the plugin after configuration.

```lua
vim.g.diffs = {
  integrations = {
    fugitive = true,
    gitsigns = true,
  },
  highlights = {
    background = true,
  },
  conflict = {
    enabled = true,
    keymaps = {
      ours = 'cc',
      theirs = 'ct',
    }
  }
}

require('diffs').attach()
```

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

### Install diffs.nvim with vim.pack

Source: https://github.com/barrettruth/diffs.nvim/blob/main/README.md

Use this snippet to install the plugin using vim.pack for Neovim 0.12+.

```lua
vim.pack.add({
  'https://git.barrettruth.com/barrettruth/diffs.nvim',
})
```

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

### Example: Apply Patch with Validation

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-main.md

Shows how to apply a patch and validate its application using the `cached` and `check` options, printing errors if validation fails.

```lua
local git = require('diffs.git')
local ok, output = git.apply_patch(repo_root, patch_string, {
  cached = true,
  check = true,
})
if not ok then
  print("Patch validation failed: " .. table.concat(output))
end
```

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

### Create Custom Review Command

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-review.md

Example of creating a custom Neovim user command that utilizes the greview_command function with predefined arguments.

```lua
-- Create custom command with different defaults
local review = require('diffs.review')

vim.api.nvim_create_user_command('MyReview', function(opts)
  -- Review from develop branch to current feature branch
  review.greview_command('origin/develop HEAD', false, {
    vertical = false,
  })
end, {})
```

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

### Full Configuration Example

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/configuration.md

This is the complete default configuration structure for diffs.nvim. It covers all available options for debugging, view formatting, extra filetypes, highlighting, integrations, and conflict resolution.

```lua
vim.g.diffs = {
  debug = false,
  view = {
    prefix = true,
    change_bar = '▏',
    rail_separator = '│',
  },
  extra_filetypes = {},
  highlights = {
    background = true,
    blend_alpha = nil,
    warn_max_lines = true,
    context = {
      enabled = true,
      lines = 25,
    },
    treesitter = {
      enabled = true,
      max_lines = 500,
    },
    vim = {
      enabled = true,
      max_lines = 200,
    },
    intra = {
      enabled = true,
      algorithm = 'default',
      max_lines = 500,
    },
  },
  integrations = {
    fugitive = false,
    neogit = false,
    neojj = false,
    gitsigns = false,
    committia = false,
    telescope = false,
  },
  conflict = {
    enabled = true,
    disable_diagnostics = true,
    show_virtual_text = false,
    show_actions = false,
    keymaps = false,
  },
}
```

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

### Stacked Layout Example

Source: https://github.com/barrettruth/diffs.nvim/blob/main/doc/diffs.nvim.txt

Demonstrates the stacked layout for diffs, which uses a single rail for line numbers.

```diff
 | @@ -9,3 +9,3 @@
 9 |  alpha
 10 | -beta
 10 | +beta changed
 11 |  gamma
```

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

### Basic diffs.nvim Configuration

Source: https://github.com/barrettruth/diffs.nvim/blob/main/doc/diffs.nvim.txt

Configure diffs.nvim by setting vim.g.diffs options before the plugin loads. This example shows basic debug and view settings.

```lua
vim.g.diffs = {
  debug = false,
  view = {
    prefix = true,
    change_bar = '▏',
    rail_separator = '│',
  },
  integrations = {
    fugitive = false,
    neogit = false,
    neojj = false,
    gitsigns = false,
    committia = false,
    telescope = false,
  },
  extra_filetypes = {},
  highlights = {
    background = true,
    blend_alpha = 0.6,
    warn_max_lines = true,
    context = {
      enabled = true,
      lines = 25,
    },
    treesitter = {
      enabled = true,
      max_lines = 500,
    },
    vim = {
      enabled = true,
      max_lines = 200,
    },
    intra = {

```

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

### Attach Diffs.nvim to a Plugin-Owned Buffer

Source: https://github.com/barrettruth/diffs.nvim/blob/main/doc/diffs.nvim.txt

Example of how a plugin can integrate with diffs.nvim. This involves creating a buffer, setting its content and filetype, and then attaching diffs.nvim highlighting.

```lua
local bufnr = vim.api.nvim_create_buf(false, true)

vim.api.nvim_buf_set_lines(bufnr, 0, -1, false, diff_lines)
vim.b[bufnr].diffs_repo_root = repo_root
vim.bo[bufnr].filetype = 'myplugin-diff'

require('diffs').attach(bufnr)
```

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

### Setup Navigation for Diffs

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-review.md

Enables navigation features within review diffs, such as moving between files using the quickfix or location list. Call this function to activate these navigation capabilities.

```lua
local review = require('diffs.review')
review.setup_navigation()
```

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

### Advanced Diffs.nvim Customization

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/configuration.md

A comprehensive configuration example demonstrating advanced options for diffs.nvim. This includes detailed highlight settings, custom view prefixes, and specific conflict resolution keymaps.

```lua
vim.g.diffs = {
  debug = '/tmp/diffs.log',
  view = {
    change_bar = '█',
    prefix = true,
  },
  highlights = {
    blend_alpha = 0.9,
    treesitter = {
      enabled = true,
      max_lines = 1000,
    },
    intra = {
      algorithm = 'vscode',  -- Use more accurate diffs
      max_lines = 1000,
    },
  },
  integrations = {
    fugitive = true,
    neogit = true,
    gitsigns = true,
  },
  conflict = {
    enabled = true,
    show_virtual_text = true,
    show_actions = true,
    keymaps = {
      ours = 'cc',
      theirs = 'ct',
      both = 'cb',
      none = 'cn',
      next = 'n',
      prev = 'N',
    }
  }
}
```

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

### Setup Diff Buffer Function

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-review.md

Configures a buffer to display diffs.nvim content. It sets up essential keymaps, autocmds, and syntax highlighting for effective diff viewing.

```lua
function setup_diff_buf(bufnr: integer): boolean
```

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

### Performance-Focused Diffs.nvim Setup

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/configuration.md

Optimize diffs.nvim performance by adjusting highlight settings, such as skipping treesitter for large hunks and disabling intra-line diffs. Integrations can also be selectively enabled.

```lua
vim.g.diffs = {
  integrations = {
    fugitive = true,
  },
  highlights = {
    treesitter = { max_lines = 200 },  -- Skip treesitter for large hunks
    vim = { max_lines = 100 },
    intra = { enabled = false },       -- Disable intra-line diffs
  }
}
```

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

### Example GreviewSpec Usage

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-review.md

Demonstrates how to create a GreviewSpec object with specific base and target revisions, and a vertical split orientation. This is useful for configuring a review session.

```lua
local review = require('diffs.review')
local spec = {
  base = 'origin/main',
  target = 'HEAD',
  vertical = true,
}
```

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

### Filetype Autocommands

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-runtime.md

Example autocmds for triggering diffs.nvim based on buffer FileType. These are typically set up internally by the plugin but illustrate the event triggers.

```lua
-- Fugitive
autocmd FileType fugitive callback

-- Neogit  
autocmd FileType neogit callback

-- Built-in diff filetype
autocmd FileType diff callback
```

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

### Global Event Autocommands

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-runtime.md

Example autocmds for global events that affect diffs.nvim highlighting. These handle color scheme changes and window closures.

```lua
-- Recompute highlight colors on color scheme change
autocmd ColorScheme callback

-- Forget closed diff windows
autocmd WinClosed callback
```

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

### Example Custom Review Mode

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-review.md

Illustrates setting a custom review mode within the GreviewSpec. While currently limited to basic review, the 'mode' field is intended for future extensions to the review workflow.

```lua
local spec = {
  base = 'origin/main',
  target = 'HEAD',
  mode = 'review',      -- Could enable additional UI
}
```

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

### Get File Content from Working Directory

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-main.md

Reads the current content of a file directly from the working directory.

```lua
function get_working_content(filepath: string): diffs.ContentLines?, string?
```

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

### Get File Content from Git Index

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-main.md

Retrieves the content of a file as it exists in the Git staging area (index).

```lua
function get_index_content(filepath: string): diffs.ContentLines?, string?
```

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

### Buffer Event Autocommands

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-runtime.md

Example autocmds for handling buffer-related events that trigger diffs.nvim updates. These ensure highlights are refreshed when buffer content or state changes.

```lua
-- Redraw on buffer changes
autocmd BufWritePost callback
autocmd InsertLeave callback
autocmd TextChanged callback

-- Cleanup on buffer deletion
autocmd BufWipeout callback
```

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

### Get Human-Readable Diff Label

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-main.md

Generates a descriptive label for a given diff specification, useful for UI display.

```lua
function label(diff_spec: diffs.DiffSpec): string
```

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

### GdiffHunkRange Type

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/types.md

Defines a line range within a diff hunk, specifying the start line and the total count of lines.

```lua
---@class diffs.GdiffHunkRange
---@field start integer
---@field count integer
---@field finish integer
```

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

### Open diffs.nvim documentation

Source: https://github.com/barrettruth/diffs.nvim/blob/main/README.md

Access the plugin's help documentation within Neovim using this command.

```vim
:help diffs.nvim
```

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

### Enable Telescope Integration

Source: https://github.com/barrettruth/diffs.nvim/blob/main/doc/diffs.nvim.txt

Set `vim.g.diffs.integrations.telescope = true` to enable integration with telescope.nvim for preview highlighting. Passing a table is deprecated.

```lua
vim.g.diffs = { integrations = { telescope = true } }
```

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

### :Diff review [options]

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-main.md

Opens a full-repository review diff view. Creates an interactive diff viewer for reviewing all changes in the repository. Navigate between files with quickfix/location list. Press Enter on a file to view its detailed diff.

```APIDOC
## :Diff review [options]

### Description
Opens a full-repository review diff view. Creates an interactive diff viewer for reviewing all changes in the repository. Navigate between files with quickfix/location list. Press Enter on a file to view its detailed diff.

### Options
- `base`: Base revision for the review (default: origin/main)
- `target`: Target revision (default: HEAD)
- `vertical`: Split layout vertically instead of horizontally

### Example
```vim
" Review HEAD against origin/main
:Diff review

" Review with custom base
:Diff review origin/develop

" Review with vertical split
:Diff review base=origin/main vertical
```
```

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

### Get Git Repository Root

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-main.md

Finds the root directory of the Git repository for a given file path. Caches results per directory.

```lua
function get_repo_root(filepath?: string): string?
```

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

### Open Review with Stacked Layout

Source: https://github.com/barrettruth/diffs.nvim/blob/main/doc/diffs.nvim.txt

Opens a generated review map with one context-aware line-number rail against the specified base ref.

```vim
:Diff review ++layout=stacked origin/main
```

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

### setup_diff_buf Function

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-review.md

Configures a diff buffer for use with diffs.nvim. It sets up buffer-local keymaps for staging/unstaging, autocmds for buffer cleanup, syntax highlighting, and hunk parsing.

```APIDOC
## setup_diff_buf Function

### Description
Configures a diff buffer for use with diffs.nvim. This function sets up essential buffer-local configurations including keymaps for staging/unstaging hunks, autocmds for buffer cleanup, syntax highlighting attachment, and hunk parsing.

### Parameters

- **bufnr** (integer) - Required - The buffer number to configure.

### Returns
- **boolean** - `true` if the setup was successful, `false` otherwise.
```

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

### Get File Content at a Specific Revision

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-main.md

Retrieves the content of a file at a given Git revision. Returns content lines and an optional error message.

```lua
function get_file_content(revision: string, filepath: string): diffs.ContentLines?, string?
```

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

### Basic Diff Commands

Source: https://github.com/barrettruth/diffs.nvim/blob/main/doc/diffs.nvim.txt

Use these commands to initiate diffs against different sources like the index or a specific git revision.

```vim
:Diff           " diff against the index
:Diff main      " diff against main branch
:Diff HEAD~3    " diff against 3 commits ago
:Diff :0:%      " diff against the index explicitly
:Diff abc123    " diff against specific commit
:Diff ++layout=stacked
:vertical Diff  " open the generated diff in a vertical split
```

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

### resolve_repo_root Function Signature

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-review.md

Function to resolve the repository root path. It searches for the Git repository starting from the provided path or the current buffer/working directory.

```lua
function resolve_repo_root(repo?: string): string?
```

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

### Configuration options

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/README.md

Provides a way to create new configuration with specified options.

```APIDOC
## new configuration

### Description
Creates a new configuration with the given options.

### Method
`require('diffs.config').new(opts)

### Parameters
#### Path Parameters
- **opts** (table) - Optional - Configuration options.
```

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

### Programmatic Split Workspace Review

Source: https://github.com/barrettruth/diffs.nvim/blob/main/doc/diffs.nvim.txt

Helper function to programmatically open the currently selected :Diff-review file in the two-surface split workspace.

```lua
require('diffs.commands').greview_split()
```

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

### Get File Path Relative to Repository Root

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-main.md

Converts an absolute or relative file path into its equivalent path relative to the Git repository's root directory.

```lua
function get_relative_path(filepath: string): string?
```

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

### Enable Neogit Integration

Source: https://github.com/barrettruth/diffs.nvim/blob/main/doc/diffs.nvim.txt

Set `vim.g.diffs.integrations.neogit = true` to enable integration with Neogit. Passing a table is deprecated.

```lua
vim.g.diffs = { integrations = { neogit = true } }
```

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

### Configure High-Quality Highlights

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/README.md

Set up advanced highlighting options for diffs.nvim, including background blending and intra-line diffs using the VS Code algorithm. This provides a visually rich diff experience.

```lua
vim.g.diffs = {
  highlights = {
    background = true,
    blend_alpha = 0.9,
    intra = {
      enabled = true,
      algorithm = 'vscode',
    }
  }
}
```

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

### Run Health Check

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-runtime.md

Execute the Neovim health check for diffs.nvim to verify its setup, configuration, and integration status. This command also checks for parser and FFI library availability.

```vim
:checkhealth diffs
```

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

### Open Review with Split Layout

Source: https://github.com/barrettruth/diffs.nvim/blob/main/doc/diffs.nvim.txt

Opens a two-surface split workspace for the first renderable changed review file. The left window shows the diff, and the right window is the editable worktree file.

```vim
:Diff review ++layout=split
```

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

### Configure diffs.nvim Mappings for Diffs

Source: https://github.com/barrettruth/diffs.nvim/blob/main/doc/diffs.nvim.txt

Sets up key mappings for common diff operations using diffs.nvim plugin plugs. These mappings allow for quick access to showing index-to-worktree diffs in horizontal or vertical splits.

```lua
vim.keymap.set('n', '<leader>gd', '<Plug>(diffs-gdiff)')
vim.keymap.set('n', '<leader>gD', '<Plug>(diffs-gvdiff)')
```

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

### Open Default Repository Review

Source: https://github.com/barrettruth/diffs.nvim/blob/main/doc/diffs.nvim.txt

Reviews the current repository state against the remote default branch. Ensure the remote HEAD ref is set.

```vim
:Diff review
```

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

### Configure diffs.nvim Mappings for Merge Resolution

Source: https://github.com/barrettruth/diffs.nvim/blob/main/doc/diffs.nvim.txt

Sets up key mappings for accepting changes in a merge diff view using diffs.nvim. These mappings allow accepting ours, theirs, or both changes to resolve merge conflicts.

```lua
vim.keymap.set('n', '<leader>mo', '<Plug>(diffs-merge-ours)')
vim.keymap.set('n', '<leader>mt', '<Plug>(diffs-merge-theirs)')
vim.keymap.set('n', '<leader>mb', '<Plug>(diffs-merge-both)')
vim.keymap.set('n', '<leader>m0', '<Plug>(diffs-merge-none)')
```

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

### Open Review Against Specific Base Ref

Source: https://github.com/barrettruth/diffs.nvim/blob/main/doc/diffs.nvim.txt

Reviews the current repository state against the specified base ref.

```vim
:Diff review origin/main
```

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

### High-Quality Syntax Highlighting Configuration

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-highlight.md

Enables all highlighting features with increased context and accuracy. This configuration aims for maximum highlight quality and precision.

```lua
vim.g.diffs = {
  highlights = {
    background = true,
    blend_alpha = 0.9,  -- Slightly transparent for syntax visibility
    context = {
      lines = 50,       -- More context for better parsing
    },
    treesitter = {
      enabled = true,
      max_lines = 1000, -- Process larger hunks
    },
    vim = {
      enabled = true,
      max_lines = 1000,
    },
    intra = {
      enabled = true,
      algorithm = 'vscode',  -- More accurate diffs
      max_lines = 1000,
    },
  }
}
```

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

### Enable Neojj Integration

Source: https://github.com/barrettruth/diffs.nvim/blob/main/doc/diffs.nvim.txt

Set `vim.g.diffs.integrations.neojj = true` to enable integration with neojj. Passing a table is deprecated.

```lua
vim.g.diffs = { integrations = { neojj = true } }
```

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

### Enable Gitsigns Integration

Source: https://github.com/barrettruth/diffs.nvim/blob/main/doc/diffs.nvim.txt

Set `vim.g.diffs.integrations.gitsigns = true` to enable integration with gitsigns.nvim for blame hunk previews. Passing a table is deprecated.

```lua
vim.g.diffs = { integrations = { gitsigns = true } }
```

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

### Open Repository-Wide Review Diff View

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-main.md

Creates an interactive diff viewer for reviewing all changes in the repository. Allows navigation between files and viewing detailed diffs.

```vim
" Review HEAD against origin/main
:Diff review

" Review with custom base
:Diff review origin/develop

" Review with vertical split
:Diff review base=origin/main vertical
```

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

### Intra Configuration Type

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/types.md

Sets up intra-line diff highlighting in diffs.nvim. Enable intra-line diffs, choose an algorithm, and specify the maximum lines.

```lua
---@class diffs.IntraConfig
---@field enabled boolean
---@field algorithm string
---@field max_lines integer
```

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

### Pre-built Spec for Index vs. Working Directory

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-main.md

A convenience constructor for creating a diff specification that compares the git index against the working directory. Provide the path to the file you want to compare.

```lua
function index_to_worktree(path: string): diffs.DiffSpec

```

```lua
local spec = require('diffs.spec')
local diff = spec.index_to_worktree('path/to/file.txt')

```

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

### Create New Configuration

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/README.md

Create a new configuration object using 'require("diffs.config").new(opts)'. This is part of the stable API for configuring diffs.

```lua
require('diffs.config').new(opts)
```

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

### Add Custom Filetypes

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-runtime.md

Configure additional filetypes for diff detection. Add custom filetype names to the `extra_filetypes` table in your configuration.

```lua
vim.g.diffs = {
  extra_filetypes = {
    'git-diff',
    'my-custom-diff-format',
  }
}
```

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

### Create Namespace for Diffs

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-highlight.md

All diff highlights use a dedicated namespace. This snippet shows how to create it.

```lua
local ns = vim.api.nvim_create_namespace('diffs')
```

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

### Compute Hunk Highlight Options

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-highlight.md

Merges global configuration with per-hunk overrides to determine highlighting algorithms. Used internally to configure hunk-by-hunk highlighting based on hunk size and buffer state.

```lua
local highlight = require('diffs.highlight')
local config = require('diffs.config').new()

-- Standard highlighting with global config
local opts = highlight.hunk_opts(config)

-- Fast highlighting (treesitter disabled)
local fast_opts = highlight.hunk_opts(config, {
  highlights = {
    treesitter = { enabled = false },
  }
})
```

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

### Logging Notifications

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/errors.md

Demonstrates how to send notifications using the diffs.nvim logging utility. Different log levels can be used to categorize messages.

```lua
local log = require('diffs.log')
log.notify('Operation succeeded', vim.log.levels.INFO)
log.dbg('Detailed diagnostic: %s', debug_info)  -- Only if debug enabled
```

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

### Enable diffs.nvim integrations

Source: https://github.com/barrettruth/diffs.nvim/blob/main/README.md

Configure diffs.nvim to integrate with various Git plugins like vim-fugitive and Neogit by setting global variables.

```lua
vim.g.diffs = {
  integrations = {
    fugitive = true,
    neogit = true,
    neojj = true,
    gitsigns = true,
  }
}
```

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

### Enable Debug Logging to File

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/configuration.md

Configure diffs.nvim to log debug information to a specified file. This is useful for troubleshooting.

```lua
vim.g.diffs = {
  debug = '/tmp/diffs.log'  -- Log to file
}
```

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

### Enable Neojj Integration

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-runtime.md

Enable integration with neojj for diff views. This configuration should be placed in your Neovim configuration.

```lua
vim.g.diffs = {
  integrations = {
    neojj = true
  }
}
```

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

### Configure Max Lines for Syntax Highlighting

Source: https://github.com/barrettruth/diffs.nvim/blob/main/doc/diffs.nvim.txt

Adjust the threshold for skipping syntax highlighting in large diff hunks. Set `warn_max_lines` to false to suppress warnings.

```lua
vim.g.diffs = {
  highlights = {
    treesitter = { max_lines = 1000 },  -- default: 500
    vim = { max_lines = 500 },           -- default: 200
  },
}
```

```lua
vim.g.diffs = {
  highlights = { warn_max_lines = false },
}
```

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

### View Diff with Syntax Highlighting

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/README.md

Use these Vim commands to view diffs of the current file against different revisions or to review all changes in the repository.

```vim
:Diff HEAD            " Diff current file against HEAD
:Diff origin/main     " Diff against a branch
:Diff review          " Review all changes in repo
```

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

### Opt-in Integration for Custom Filetypes

Source: https://github.com/barrettruth/diffs.nvim/blob/main/doc/diffs.nvim.txt

Use 'extra_filetypes' to attach diffs.nvim to any buffer whose content resembles a diff, for filetypes not covered by built-in integrations.

```lua
vim.g.diffs = { extra_filetypes = { 'diff' } }
```

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

### Highlights Configuration Type

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/types.md

Manages syntax highlighting settings for diffs.nvim. Control background highlighting, blend alpha, overrides, and context-specific highlighting.

```lua
---@class diffs.Highlights
---@field background boolean
---@field blend_alpha? number
---@field overrides? table<string, table>
---@field warn_max_lines boolean
---@field context diffs.ContextConfig
---@field treesitter diffs.TreesitterConfig
---@field vim diffs.VimConfig
---@field intra diffs.IntraConfig
```

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

### :Greview [BASE] [TARGET]

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-main.md

Legacy command for repository-wide reviews (deprecated, use `:Diff review`).

```APIDOC
## :Greview [BASE] [TARGET]

### Description
Legacy command for repository-wide reviews (deprecated, use `:Diff review`).
```

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

### Pre-built Spec for Revision vs. Working Directory

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-main.md

A convenience constructor for creating a diff specification that compares a specific git revision against the working directory. Provide the revision identifier (e.g., commit hash, branch name) and the file path.

```lua
function rev_to_worktree(rev: string, path: string): diffs.DiffSpec

```

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

### Enable Debug Logging

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/README.md

Enable debug logging for diffs.nvim by specifying a log file path. This helps in diagnosing slow hunks and other performance issues.

```lua
vim.g.diffs.debug = '/tmp/diffs.log'
-- Check log for slow hunks
```

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

### Configure Buffer-Local Conflict Resolution Keymaps

Source: https://github.com/barrettruth/diffs.nvim/blob/main/doc/diffs.nvim.txt

Opt-in to buffer-local keymaps for conflict resolution actions like accepting ours, theirs, or both changes, and navigating between conflicts. Unspecified fields remain disabled.

```lua
vim.g.diffs = {
  conflict = {
    keymaps = {
      ours = '<leader>co',
      theirs = '<leader>ct',
      both = '<leader>cb',
      none = '<leader>c0',
      next = ']x',
      prev = '[x',
    },
  },
}
```

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

### Open Diff View

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/README.md

Use the ':Diff' command to manually open the diff view. This is useful for troubleshooting if highlights are not showing.

```vim
:Diff
```

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

### Configure Diffs.nvim Settings

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/README.md

Set global variables to configure debugging, display options, highlighting, integrations, and conflict resolution behavior for diffs.nvim.

```lua
vim.g.diffs = {
  -- Debugging
  debug = false,                    " or file path
  
  -- Display
  view = {
    prefix = true,                 " Show +/- prefixes
    change_bar = '▏',              " Rail character
    rail_separator = '│',          " Separator character
  },
  
  -- Highlighting
  highlights = {
    background = true,
    blend_alpha = nil,              " 0-1, nil for default
    context = {
      enabled = true,
      lines = 25,                  " Context size
    },
    treesitter = {
      enabled = true,
      max_lines = 500,             " Skip for large hunks
    },
    vim = {
      enabled = true,
      max_lines = 200,
    },
    intra = {
      enabled = true,
      algorithm = 'default',       " or 'vscode'
      max_lines = 500,
    },
  },
  
  -- Integrations
  integrations = {
    fugitive = false,
    neogit = false,
    neojj = false,
    gitsigns = false,
    committia = false,
    telescope = false,
  },
  
  -- Conflict Resolution
  conflict = {
    enabled = true,
    disable_diagnostics = true,
    show_virtual_text = true,
    show_actions = false,
    keymaps = {
      ours = false,               " Set to 'cc', etc.
      theirs = false,
      both = false,
      none = false,
      next = false,
      prev = false,
    }
  }
}
```

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

### Create Diff Endpoint for Working Directory

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-main.md

Creates a reference to a file in the working directory. Use this to compare against the current state of files on disk.

```lua
function worktree(): diffs.WorktreeEndpoint

```

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

### Programmatic Merge-Base Review

Source: https://github.com/barrettruth/diffs.nvim/blob/main/doc/diffs.nvim.txt

Helper function to programmatically initiate a merge-base review with specified base, target, and repository path.

```lua
require('diffs.commands').greview({
  base = 'origin/main',
  target = 'refs/forge/pr/42',
  repo = '/path/to/repo',
})
```

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

### Global configuration

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/README.md

Allows global configuration of diffs.nvim using `vim.g.diffs`.

```APIDOC
## Global Configuration

### Description
Global configuration settings for diffs.nvim are accessible via `vim.g.diffs`.
```

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

### Enable Neogit Integration

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-runtime.md

Enable integration with Neogit to automatically attach diffs.nvim to Neogit diff views. This configuration should be placed in your Neovim configuration.

```lua
vim.g.diffs = {
  integrations = {
    neogit = true
  }
}
```

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

### Enable Committia Integration

Source: https://github.com/barrettruth/diffs.nvim/blob/main/doc/diffs.nvim.txt

Set `vim.g.diffs.integrations.committia = true` to enable integration with committia.vim for diff-pane support. Passing a table is deprecated.

```lua
vim.g.diffs = { integrations = { committia = true } }
```

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

### View Configuration Type

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/types.md

Specifies display formatting options for diffs.nvim. Configure prefixes, change bar styles, and rail separators.

```lua
---@class diffs.ViewConfig
---@field prefix boolean
---@field change_bar string
---@field rail_separator string
```

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

### Configure Context Line Highlighting

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/configuration.md

Enable or disable context line highlighting and set the number of surrounding lines to include for syntax parsing. Adjust 'lines' for better accuracy at the cost of memory.

```lua
vim.g.diffs = {
  highlights = {
    context = {
      enabled = true,
      lines = 50  -- Include more context for complex syntax
    }
  }
}
```

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

### Vim Configuration Type

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/types.md

Configures Vim's built-in syntax highlighting for diffs.nvim. Enable Vim highlighting and set the maximum number of lines.

```lua
---@class diffs.VimConfig
---@field enabled boolean
---@field max_lines integer
```

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

### Context Configuration Type

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/types.md

Defines context line settings for diffs.nvim. Enable context lines and specify the number of lines to display.

```lua
---@class diffs.ContextConfig
---@field enabled boolean
---@field lines integer
```

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

### Enable Debug Logging for Highlighting

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-highlight.md

To diagnose highlighting issues, enable debug logging. You can direct the output to a file or to the console. This log provides detailed information about highlighting operations.

```lua
vim.g.diffs = {
  debug = '/tmp/diffs.log'  -- or true for console output
}
```

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

### Configure Extra Filetypes for Diffs.nvim Integration

Source: https://github.com/barrettruth/diffs.nvim/blob/main/doc/diffs.nvim.txt

Set global variables to inform diffs.nvim about additional filetypes that should be integrated. This allows the plugin to automatically attach highlighting to buffers with these filetypes.

```lua
vim.g.diffs = {
  extra_filetypes = { 'myplugin-diff' },
}
```

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

### Minimal Configuration for Performance

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-highlight.md

Disables advanced highlighting features like treesitter, vim syntax, and intra-line diffs to prioritize performance. Only line background colors will be shown.

```lua
vim.g.diffs = {
  highlights = {
    background = true,
    treesitter = { enabled = false },      -- Skip treesitter
    vim = { enabled = false },             -- Skip vim syntax
    intra = { enabled = false },           -- Skip character-level
  }
}
```

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

### Pre-built Diff Spec for Two Revisions

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-main.md

Use this function to create a diff specification for comparing two specific revisions of a file.

```lua
function rev_to_rev(left_rev: string, right_rev: string, path: string): diffs.DiffSpec
```

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

### Enable Automatic Integrations

Source: https://github.com/barrettruth/diffs.nvim/blob/main/doc/diffs.nvim.txt

Enable automatic integration with various plugins by setting the 'integrations' table in the global 'diffs' configuration. This automatically registers FileType autocmds for supported filetypes.

```lua
vim.g.diffs = {
  integrations = {
    fugitive = true,
    neogit = true,
    neojj = true,
    gitsigns = true,
    committia = true,
  },
}
```

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

### Configuration Validation Type Errors

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/errors.md

Illustrates how to use `vim.validate` for type checking configuration fields. Errors are raised using the `error()` function with a specific prefix.

```lua
vim.validate('field_name', value, 'expected_type')
```

```lua
error('diffs: highlights.context.lines must be >= 0')
```

```lua
error('diffs: highlights.blend_alpha must be >= 0 and <= 1')
```

```lua
error('diffs: highlights.treesitter.max_lines must be >= 1')
```

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

### Apply Patch with Options

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-main.md

Applies a unified diff patch to the repository using `git apply`. Supports various options like cached, reverse, and check.

```lua
function apply_patch(
  repo_root: string,
  patch: string,
  opts?: diffs.GitApplyOpts
): boolean, string[]
```

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

### Configure Conflict Keymaps

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/configuration.md

Define keybindings for resolving merge conflicts. Each field corresponds to a specific conflict resolution action.

```lua
vim.g.diffs = {
  conflict = {
    keymaps = {
      ours = '<leader>co',     -- Take current
      theirs = '<leader>ct',   -- Take incoming
      both = '<leader>cb',     -- Take both
      none = '<leader>cn',     -- Take neither
      next = '<leader>]x',     -- Next conflict
      prev = '<leader>[x',     -- Previous conflict
    }
  }
}
```

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

### Enable Fugitive Integration

Source: https://github.com/barrettruth/diffs.nvim/blob/main/doc/diffs.nvim.txt

Set `vim.g.diffs.integrations.fugitive = true` to enable integration with Fugitive. Passing a table is deprecated.

```lua
vim.g.diffs = {
  integrations = {
    fugitive = true,
  },
}
```

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

### Create Diff Endpoint for Git Index

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-main.md

Creates a reference to a file in the git index (staging area). Use this when comparing against what is currently staged for commit.

```lua
function index(): diffs.IndexEndpoint

```

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

### Pre-built Diff Spec for Stage vs. Working Directory

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-main.md

Use this function to create a diff specification for comparing a merge conflict stage against the working directory.

```lua
function stage_to_worktree(stage_num: 1|2|3, path: string): diffs.DiffSpec
```

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

### Configure Diffs Highlights via Overrides

Source: https://github.com/barrettruth/diffs.nvim/blob/main/doc/diffs.nvim.txt

Configure DiffsAdd and DiffsDiffDelete highlights using the `highlights.overrides` option in your Neovim configuration. This method allows for centralized theme management.

```lua
vim.g.diffs = {
      highlights = {
        overrides = {
          DiffsAdd = { bg = '#2e4a3a' },
          DiffsDiffDelete = { link = 'DiffDelete' },
        },
      },
    }
```

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

### Enable Committia Integration

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-runtime.md

Enable integration with committia.vim for diff views during commit editing. This configuration should be placed in your Neovim configuration.

```lua
vim.g.diffs = {
  integrations = {
    committia = true
  }
}
```

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

### Enabling Diffs for 'diff' Filetype

Source: https://github.com/barrettruth/diffs.nvim/blob/main/doc/diffs.nvim.txt

Use this configuration to enable diff highlighting for plain .diff or .patch files by adding 'diff' to extra_filetypes.

```lua
vim.g.diffs = {
  extra_filetypes = { 'diff' },
}
```

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

### Create and Inspect Diff Specifications

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/README.md

Use the diffs.spec module to create diff specifications and inspect their properties. This is fundamental for programmatic diff operations.

```lua
local spec = require('diffs.spec')
local actions = require('diffs.actions')

-- Create a diff specification
local diff = spec.index_to_worktree('src/main.py')
print(spec.label(diff))  -- "index -> worktree file:src/main.py"

-- Get diff metadata
local actions_data = spec.patch_actions(diff)
if actions_data.can_put then
  print("Can stage this hunk")
end

-- Generate patch for hunk
local patch, err = actions.patch_for_hunk(hunk)
if err then print("Error: " .. err) end
```

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

### Open Diff with Split Layout

Source: https://github.com/barrettruth/diffs.nvim/blob/main/doc/diffs.nvim.txt

Opens the current single-file comparison as paired old/new endpoint windows with native Vim diff alignment.

```vim
:Diff ++layout=split [object]
```

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

### Configure diffs.nvim Mappings for Conflict Resolution

Source: https://github.com/barrettruth/diffs.nvim/blob/main/doc/diffs.nvim.txt

Configures key mappings for resolving merge conflicts using diffs.nvim. These mappings allow accepting ours, theirs, both, or neither, and navigating between conflict markers.

```lua
vim.keymap.set('n', '<leader>co', '<Plug>(diffs-conflict-ours)')
vim.keymap.set('n', '<leader>ct', '<Plug>(diffs-conflict-theirs)')
vim.keymap.set('n', '<leader>cb', '<Plug>(diffs-conflict-both)')
vim.keymap.set('n', '<leader>c0', '<Plug>(diffs-conflict-none)')
vim.keymap.set('n', ']x', '<Plug>(diffs-conflict-next)')
vim.keymap.set('n', '[x', '<Plug>(diffs-conflict-prev)')
```

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

### Migrate Deprecated Config Format

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-runtime.md

Automatically migrates deprecated configuration settings to the new format. Use this when updating from older versions of the plugin.

```lua
-- Old format (deprecated)
vim.g.diffs = {
  hide_prefix = true  -- Deprecated
}

-- Automatically migrated to
vim.g.diffs = {
  view = {
    prefix = false   -- New format
  }
}
```

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

### Create Diff Endpoint for Merge Conflict Stage

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-main.md

Creates a reference to a file in a specific merge conflict stage (1 for 'ours', 2 for 'base', 3 for 'theirs'). Use this when resolving merge conflicts.

```lua
function stage(stage_num: 1|2|3): diffs.StageEndpoint

```

```lua
local sp = require('diffs.spec')
local ep = sp.stage(1) -- "ours" stage in merge conflict

```

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

### Pre-built Spec for HEAD vs. Index

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-main.md

A convenience constructor for creating a diff specification that compares the HEAD commit against the git index. This is useful for seeing what changes are staged relative to the last commit.

```lua
function head_to_index(path: string): diffs.DiffSpec

```

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

### Check Filetype

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/README.md

Check the current buffer's filetype using ':set filetype?'. This is a troubleshooting step for highlight issues.

```vim
:set filetype?
```

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

### Create Custom Diff View

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/README.md

Generate a custom diff specification between two revisions using `diffs.spec` and retrieve file content with `diffs.git`.

```lua
local spec = require('diffs.spec')
local git = require('diffs.git')

-- Get file contents for two revisions
local old, err1 = git.get_file_content('v1.0', 'src/main.py')
local new, err2 = git.get_file_content('v1.1', 'src/main.py')

if err1 or err2 then
  print("Error retrieving files")
else
  -- Use with diffs.spec to create comparison
  local diff_spec = spec.rev_to_rev('v1.0', 'v1.1', 'src/main.py')
  print(spec.label(diff_spec))
end
```

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

### greview_command Function

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-review.md

Implements the :Diff review [args] and :Greview commands to create and manage review diffs. It parses review specifications, validates revisions, generates file diffs, and sets up navigation and hunk actions.

```APIDOC
## greview_command Function

### Description
Implements the `:Diff review [args]` and `:Greview` commands. This function parses review specifications, validates revisions, generates file diffs using `git diff`, creates a review diff buffer, populates it with file diffs, and sets up navigation and hunk actions.

### Parameters

- **args** (string) - Required - Command arguments (base revision, target, etc.).
- **vertical** (boolean?) - Optional - Split the review buffer vertically.
- **opts** (table?) - Optional - Additional options for the review.

### Returns
- **boolean** - `true` if the review buffer was opened successfully, `false` on error.

### Behavior
1. Parse review specification.
2. Validate revisions exist.
3. Generate file list via `git diff`.
4. Create review diff buffer.
5. Populate with file diffs.
6. Setup navigation (quickfix/location list).
7. Enable hunk actions.
```

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

### diffs.spec.index

Source: https://github.com/barrettruth/diffs.nvim/blob/main/_autodocs/api-reference-main.md

Creates a reference to a file in the git index (staging area). This is useful for diffing against what is currently staged.

```APIDOC
## diffs.spec.index()

### Description
Creates a reference to a file in the git index (staging area).
```

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

### Configure Git Mergetool for Diffs.nvim

Source: https://github.com/barrettruth/diffs.nvim/blob/main/doc/diffs.nvim.txt

Configure Git to use diffs.nvim as the mergetool. This allows Neovim to open merge conflict files with diffs.nvim's enhanced highlighting and resolution capabilities.

```gitconfig
[merge]
    tool = diffs-nvim

[mergetool "diffs-nvim"]
    cmd = nvim "$MERGED"
```