treemerge

package
v0.20.0 Latest Latest
Warning

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

Go to latest
Published: Nov 11, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Overview

Package treemerge merges three versions of a set of files: a base, and two sides ("ours" and "theirs") that each changed it. It answers what each path becomes, the merged files' content, and the conflicts it couldn't decide. docs/designs/treemerge.md is its design.

It's pure: no file system, network, git or anfra state. Callers hand it the three versions as trees of blob ids, and a way to read a blob's content.

git's merge is the baseline: for any input, the result is git's, or a conflict where git would have resolved. The text of a file both sides changed is merged by textmerge.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Render

func Render(ctx context.Context, c ConflictInfo, blobs BlobReader, o Options) ([]byte, error)

Render writes a conflict's file with markers, from its blob ids alone: the same bytes Merge wrote. Only conflicts with markers have a rendering.

func Resolved

func Resolved(c ConflictInfo, current []byte, exists bool) bool

Resolved says whether a conflict is resolved, from its file's current content. A file deleted is resolved, as a deletion. A file still holding a marker-like line of the conflict's marker size isn't. A conflict without markers is resolved only by taking a side.

Types

type BlobReader

type BlobReader interface {
	ReadBlob(ctx context.Context, id string) ([]byte, error)
}

BlobReader reads a file's content by blob id.

type Change

type Change struct {
	Path string
	Blob string
}

Change is a path's content after taking a side: a blob id, or "" to delete the path.

func Take

func Take(c ConflictInfo, side Side) []Change

Take resolves a conflict by taking one side's version of every path it covers, as `git checkout --ours` and `--theirs` do. An absent version means the path is deleted.

type ConflictInfo

type ConflictInfo struct {
	Kind  Kind
	Files []Version
	// MarkerSize is the size of the markers written into the file, for the
	// kinds a file shows with markers. 0: the conflict has no markers, and is
	// resolved only by taking a side.
	MarkerSize int
}

ConflictInfo is a conflict as data: its kind, every path it covers with its three versions, and its marker size. Markers are rendered from it (Render), so a caller can keep it and show the conflict its own way.

type Kind

type Kind string

Kind is why a conflict is one: a stable code callers branch on and show. The names follow the conflict types git's merge reports.

const (
	// Content: both sides changed a text file, and the changes overlap or touch.
	Content Kind = "content"
	// AddAdd: both sides added a text file at the same path, and their lines
	// conflict.
	AddAdd Kind = "add_add"
	// ModifyDelete: ours changed a file theirs deleted.
	ModifyDelete Kind = "modify_delete"
	// DeleteModify: ours deleted a file theirs changed.
	DeleteModify Kind = "delete_modify"
	// Binary: both sides changed a binary file differently.
	Binary Kind = "binary"
	// FileFolder: a path is a file in the merge, and a folder too.
	FileFolder Kind = "file_folder"
	// PathCollision: two paths in the merge would be one file on a system that
	// ignores case or Unicode form.
	PathCollision Kind = "path_collision"
)

type Labels

type Labels struct{ Ours, Base, Theirs string }

Labels name the sides in conflict markers: "<<<<<<< ours (local)". Empty labels leave the markers bare.

type Options

type Options struct {
	Labels Labels
	// MaxFileSize, when above 0, treats larger files as binary: never merged
	// by lines.
	MaxFileSize int
}

Options are how Merge treats files and writes conflicts.

type Outcome

type Outcome string

Outcome is what happened to a path.

const (
	// Unchanged: both sides have the same version, the base's or a change
	// both made.
	Unchanged Outcome = "unchanged"
	// Ours: only ours changed it, so ours' version is kept.
	Ours Outcome = "ours"
	// Theirs: only theirs changed it, so theirs' version is taken.
	Theirs Outcome = "theirs"
	// Merged: both changed it, and the text merged cleanly.
	Merged Outcome = "merged"
	// Conflict: treemerge won't decide it. PathResult.Conflict says why.
	Conflict Outcome = "conflict"
	// NeedsMerge: both changed its content, so deciding needs the content.
	// Only Classify answers it: Merge answers Merged or Conflict instead.
	NeedsMerge Outcome = "needs_merge"
)

type PathResult

type PathResult struct {
	Version
	Outcome Outcome
	// Conflict is set when Outcome is Conflict. Paths a conflict covers
	// together share it.
	Conflict *ConflictInfo
	// Result is the path's content after the merge, as a blob id: the
	// version kept or taken, the merged file, or the file with conflict
	// markers. "" means the path doesn't exist after the merge. A conflict
	// without markers keeps ours' version.
	Result string
}

PathResult is what the merge decided for one path, with its three versions.

func Classify

func Classify(base, ours, theirs Tree) []PathResult

Classify decides each path from blob ids alone, reading no content. A path both sides changed differently is NeedsMerge: whether it merges cleanly needs its content. It answers whether a merge would change ours, cheaply enough to ask before every publish.

type Result

type Result struct {
	Paths    []PathResult
	NewBlobs map[string][]byte
	// Conflicts is how many conflicts there are. One conflict can cover
	// several paths.
	Conflicts int
}

Result is a merge: every path in any of the three trees, sorted, and the content of the files the merge made (merged, or with markers), by blob id.

func Merge

func Merge(ctx context.Context, base, ours, theirs Tree, blobs BlobReader, o Options) (Result, error)

Merge merges the three trees. Content is read only for paths both sides changed.

type Side

type Side int

Side is a side of a merge, to take.

const (
	TakeOurs Side = iota + 1
	TakeTheirs
)

type Tree

type Tree map[string]string

Tree is a set of files: slash-separated path → blob id, git's blob id of the file's bytes (repoformat.BlobID).

type Version

type Version struct {
	Path               string
	Base, Ours, Theirs string
}

Version is one path's three versions, as blob ids. "" is absent.

Jump to

Keyboard shortcuts

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