multibuffer

Documentation

Overview

Package multibuffer renders fragments stitched from multiple files into one scrollable surface. The first slice (v0.13.0) is read-only: each fragment shows a header (path + line range) followed by the lines from the source file with markers for added / context lines. Enter on any row fires an OpenAtMsg the host uses to open that file in the editor at the row's line.

The single load source so far is `git diff --unified=3 HEAD` — every modified hunk from working tree against HEAD, including staged and unstaged. Future loaders (workspace symbol references, find-all-results) will return the same []Fragment shape.

Editable multibuffer (edits flowing back to source) is intentionally deferred. Read-only is a complete and useful slice on its own.

Index

• func LoadDiffCmd(root, base string) tea.Cmd
• type CancelMsg
• type Fragment
  • func Parse(diff []byte, root string) ([]Fragment, error)
• type FragmentsMsg
• type Line
• type Marker
• type OpenAtMsg
• type Pane
  • func NewPane(t theme.Theme, root string) Pane
  • func (p Pane) Blur() Pane
  • func (p Pane) Err() error
  • func (p Pane) Focus() Pane
  • func (p Pane) Focused() bool
  • func (p Pane) Fragments() []Fragment
  • func (p Pane) Reset(title string) Pane
  • func (p Pane) Selected() (string, int, bool)
  • func (p Pane) SetFragments(frags []Fragment, err error) Pane
  • func (p Pane) Title() string
  • func (p Pane) Update(msg tea.Msg) (Pane, tea.Cmd)
  • func (p Pane) View() string
  • func (p Pane) WithSize(w, h int) Pane

Functions

func LoadDiffCmd

func LoadDiffCmd(root, base string) tea.Cmd

LoadDiffCmd is a tea.Cmd that runs `git diff --no-color --unified=3 base` and returns a FragmentsMsg with the parsed hunks. base may be "" (working tree vs index — staged-only changes are excluded) or "HEAD" (working tree vs HEAD — covers staged and unstaged together) or any other rev. When the command exits non-zero, the err is wrapped in the message and the pane shows it in place of the fragment list.

Types

type CancelMsg

type CancelMsg struct{}

CancelMsg fires on Esc.

type Fragment

type Fragment struct {
	Path      string // absolute
	StartLine int    // 1-based, first line in the source file
	EndLine   int    // 1-based, last line in the source file
	Lines     []Line // ordered top-to-bottom
	Suffix    string // optional, e.g. function name from "@@ -... @@ <suffix>"
}

Fragment is a contiguous slice of one file rendered together.

func Parse

func Parse(diff []byte, root string) ([]Fragment, error)

Parse extracts fragments from unified-diff output. Each `@@` hunk becomes one Fragment. The walker tracks the current new-file line counter through each hunk's body so every emitted Line gets the correct 1-based row in the new file.

Inputs:

• diff: the raw `git diff` output (any number of files)
• root: optional repo root used to absolutize the b/<path> the diff emits; pass "" to keep paths as-is.

Pure-deletion hunks (oldCount > 0, newCount == 0) produce no Fragment because there's nothing in the new file to anchor on. The gitgutter package surfaces those via a DeletedAbove marker on the line below.

type FragmentsMsg

type FragmentsMsg struct {
	Fragments []Fragment
	Source    string // "diff" / "references" / "search" — informational
	Err       error
}

FragmentsMsg is the async response from a load command.

type Line

type Line struct {
	Marker   Marker
	FileLine int // 1-based row in the source file
	Text     string
}

Line is one displayed line within a Fragment.

type Marker

type Marker int

Marker is the per-line annotation in a fragment. Context lines are unchanged in the diff; Added lines were inserted. (Modified is unused for diff-source fragments — git's unified diff models a modification as a delete + add pair, both of which the parser surfaces individually.)

const (
	Context Marker = iota
	Added
	Modified
)

type OpenAtMsg

type OpenAtMsg struct {
	Path string
	Line int // 1-based
}

OpenAtMsg fires when the user presses Enter on a fragment row.

type Pane

type Pane struct {
	// contains filtered or unexported fields
}

Pane is the multibuffer UI model. Construct with NewPane, populate with SetFragments (typically the response from LoadDiffCmd), focus via Focus. Pane is a value type — pass-by-value, return-by-value.

func NewPane

func NewPane(t theme.Theme, root string) Pane

NewPane constructs an empty pane rooted at root. The root is used only for path relativization in the header; absolute paths in fragments are preserved untouched.

func (Pane) Blur

func (p Pane) Blur() Pane

Blur sets focused=false.

func (Pane) Err

func (p Pane) Err() error

Err returns the load error, if any.

func (Pane) Focus

func (p Pane) Focus() Pane

Focus sets focused=true.

func (Pane) Focused

func (p Pane) Focused() bool

Focused reports keyboard focus.

func (Pane) Fragments

func (p Pane) Fragments() []Fragment

Fragments returns the current fragment slice (read-only — callers must not mutate the underlying lines slice).

func (Pane) Reset

func (p Pane) Reset(title string) Pane

Reset clears state and prepares for a new load. Title shows above the fragment list while the load is in flight.

func (Pane) Selected

func (p Pane) Selected() (string, int, bool)

Selected returns (path, line, true) for the row under the cursor. Header rows resolve to (frag.Path, frag.StartLine); content rows resolve to (frag.Path, line.FileLine). Separators and out-of-range cursors return (empty, 0, false).

func (Pane) SetFragments

func (p Pane) SetFragments(frags []Fragment, err error) Pane

SetFragments replaces displayed fragments and rebuilds row positions. Cursor lands on the first non-separator row.

func (Pane) Title

func (p Pane) Title() string

Title returns the human-readable title (e.g. "uncommitted changes").

func (Pane) Update

func (p Pane) Update(msg tea.Msg) (Pane, tea.Cmd)

Update routes a key event. Esc emits CancelMsg, Enter emits OpenAtMsg for the currently-selected row.

func (Pane) View

func (p Pane) View() string

View renders the pane to a single string.

func (Pane) WithSize

func (p Pane) WithSize(w, h int) Pane

WithSize sets render dimensions. The pane will clamp internal computations against these on every View call.