gitgutter

Documentation

Overview

Package gitgutter computes per-line diff markers (added / modified / deleted) for a file by shelling out to `git diff` against the index.

The host calls Compute (or the matching tea.Cmd factory MarkerCmd) when it opens or saves a file; the returned Markers map is handed to the editor pane which paints each marked row's gutter with a colored sigil.

Three states are surfaced:

• Added — a line present in the working tree but not in the index. This includes every line of an untracked file (compared against /dev/null) and lines newly inserted into a tracked file.
• Modified — a line whose content differs between working tree and index. Pure replacements ("oldCount > 0 && newCount > 0") in unified diff terms.
• DeletedAbove — a line in the working tree immediately following a stretch of lines that were deleted relative to the index. Painted on the surviving line below the deletion (Zed / VS Code convention).

Files outside a git repository, binary files, or paths git cannot read produce an empty map and a non-nil error. The host treats this as "no markers" and the editor renders an unadorned gutter.

Index

• func Compute(ctx context.Context, root, path string) (map[int]Marker, error)
• func MarkerCmd(root, path string) tea.Cmd
• func Parse(diff []byte) map[int]Marker
• type Marker
  • func (m Marker) String() string
• type MarkersMsg

Functions

func Compute

func Compute(ctx context.Context, root, path string) (map[int]Marker, error)

Compute runs git against the working tree to produce the per-line markers for path. Returns an empty map (and nil error) when the file is tracked and clean; an empty map with a non-nil error when git itself failed or the file is outside any git repo.

Untracked files are detected via `git ls-files --error-unmatch` and then treated as wholly-added by reading the working-tree file's line count.

func MarkerCmd

func MarkerCmd(root, path string) tea.Cmd

MarkerCmd returns a tea.Cmd that runs Compute in a background goroutine and wraps the result into a MarkersMsg. Callers pin path at call time so a late response can be discarded if the active buffer has moved on.

We deliberately do NOT thread a context here — the cost of a `git diff --unified=0` on a single file is bounded and the host fires this only on open/save (not per-keystroke). If a future profile demands cancellation the signature can grow a context without breaking callers.

func Parse

func Parse(diff []byte) map[int]Marker

Parse extracts per-row markers from unified-diff output. The input may contain output for any number of files, in any order; Parse takes them all (the caller is expected to pass output for the file it cares about). Row indices in the returned map are 0-based positions in the WORKING-TREE file.

Types

type Marker

type Marker int

Marker is a per-line diff state. Zero value (None) means the line is unchanged relative to the index.

const (
	None Marker = iota
	Added
	Modified
	DeletedAbove
)

func (Marker) String

func (m Marker) String() string

String renders the marker as a short tag for tests and debug logs.

type MarkersMsg

type MarkersMsg struct {
	Path    string
	Markers map[int]Marker
	Err     error
}

MarkersMsg is the response from MarkerCmd. Path is the absolute path the markers belong to; the host compares against the active buffer's path before applying so a late response for an old buffer is dropped.