*fugitive-ts.nvim.txt*        Treesitter highlighting for vim-fugitive diffs

Author:  Barrett Ruth <br.barrettruth@gmail.com>
License: MIT

==============================================================================
INTRODUCTION                                                   *fugitive-ts.nvim*

fugitive-ts.nvim adds treesitter-based syntax highlighting to vim-fugitive
diff views. It overlays language-aware highlights on top of fugitive's
default regex-based diff highlighting.

==============================================================================
REQUIREMENTS                                          *fugitive-ts-requirements*

- Neovim 0.9.0+
- vim-fugitive (https://github.com/tpope/vim-fugitive)
- Treesitter parsers for languages you want highlighted

==============================================================================
SETUP                                                        *fugitive-ts-setup*

Using lazy.nvim: >lua
    {
      'barrettruth/fugitive-ts.nvim',
      dependencies = { 'tpope/vim-fugitive' },
      opts = {},
    }
<
The plugin works automatically with no configuration required. For
customization, see |fugitive-ts-config|.

==============================================================================
CONFIGURATION                                               *fugitive-ts-config*

                                                          *fugitive-ts.Config*
    Fields: ~
        {enabled}            (boolean, default: true)
                             Enable or disable highlighting globally.

        {debug}              (boolean, default: false)
                             Enable debug logging to |:messages| with
                             `[fugitive-ts]` prefix.

        {languages}          (table<string, string>, default: {})
                             Custom filename to treesitter language mappings.
                             Useful for non-standard file extensions.
                             Example: >lua
                                 languages = {
                                   ['.envrc'] = 'bash',
                                   ['Justfile'] = 'just',
                                 }
<
        {disabled_languages} (string[], default: {})
                             Treesitter language names to skip highlighting.
                             Example: >lua
                                 disabled_languages = { 'markdown', 'text' }
<
        {highlight_headers}  (boolean, default: true)
                             Highlight function context in hunk headers.
                             The context portion of `@@ -10,3 +10,4 @@ func()`
                             will receive treesitter highlighting.

        {debounce_ms}        (integer, default: 50)
                             Debounce delay in milliseconds for re-highlighting
                             after buffer changes. Lower values feel snappier
                             but use more CPU.

        {max_lines_per_hunk} (integer, default: 500)
                             Skip treesitter highlighting for hunks larger than
                             this many lines. Prevents lag on massive diffs.

Example Configuration ~
>lua
    require('fugitive-ts').setup({
      enabled = true,
      debug = false,
      languages = {},
      disabled_languages = {},
      highlight_headers = true,
      debounce_ms = 50,
      max_lines_per_hunk = 500,
    })
<
==============================================================================
API                                                            *fugitive-ts-api*

setup({opts})                                           *fugitive-ts.setup()*
    Configure the plugin. Called automatically by lazy.nvim when using `opts`.

    Parameters: ~
        {opts}  (|fugitive-ts.Config|, optional) Configuration table.

attach({bufnr})                                         *fugitive-ts.attach()*
    Manually attach highlighting to a buffer. Called automatically for
    fugitive buffers via the `FileType fugitive` autocmd.

    Parameters: ~
        {bufnr}  (integer, optional) Buffer number. Defaults to current buffer.

refresh({bufnr})                                       *fugitive-ts.refresh()*
    Manually refresh highlighting for a buffer. Useful after external changes
    or for debugging.

    Parameters: ~
        {bufnr}  (integer, optional) Buffer number. Defaults to current buffer.

==============================================================================
IMPLEMENTATION                                    *fugitive-ts-implementation*

1. The `FileType fugitive` autocmd triggers |fugitive-ts.attach()|
2. The buffer is parsed to detect file headers (`M path/to/file.lua`) and
   hunk headers (`@@ -10,3 +10,4 @@`)
3. For each hunk:
   - Language is detected from the filename using |vim.filetype.match()|
   - Diff prefixes (`+`/`-`/` `) are stripped from code lines
   - Code is parsed with |vim.treesitter.get_string_parser()|
   - Treesitter highlights are applied as extmarks at priority 200
   - A `Normal` extmark at priority 199 clears underlying diff colors
4. Re-highlighting occurs on `TextChanged` (debounced) and `Syntax` events

==============================================================================
KNOWN LIMITATIONS                                   *fugitive-ts-limitations*

Syntax Highlighting Flash ~
                                                     *fugitive-ts-flash*
When opening a fugitive buffer, there is an unavoidable visual "flash" where
the buffer briefly shows fugitive's default diff highlighting before
fugitive-ts.nvim applies treesitter highlights.

This occurs because fugitive-ts.nvim hooks into the `FileType fugitive` event,
which fires after vim-fugitive has already painted the buffer. Even with
`debounce_ms = 0`, the re-painting goes through Neovim's event loop.

To minimize the flash, use a low debounce value: >lua
    require('fugitive-ts').setup({
      debounce_ms = 0,
    })
<
See https://github.com/barrettruth/fugitive-ts.nvim/issues/18 for discussion
and potential solutions.

==============================================================================
HEALTH CHECK                                             *fugitive-ts-health*

Run |:checkhealth| fugitive-ts to verify your setup.

Checks performed:
- Neovim version >= 0.9.0
- vim-fugitive is installed

==============================================================================
 vim:tw=78:ts=8:ft=help:norl: