Help us shape the future of Go! Take the 2026 Go Developer Survey

diffpos

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 27, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

Documentation

Overview

Package diffpos computes where an inline comment lands: GitLab's diff position for a line of a merge request's diff, from the file's unified diff and the diff version's refs (docs/architecture.md §7.4). It makes no request.

The numbering follows GitLab's own parser, read at gitlab-org/gitlab 829b21d284863743bde419836a053626309d02f6 (lib/gitlab/diff/parser.rb, lib/gitlab/diff/line.rb, lib/gitlab/git.rb): both counters start at a hunk header's positions; a context line advances both, an added line the new one and a removed line the old one; a "\ No newline" line advances neither. Every line carries both counters, so a removed line's line_code names the new side's position too:

line_code = sha1(new_path, or old_path when empty) "_" old "_" new

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Error

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

Error is a line the diff cannot place. Its message names what to pass instead; the caller attaches the class.

func (*Error) Error

func (e *Error) Error() string

type File

type File struct {
	OldPath, NewPath string
	// Diff is GitLab's unified diff for the file: hunks, each starting
	// "@@ -a,b +c,d @@". Empty when GitLab withheld it.
	Diff string
}

File is one file of the diff version.

type Hunk

type Hunk struct {
	OldStart, OldEnd, NewStart, NewEnd int
	// contains filtered or unexported fields
}

Hunk is one hunk's line ranges, for a caller to name.

func Parse

func Parse(diff string) ([]Hunk, error)

Parse reads a unified diff into hunks. Lines before the first hunk header, such as "---" and "+++" file headers, are skipped.

type Kind

type Kind string

Kind is what the change did to a line.

const (
	Added     Kind = "added"
	Removed   Kind = "removed"
	Unchanged Kind = "unchanged"
)

The kinds.

type Line

type Line struct {
	Kind Kind
	// Old and New are GitLab's counters at the line. For an added line
	// Old is where it sits between old lines, and for a removed line New
	// is where it sits between new lines: both go into line_code, and
	// only the side the line exists on goes into a position.
	Old, New int
}

Line is one line of the diff as GitLab numbers it.

func (Line) Code

func (l Line) Code(f File) string

Code is the line's line_code in file f.

func (Line) NewLine

func (l Line) NewLine() *int

NewLine is the new-side line number a position carries, nil for a removed line.

func (Line) OldLine

func (l Line) OldLine() *int

OldLine is the old-side line number a position carries, nil for an added line.

type LineRange

type LineRange struct {
	Start RangeEnd `json:"start"`
	End   RangeEnd `json:"end"`
}

LineRange is a multi-line comment's first and last line.

type Placed

type Placed struct {
	Position Position
	Start    Line
	End      Line
}

Placed is where a comment was computed to land: the position to send and the lines it covers, first to last.

func Compute

func Compute(refs Refs, f File, side Side, line, endLine int) (Placed, error)

Compute places a comment on line (and through endLine, when it is not zero) on side of file f. Both ends must be in the same hunk of the diff: a line the diff does not show has no position GitLab can draw.

type Position

type Position struct {
	BaseSHA      string     `json:"base_sha"`
	StartSHA     string     `json:"start_sha"`
	HeadSHA      string     `json:"head_sha"`
	PositionType string     `json:"position_type"`
	OldPath      string     `json:"old_path"`
	NewPath      string     `json:"new_path"`
	OldLine      *int       `json:"old_line,omitempty"`
	NewLine      *int       `json:"new_line,omitempty"`
	LineRange    *LineRange `json:"line_range,omitempty"`
}

Position is GitLab's position for a diff note, as the draft notes and discussions APIs take it.

type RangeEnd

type RangeEnd struct {
	LineCode string `json:"line_code"`
	Type     string `json:"type,omitempty"`
	OldLine  *int   `json:"old_line,omitempty"`
	NewLine  *int   `json:"new_line,omitempty"`
}

RangeEnd is one end of a LineRange.

type Refs

type Refs struct {
	BaseSHA, StartSHA, HeadSHA string
}

Refs are the diff version's commits.

type Side

type Side string

Side is which version of the file a line number counts in.

const (
	// New counts lines of the file after the change.
	New Side = "new"
	// Old counts lines of the file before the change.
	Old Side = "old"
)

The sides.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL