---
title: libfossil
---
# libfossil
```go
import "github.com/danmestas/go-libfossil"
```
## Index
- [Constants](<#constants>)
- [Variables](<#variables>)
- [func Clone\(ctx context.Context, path string, t Transport, opts CloneOpts\) \(\*Repo, \*CloneResult, error\)](<#Clone>)
- [func JulianToTime\(j float64\) time.Time](<#JulianToTime>)
- [func TimeToJulian\(t time.Time\) float64](<#TimeToJulian>)
- [type AnnotateOpts](<#AnnotateOpts>)
- [type AnnotatedLine](<#AnnotatedLine>)
- [type BisectSession](<#BisectSession>)
- [type BuggifyChecker](<#BuggifyChecker>)
- [type Checkout](<#Checkout>)
- [func \(c \*Checkout\) Add\(patterns \[\]string\) \(int, error\)](<#Checkout.Add>)
- [func \(c \*Checkout\) Checkin\(opts CheckoutCommitOpts\) \(int64, string, error\)](<#Checkout.Checkin>)
- [func \(c \*Checkout\) Close\(\) error](<#Checkout.Close>)
- [func \(c \*Checkout\) Dir\(\) string](<#Checkout.Dir>)
- [func \(c \*Checkout\) Extract\(rid int64, opts ExtractOpts\) error](<#Checkout.Extract>)
- [func \(c \*Checkout\) HasChanges\(\) \(bool, error\)](<#Checkout.HasChanges>)
- [func \(c \*Checkout\) Remove\(patterns \[\]string\) error](<#Checkout.Remove>)
- [func \(c \*Checkout\) Rename\(oldName, newName string\) error](<#Checkout.Rename>)
- [func \(c \*Checkout\) Revert\(opts RevertOpts\) error](<#Checkout.Revert>)
- [func \(c \*Checkout\) Status\(\) \(\[\]CheckoutChange, error\)](<#Checkout.Status>)
- [func \(c \*Checkout\) Update\(opts UpdateOpts\) \(UpdateResult, error\)](<#Checkout.Update>)
- [func \(c \*Checkout\) Version\(\) \(int64, string, error\)](<#Checkout.Version>)
- [func \(c \*Checkout\) WouldFork\(\) \(bool, error\)](<#Checkout.WouldFork>)
- [type CheckoutChange](<#CheckoutChange>)
- [type CheckoutCommitOpts](<#CheckoutCommitOpts>)
- [type CheckoutCreateOpts](<#CheckoutCreateOpts>)
- [type CheckoutObserver](<#CheckoutObserver>)
- [func NopCheckoutObserver\(\) CheckoutObserver](<#NopCheckoutObserver>)
- [func StdoutCheckoutObserver\(\) CheckoutObserver](<#StdoutCheckoutObserver>)
- [type CheckoutOpenOpts](<#CheckoutOpenOpts>)
- [type CheckpointMode](<#CheckpointMode>)
- [type CloneOpts](<#CloneOpts>)
- [type CloneResult](<#CloneResult>)
- [type CommitEnd](<#CommitEnd>)
- [type CommitOpts](<#CommitOpts>)
- [type CommitStart](<#CommitStart>)
- [type CreateOpts](<#CreateOpts>)
- [type Cursor](<#Cursor>)
- [type DiffEntry](<#DiffEntry>)
- [type EventKind](<#EventKind>)
- [type ExtractEnd](<#ExtractEnd>)
- [type ExtractOpts](<#ExtractOpts>)
- [type ExtractStart](<#ExtractStart>)
- [type FileEntry](<#FileEntry>)
- [type FileToCommit](<#FileToCommit>)
- [type Fork](<#Fork>)
- [type FslError](<#FslError>)
- [func \(e \*FslError\) Error\(\) string](<#FslError.Error>)
- [func \(e \*FslError\) Unwrap\(\) error](<#FslError.Unwrap>)
- [type FslID](<#FslID>)
- [type FslSize](<#FslSize>)
- [type HTTPOption](<#HTTPOption>)
- [func WithHTTPClient\(c \*http.Client\) HTTPOption](<#WithHTTPClient>)
- [type HandleEnd](<#HandleEnd>)
- [type HandleOpts](<#HandleOpts>)
- [type HandleStart](<#HandleStart>)
- [type LogEntry](<#LogEntry>)
- [type LogOpts](<#LogOpts>)
- [type MergeConflict](<#MergeConflict>)
- [type MergeConflictError](<#MergeConflictError>)
- [func \(e \*MergeConflictError\) Error\(\) string](<#MergeConflictError.Error>)
- [func \(e \*MergeConflictError\) Is\(target error\) bool](<#MergeConflictError.Is>)
- [type MergeResult](<#MergeResult>)
- [type MockTransport](<#MockTransport>)
- [func \(t \*MockTransport\) RoundTrip\(\_ context.Context, payload \[\]byte\) \(\[\]byte, error\)](<#MockTransport.RoundTrip>)
- [type PullOpts](<#PullOpts>)
- [type RC](<#RC>)
- [func \(rc RC\) String\(\) string](<#RC.String>)
- [type Repo](<#Repo>)
- [func Create\(path string, opts CreateOpts\) \(\*Repo, error\)](<#Create>)
- [func Open\(path string\) \(\*Repo, error\)](<#Open>)
- [func \(r \*Repo\) Ancestry\(opts LogOpts\) \(\[\]LogEntry, error\)](<#Repo.Ancestry>)
- [func \(r \*Repo\) Annotate\(opts AnnotateOpts\) \(\[\]AnnotatedLine, error\)](<#Repo.Annotate>)
- [func \(r \*Repo\) BranchTip\(name string\) \(int64, error\)](<#Repo.BranchTip>)
- [func \(r \*Repo\) Checkpoint\(mode CheckpointMode\) error](<#Repo.Checkpoint>)
- [func \(r \*Repo\) Close\(\) error](<#Repo.Close>)
- [func \(r \*Repo\) Commit\(opts CommitOpts\) \(int64, string, error\)](<#Repo.Commit>)
- [func \(r \*Repo\) Config\(key string\) \(string, error\)](<#Repo.Config>)
- [func \(r \*Repo\) CreateCheckout\(dir string, opts CheckoutCreateOpts\) \(\*Checkout, error\)](<#Repo.CreateCheckout>)
- [func \(r \*Repo\) CreateUser\(opts UserOpts\) error](<#Repo.CreateUser>)
- [func \(r \*Repo\) DB\(\) \*db.DB](<#Repo.DB>)
- [func \(r \*Repo\) DeleteUser\(login string\) error](<#Repo.DeleteUser>)
- [func \(r \*Repo\) DetectForks\(\) \(\[\]Fork, error\)](<#Repo.DetectForks>)
- [func \(r \*Repo\) Diff\(ridA, ridB int64, filePath string\) \(\[\]DiffEntry, error\)](<#Repo.Diff>)
- [func \(r \*Repo\) FindCommonAncestor\(ridA, ridB int64\) \(int64, error\)](<#Repo.FindCommonAncestor>)
- [func \(r \*Repo\) GetUser\(login string\) \(User, error\)](<#Repo.GetUser>)
- [func \(r \*Repo\) HandleSync\(ctx context.Context, payload \[\]byte\) \(\[\]byte, error\)](<#Repo.HandleSync>)
- [func \(r \*Repo\) HandleSyncWithOpts\(ctx context.Context, payload \[\]byte, opts HandleOpts\) \(\[\]byte, error\)](<#Repo.HandleSyncWithOpts>)
- [func \(r \*Repo\) Inner\(\) \*repo.Repo](<#Repo.Inner>)
- [func \(r \*Repo\) ListConflictForks\(\) \(\[\]string, error\)](<#Repo.ListConflictForks>)
- [func \(r \*Repo\) ListFiles\(rid int64\) \(\[\]FileEntry, error\)](<#Repo.ListFiles>)
- [func \(r \*Repo\) ListUsers\(\) \(\[\]User, error\)](<#Repo.ListUsers>)
- [func \(r \*Repo\) Merge\(srcBranch, dstBranch, message, user string\) \(int64, string, error\)](<#Repo.Merge>)
- [func \(r \*Repo\) OpenCheckout\(dir string, opts CheckoutOpenOpts\) \(\*Checkout, error\)](<#Repo.OpenCheckout>)
- [func \(r \*Repo\) Path\(\) string](<#Repo.Path>)
- [func \(r \*Repo\) Pull\(ctx context.Context, url string, opts PullOpts\) \(\*SyncResult, error\)](<#Repo.Pull>)
- [func \(r \*Repo\) ReadFile\(rid int64, filePath string\) \(\[\]byte, error\)](<#Repo.ReadFile>)
- [func \(r \*Repo\) ReadFileAt\(version string, filePath string\) \(\[\]byte, error\)](<#Repo.ReadFileAt>)
- [func \(r \*Repo\) Redo\(dir string\) error](<#Repo.Redo>)
- [func \(r \*Repo\) ResolveConflictFork\(filename string\) error](<#Repo.ResolveConflictFork>)
- [func \(r \*Repo\) ResolveVersion\(name string\) \(int64, error\)](<#Repo.ResolveVersion>)
- [func \(r \*Repo\) ServeHTTP\(ctx context.Context, addr string\) error](<#Repo.ServeHTTP>)
- [func \(r \*Repo\) SetCaps\(login, caps string\) error](<#Repo.SetCaps>)
- [func \(r \*Repo\) SetConfig\(key, value string\) error](<#Repo.SetConfig>)
- [func \(r \*Repo\) SetPassword\(login, password string\) error](<#Repo.SetPassword>)
- [func \(r \*Repo\) StashApply\(dir string, id int64\) error](<#Repo.StashApply>)
- [func \(r \*Repo\) StashClear\(\) error](<#Repo.StashClear>)
- [func \(r \*Repo\) StashDrop\(id int64\) error](<#Repo.StashDrop>)
- [func \(r \*Repo\) StashList\(\) \(\[\]StashEntry, error\)](<#Repo.StashList>)
- [func \(r \*Repo\) StashPop\(dir string\) error](<#Repo.StashPop>)
- [func \(r \*Repo\) StashSave\(dir, comment string\) error](<#Repo.StashSave>)
- [func \(r \*Repo\) Sync\(ctx context.Context, t Transport, opts SyncOpts\) \(\*SyncResult, error\)](<#Repo.Sync>)
- [func \(r \*Repo\) Tag\(opts TagOpts\) \(int64, error\)](<#Repo.Tag>)
- [func \(r \*Repo\) Timeline\(opts TimelineOpts\) \(\[\]TimelineEntry, error\)](<#Repo.Timeline>)
- [func \(r \*Repo\) UUIDFromRID\(rid int64\) \(string, error\)](<#Repo.UUIDFromRID>)
- [func \(r \*Repo\) UVDelete\(name string, mtime time.Time\) error](<#Repo.UVDelete>)
- [func \(r \*Repo\) UVList\(\) \(\[\]UVEntry, error\)](<#Repo.UVList>)
- [func \(r \*Repo\) UVRead\(name string\) \(\[\]byte, int64, string, error\)](<#Repo.UVRead>)
- [func \(r \*Repo\) UVWrite\(name string, content \[\]byte, mtime time.Time\) error](<#Repo.UVWrite>)
- [func \(r \*Repo\) Undo\(dir string\) error](<#Repo.Undo>)
- [func \(r \*Repo\) Verify\(\) error](<#Repo.Verify>)
- [func \(r \*Repo\) WithTx\(fn func\(tx \*db.Tx\) error\) error](<#Repo.WithTx>)
- [func \(r \*Repo\) XferHandler\(\) http.HandlerFunc](<#Repo.XferHandler>)
- [type RevertOpts](<#RevertOpts>)
- [type RoundStats](<#RoundStats>)
- [type ScanEnd](<#ScanEnd>)
- [type SessionEnd](<#SessionEnd>)
- [type SessionStart](<#SessionStart>)
- [type StashEntry](<#StashEntry>)
- [type StatusEntry](<#StatusEntry>)
- [type SyncObserver](<#SyncObserver>)
- [func NopSyncObserver\(\) SyncObserver](<#NopSyncObserver>)
- [func StdoutSyncObserver\(\) SyncObserver](<#StdoutSyncObserver>)
- [type SyncOpts](<#SyncOpts>)
- [type SyncResult](<#SyncResult>)
- [type TableSyncEnd](<#TableSyncEnd>)
- [type TableSyncStart](<#TableSyncStart>)
- [type TagOpts](<#TagOpts>)
- [type TagSpec](<#TagSpec>)
- [type TimelineEntry](<#TimelineEntry>)
- [type TimelineOpts](<#TimelineOpts>)
- [type Transport](<#Transport>)
- [func NewHTTPTransport\(url string, opts ...HTTPOption\) Transport](<#NewHTTPTransport>)
- [type TransportFunc](<#TransportFunc>)
- [func \(f TransportFunc\) RoundTrip\(ctx context.Context, payload \[\]byte\) \(\[\]byte, error\)](<#TransportFunc.RoundTrip>)
- [type UVEntry](<#UVEntry>)
- [type UpdateChange](<#UpdateChange>)
- [type UpdateOpts](<#UpdateOpts>)
- [type UpdateResult](<#UpdateResult>)
- [type User](<#User>)
- [type UserOpts](<#UserOpts>)
## Constants
```go
const (
CheckpointPassive = db.CheckpointPassive
CheckpointFull = db.CheckpointFull
CheckpointRestart = db.CheckpointRestart
CheckpointTruncate = db.CheckpointTruncate
)
```
```go
const (
PhantomSize FslSize = fsltype.PhantomSize
FossilApplicationID int32 = fsltype.FossilApplicationID
)
```
## Variables
ErrAmbiguousVersion is returned by ResolveVersion when a UUID prefix matches more than one artifact \(collision\). Callers can match with errors.Is.
```go
var ErrAmbiguousVersion = errors.New("libfossil: ambiguous version prefix")
```
ErrArtifactNotFound is returned by UUIDFromRID when the given RID does not correspond to any artifact in the repository's blob table. Callers can match with errors.Is.
```go
var ErrArtifactNotFound = errors.New("libfossil: artifact not found")
```
ErrFileNotFound is returned by ReadFile when the requested filePath is not tracked in the given checkin. Callers can match with errors.Is.
```go
var ErrFileNotFound = errors.New("libfossil: file not found in checkin")
```
ErrMergeConflict is returned \(wrapped in a MergeConflictError\) when Merge detects any unresolved three\-way conflicts. Callers can check with errors.Is\(err, ErrMergeConflict\) without caring about the file list.
```go
var ErrMergeConflict = errors.New("libfossil: merge has conflicts")
```
ErrVersionNotFound is returned by ResolveVersion when the requested version string does not match any artifact in the repository. Callers can match with errors.Is.
```go
var ErrVersionNotFound = errors.New("libfossil: version not found")
```
## func [Clone]()
```go
func Clone(ctx context.Context, path string, t Transport, opts CloneOpts) (*Repo, *CloneResult, error)
```
Clone performs a full repository clone from a remote Fossil server. It creates a new repository at the given path, runs the clone protocol until convergence, and returns the opened Repo handle and a result summary. On error, the partially\-created repo file is removed.
## func [JulianToTime]()
```go
func JulianToTime(j float64) time.Time
```
JulianToTime converts a Fossil Julian day number to time.Time.
## func [TimeToJulian]()
```go
func TimeToJulian(t time.Time) float64
```
TimeToJulian converts a time.Time to a Fossil Julian day number.
## type [AnnotateOpts]()
AnnotateOpts configures an annotate operation.
```go
type AnnotateOpts struct {
FilePath string
StartRID int64
}
```
## type [AnnotatedLine]()
AnnotatedLine is a single line of blame/annotate output.
```go
type AnnotatedLine struct {
Text string
UUID string
User string
Date time.Time
}
```
## type [BisectSession]()
BisectSession holds state for a binary\-search bisect operation.
```go
type BisectSession struct {
// contains filtered or unexported fields
}
```
## type [BuggifyChecker]()
BuggifyChecker controls fault injection for deterministic simulation testing.
```go
type BuggifyChecker interface {
Check(site string, probability float64) bool
}
```
## type [Checkout]()
Checkout represents a working directory linked to a Fossil repository. A Checkout is not safe for concurrent use. Callers must serialize access to a single Checkout instance.
```go
type Checkout struct {
// contains filtered or unexported fields
}
```
### func \(\*Checkout\) [Add]()
```go
func (c *Checkout) Add(patterns []string) (int, error)
```
Add adds files to version tracking. Returns the number of files added. Files already tracked are silently skipped.
### func \(\*Checkout\) [Checkin]()
```go
func (c *Checkout) Checkin(opts CheckoutCommitOpts) (int64, string, error)
```
Checkin creates a new checkin from the checkout working directory. Returns the RID and UUID of the new checkin manifest.
### func \(\*Checkout\) [Close]()
```go
func (c *Checkout) Close() error
```
Close closes the checkout database. Does NOT close the repo.
### func \(\*Checkout\) [Dir]()
```go
func (c *Checkout) Dir() string
```
Dir returns the checkout directory path.
### func \(\*Checkout\) [Extract]()
```go
func (c *Checkout) Extract(rid int64, opts ExtractOpts) error
```
Extract writes files from the specified checkin to the working directory.
### func \(\*Checkout\) [HasChanges]()
```go
func (c *Checkout) HasChanges() (bool, error)
```
HasChanges returns true if the checkout has any modified, deleted, or renamed files. This is a DB\-only check; call Extract or scan first to detect on\-disk modifications.
### func \(\*Checkout\) [Remove]()
```go
func (c *Checkout) Remove(patterns []string) error
```
Remove removes files from version tracking. Newly added files are deleted from vfile; committed files are marked as deleted.
### func \(\*Checkout\) [Rename]()
```go
func (c *Checkout) Rename(oldName, newName string) error
```
Rename marks a tracked file as renamed and moves it on disk.
### func \(\*Checkout\) [Revert]()
```go
func (c *Checkout) Revert(opts RevertOpts) error
```
Revert restores files to their checkout version state. If opts.Files is empty, reverts all changed files.
### func \(\*Checkout\) [Status]()
```go
func (c *Checkout) Status() ([]CheckoutChange, error)
```
Status scans the working directory for changes and returns a list of changed files. Wraps ScanChanges \+ VisitChanges.
### func \(\*Checkout\) [Update]()
```go
func (c *Checkout) Update(opts UpdateOpts) (UpdateResult, error)
```
Update updates the checkout to a new version, performing 3\-way merge where needed to preserve local modifications. See UpdateResult for how to distinguish a clean update from one that wrote conflict markers into working\-tree files.
### func \(\*Checkout\) [Version]()
```go
func (c *Checkout) Version() (int64, string, error)
```
Version returns the current checkout version \(RID and UUID\).
### func \(\*Checkout\) [WouldFork]()
```go
func (c *Checkout) WouldFork() (bool, error)
```
WouldFork reports whether committing on the current branch would create a fork. Returns true when another leaf exists on the same branch.
## type [CheckoutChange]()
CheckoutChange describes a single file change in the checkout.
```go
type CheckoutChange struct {
Name string
Change string // "added", "modified", "deleted", "renamed", "missing"
}
```
## type [CheckoutCommitOpts]()
CommitOpts configures creating a checkin from the checkout. \(This type is distinct from the existing libfossil.CommitOpts which takes explicit file content for direct repo commits without a checkout.\)
```go
type CheckoutCommitOpts struct {
Message string
User string
Branch string // empty = current branch
Tags []string // additional tag names
Delta bool
}
```
## type [CheckoutCreateOpts]()
CheckoutCreateOpts configures creating a new checkout.
```go
type CheckoutCreateOpts struct {
Env *simio.Env // nil = real env
Observer CheckoutObserver // nil = nop
}
```
## type [CheckoutObserver]()
CheckoutObserver receives lifecycle callbacks during checkout/commit operations. Use NopCheckoutObserver\(\) for a silent no\-op, or StdoutCheckoutObserver\(\) for stderr logging.
```go
type CheckoutObserver interface {
ExtractStarted(info ExtractStart)
ExtractFileCompleted(name string, change UpdateChange)
ExtractCompleted(info ExtractEnd)
ScanStarted(dir string)
ScanCompleted(info ScanEnd)
CommitStarted(info CommitStart)
CommitCompleted(info CommitEnd)
Error(err error)
}
```
### func [NopCheckoutObserver]()
```go
func NopCheckoutObserver() CheckoutObserver
```
NopCheckoutObserver returns a CheckoutObserver that silently discards all events.
### func [StdoutCheckoutObserver]()
```go
func StdoutCheckoutObserver() CheckoutObserver
```
StdoutCheckoutObserver returns a CheckoutObserver that logs events to stderr.
## type [CheckoutOpenOpts]()
CheckoutOpenOpts configures opening an existing checkout.
```go
type CheckoutOpenOpts struct {
SearchParents bool // search parent dirs for .fslckout
Env *simio.Env // nil = real env
Observer CheckoutObserver
}
```
## type [CheckpointMode]()
CheckpointMode mirrors SQLite's PRAGMA wal\_checkpoint\(\\) argument.
```go
type CheckpointMode = db.CheckpointMode
```
## type [CloneOpts]()
CloneOpts configures a clone operation.
```go
type CloneOpts struct {
User string
Password string
Observer SyncObserver
Buggify BuggifyChecker // fault injection for DST (nil = no faults)
}
```
## type [CloneResult]()
CloneResult reports what happened during a clone.
```go
type CloneResult struct {
Rounds int
BlobsRecvd int
ArtifactsLinked int
ProjectCode string
ServerCode string
Messages []string
}
```
## type [CommitEnd]()
CommitEnd describes the completion of a commit operation.
```go
type CommitEnd struct {
UUID string
RID int64
}
```
## type [CommitOpts]()
CommitOpts configures a commit operation.
```go
type CommitOpts struct {
// Files is the caller-supplied subset of the new commit's tree. When
// ParentID is non-zero, Files is MERGED with the parent's tracked files:
// any name in Files overrides the parent's entry, and any file tracked
// at the parent but not in Files is carried forward into the new manifest.
// This matches `fossil ci`'s full-tree semantics — supplying just the
// changed files does not erase the rest of the tree.
Files []FileToCommit
Comment string
User string
Tags []TagSpec
Time time.Time
ParentID int64
// MergeParents lists additional parents for a merge commit. The resulting
// manifest's P-card is [ParentID, MergeParents...]; ParentID is the primary
// parent (branch tip being committed onto), and each MergeParent contributes
// a secondary plink row (isprim=0).
MergeParents []int64
Delta bool
// PartialManifest, when true, skips the parent-file merge: the resulting
// manifest contains only Files. This is the legacy pre-fix behavior and
// effectively erases every file tracked at the parent that is not in
// Files. Default false matches `fossil ci`. Set true only when the
// caller intentionally wants omission-to-mean-deletion (e.g., tests for
// the diff/deletion path); a dedicated deletion API may replace this
// escape hatch later.
PartialManifest bool
}
```
## type [CommitStart]()
CommitStart describes the beginning of a commit operation.
```go
type CommitStart struct {
Comment string
User string
Files int
}
```
## type [CreateOpts]()
CreateOpts configures repository creation.
```go
type CreateOpts struct {
User string
// ProjectCode optionally sets the repo's project-code. Empty
// generates a fresh one (current behavior). When non-empty, must
// be 40-char lowercase hex (^[0-9a-f]{40}$) — matching the format
// of generated project-codes. Invalid values return an error
// before any file is written.
ProjectCode string
// Rand provides random bytes for project-code and server-code generation.
// Nil defaults to crypto/rand (production). Set to simio.NewSeededRand
// for deterministic simulation testing.
Rand simio.Rand
}
```
## type [Cursor]()
Cursor is an opaque pagination token for Timeline. Obtain one from a returned TimelineEntry's Cursor field and pass it back as the next TimelineOpts.After to resume enumeration immediately after that entry. The zero Cursor means "start from the newest event".
Cursor's representation is deliberately hidden: it cannot be constructed from a timestamp and a rid by calling code, only obtained from a TimelineEntry the library already produced. See fsltype.Cursor's doc comment for why — a hand\-built cursor derived from a rounded time.Time is not guaranteed to match the row it claims to follow exactly, which is what silently reintroduces skipped or duplicated rows at a page boundary. LogEntry, Ancestry's result type, has no Cursor field at all: Ancestry's pagination is by Start/Limit, so there is no valid cursor to obtain from it, and the type reflects that instead of documenting it as a hazard.
```go
type Cursor = fsltype.Cursor
```
## type [DiffEntry]()
DiffEntry describes a unified diff for a single file.
```go
type DiffEntry struct {
Name string
Unified string
}
```
## type [EventKind]()
EventKind is the type discriminator on a Timeline entry: one of the single\-letter codes fossil assigns per event.type row. The zero value means "all kinds" — the default Timeline uses when no Type is given.
```go
type EventKind = fsltype.EventKind
```
```go
const (
// EventKindCheckin is a check-in ('ci').
EventKindCheckin EventKind = fsltype.EventKindCheckin
// EventKindTechnote is a technote / event artifact ('e').
EventKindTechnote EventKind = fsltype.EventKindTechnote
// EventKindForum is a forum post ('f').
EventKindForum EventKind = fsltype.EventKindForum
// EventKindTag is a tag/control artifact ('g').
EventKindTag EventKind = fsltype.EventKindTag
// EventKindTicket is a ticket change ('t').
EventKindTicket EventKind = fsltype.EventKindTicket
// EventKindWiki is a wiki page edit ('w').
EventKindWiki EventKind = fsltype.EventKindWiki
)
```
## type [ExtractEnd]()
ExtractEnd describes the completion of a checkout extraction.
```go
type ExtractEnd struct {
FilesWritten int
}
```
## type [ExtractOpts]()
ExtractOpts configures file extraction from a checkin.
```go
type ExtractOpts struct {
Force bool // overwrite uncommitted changes
}
```
## type [ExtractStart]()
ExtractStart describes the beginning of a checkout extraction.
```go
type ExtractStart struct {
RID int64
Dir string
}
```
## type [FileEntry]()
FileEntry describes a file in a manifest.
```go
type FileEntry struct {
Name string
UUID string
Perm string
}
```
## type [FileToCommit]()
FileToCommit describes a file to include in a commit.
```go
type FileToCommit struct {
Name string
Content []byte
Perm string
}
```
## type [Fork]()
Fork describes a divergence point between two branches.
```go
type Fork struct {
Ancestor int64
LocalTip int64
RemoteTip int64
}
```
## type [FslError]()
```go
type FslError struct {
Code RC
Msg string
Cause error
}
```
### func \(\*FslError\) [Error]()
```go
func (e *FslError) Error() string
```
### func \(\*FslError\) [Unwrap]()
```go
func (e *FslError) Unwrap() error
```
## type [FslID]()
FslID is a row\-id in the blob table \(content\-addressed artifacts\).
```go
type FslID = fsltype.FslID
```
## type [FslSize]()
FslSize represents a blob size; negative values indicate phantom blobs.
```go
type FslSize = fsltype.FslSize
```
## type [HTTPOption]()
HTTPOption configures an HTTP transport.
```go
type HTTPOption func(*httpTransport)
```
### func [WithHTTPClient]()
```go
func WithHTTPClient(c *http.Client) HTTPOption
```
WithHTTPClient sets a custom http.Client for the transport.
## type [HandleEnd]()
HandleEnd describes the completion of a server\-side sync handle.
```go
type HandleEnd struct {
FilesSent, FilesRecvd int
}
```
## type [HandleOpts]()
HandleOpts configures server\-side sync handling.
```go
type HandleOpts struct {
Observer SyncObserver
Buggify BuggifyChecker
}
```
## type [HandleStart]()
HandleStart describes the beginning of a server\-side sync handle.
```go
type HandleStart struct {
RemoteAddr string
}
```
## type [LogEntry]()
LogEntry represents a single event, as returned by Ancestry. Parents is populated for Kind == EventKindCheckin and empty for every other kind — plink, which Parents is derived from, only relates check\-in artifacts, so that is correct, not a gap.
LogEntry carries no pagination cursor: Ancestry paginates by LogOpts.Start/Limit, not by cursor, so there would be nothing valid to put in one. See TimelineEntry, Timeline's result type, for the cursor\-carrying counterpart — this split means an Ancestry entry's \(necessarily invalid\) cursor can no longer be obtained at all, let alone passed to Timeline by mistake.
```go
type LogEntry struct {
RID int64
UUID string
Comment string
User string
Time time.Time
Kind EventKind
Parents []string
}
```
## type [LogOpts]()
LogOpts configures an Ancestry query: a first\-parent walk starting from a specific check\-in.
```go
type LogOpts struct {
Start int64
Limit int
}
```
## type [MergeConflict]()
MergeConflict describes a conflict region in a file.
```go
type MergeConflict struct {
Name string
StartLine int
EndLine int
}
```
## type [MergeConflictError]()
MergeConflictError reports which files had unresolved merge conflicts. Files is sorted alphabetically for deterministic output.
```go
type MergeConflictError struct {
Files []string
}
```
### func \(\*MergeConflictError\) [Error]()
```go
func (e *MergeConflictError) Error() string
```
### func \(\*MergeConflictError\) [Is]()
```go
func (e *MergeConflictError) Is(target error) bool
```
## type [MergeResult]()
MergeResult describes the outcome of a merge.
```go
type MergeResult struct {
Clean bool
Conflicts []MergeConflict
}
```
## type [MockTransport]()
MockTransport is a test double that delegates to a handler function.
```go
type MockTransport struct {
Handler func(req []byte) []byte
}
```
### func \(\*MockTransport\) [RoundTrip]()
```go
func (t *MockTransport) RoundTrip(_ context.Context, payload []byte) ([]byte, error)
```
RoundTrip calls the Handler function if set, otherwise returns empty bytes.
## type [PullOpts]()
PullOpts configures a pull\-only sync. Fields are a subset of SyncOpts; Pull is hard\-coded true and Push is hard\-coded false to keep the API surface honest about what Pull does.
```go
type PullOpts struct {
// ProjectCode optionally pins the expected server project code. Empty
// accepts whatever the peer advertises (matches existing Sync semantics).
ProjectCode string
// MaxSend caps the bytes the client will send per round (mostly clones
// of clients with UV files). Zero leaves the existing default in place.
MaxSend int
// Observer receives sync-progress events. nil disables observation.
Observer SyncObserver
}
```
## type [RC]()
```go
type RC int
```
```go
const (
RCOK RC = 0
RCError RC = 100
RCNYI RC = 101
RCOOM RC = 102
RCMisuse RC = 103
RCRange RC = 104
RCAccess RC = 105
RCIO RC = 106
RCNotFound RC = 107
RCAlreadyExists RC = 108
RCConsistency RC = 109
RCRepoNeedsRebuild RC = 110
RCNotARepo RC = 111
RCRepoVersion RC = 112
RCDB RC = 113
RCBreak RC = 114
RCStepRow RC = 115
RCStepDone RC = 116
RCStepError RC = 117
RCType RC = 118
RCNotACkout RC = 119
RCRepoMismatch RC = 120
RCChecksumMismatch RC = 121
RCLocked RC = 122
RCConflict RC = 123
RCSizeMismatch RC = 124
RCPhantom RC = 125
RCUnsupported RC = 126
)
```
### func \(RC\) [String]()
```go
func (rc RC) String() string
```
## type [Repo]()
Repo is an opaque handle to a Fossil repository.
```go
type Repo struct {
// contains filtered or unexported fields
}
```
### func [Create]()
```go
func Create(path string, opts CreateOpts) (*Repo, error)
```
Create creates a new Fossil repository at the given path.
### func [Open]()
```go
func Open(path string) (*Repo, error)
```
Open opens an existing Fossil repository.
### func \(\*Repo\) [Ancestry]()
```go
func (r *Repo) Ancestry(opts LogOpts) ([]LogEntry, error)
```
Ancestry walks the primary\-parent chain starting from opts.Start: it emits that check\-in, follows plink where isprim=1 to its parent, and repeats until the chain ends or opts.Limit is reached. This only ever sees first\-parent ancestors of opts.Start — a merge's second parent, a sibling branch head, or any check\-in outside that one chain will never appear. Use Timeline for a repository\-wide view.
### func \(\*Repo\) [Annotate]()
```go
func (r *Repo) Annotate(opts AnnotateOpts) ([]AnnotatedLine, error)
```
Annotate attributes each line of a file to the commit that last changed it.
### func \(\*Repo\) [BranchTip]()
```go
func (r *Repo) BranchTip(name string) (int64, error)
```
BranchTip returns the RID of the most recent checkin on the named branch. Resolves via the 'branch' propagating tag: the tip is the checkin with the latest event.mtime whose tagxref still has that branch value active. Returns an error if no such branch exists in the repository.
### func \(\*Repo\) [Checkpoint]()
```go
func (r *Repo) Checkpoint(mode CheckpointMode) error
```
Checkpoint runs PRAGMA wal\_checkpoint\(\\) against the repository. Safe to call on a live repo. CheckpointPassive is non\-blocking and appropriate for periodic background checkpoints. CheckpointTruncate produces a maximally compact on\-disk file readable by external fossil tooling without a subsequent Close.
### func \(\*Repo\) [Close]()
```go
func (r *Repo) Close() error
```
Close closes the repository and releases resources. As part of close, a WAL TRUNCATE checkpoint is run so the on\-disk repo file is readable by external fossil/SQLite tooling.
### func \(\*Repo\) [Commit]()
```go
func (r *Repo) Commit(opts CommitOpts) (int64, string, error)
```
Commit creates a new checkin manifest with the given files and returns the RID \(row ID\) and UUID of the newly created artifact. When ParentID is non\-zero, files tracked at the parent but absent from opts.Files are carried forward into the new manifest \(full\-tree semantics — see the CommitOpts.Files doc\).
### func \(\*Repo\) [Config]()
```go
func (r *Repo) Config(key string) (string, error)
```
Config reads a configuration value from the repo's config table.
### func \(\*Repo\) [CreateCheckout]()
```go
func (r *Repo) CreateCheckout(dir string, opts CheckoutCreateOpts) (*Checkout, error)
```
CreateCheckout creates a new checkout directory linked to this repository. The directory is created if it does not exist. The checkout is initialized to the tip checkin.
### func \(\*Repo\) [CreateUser]()
```go
func (r *Repo) CreateUser(opts UserOpts) error
```
CreateUser creates a new user in the repository.
### func \(\*Repo\) [DB]()
```go
func (r *Repo) DB() *db.DB
```
DB returns the underlying database handle for raw SQL queries. Use this when the high\-level Repo methods don't cover your use case.
### func \(\*Repo\) [DeleteUser]()
```go
func (r *Repo) DeleteUser(login string) error
```
DeleteUser removes a user from the repository.
### func \(\*Repo\) [DetectForks]()
```go
func (r *Repo) DetectForks() ([]Fork, error)
```
DetectForks finds divergent branches in the repository.
### func \(\*Repo\) [Diff]()
```go
func (r *Repo) Diff(ridA, ridB int64, filePath string) ([]DiffEntry, error)
```
Diff returns the unified diff\(s\) between ridA and ridB.
When filePath is non\-empty, returns 0 or 1 entries for that single file: the file is treated as empty bytes on any side where it is absent, so additions and deletions render as pure insert/delete hunks. An empty slice is returned when both sides are byte\-identical.
When filePath is empty, returns one entry per file that changed between the two checkins \(the union of files across both sides where the content UUID differs or the file exists on only one side\). Entries are sorted by Name for deterministic ordering. An empty slice is returned when the two checkins have identical file sets and content.
Whole\-checkin enumeration is currently name\-keyed: a rename with no content change surfaces as a delete of the old name plus an add of the new name, and permission\-only changes are not reflected. Proper rename and perm\-change detection \(via the underlying mlink table\) is tracked as a follow\-up; per\-file diff behaviour for an explicitly named file is unchanged.
### func \(\*Repo\) [FindCommonAncestor]()
```go
func (r *Repo) FindCommonAncestor(ridA, ridB int64) (int64, error)
```
FindCommonAncestor finds the nearest common ancestor of two checkins.
### func \(\*Repo\) [GetUser]()
```go
func (r *Repo) GetUser(login string) (User, error)
```
GetUser returns information about a user.
### func \(\*Repo\) [HandleSync]()
```go
func (r *Repo) HandleSync(ctx context.Context, payload []byte) ([]byte, error)
```
HandleSync processes an incoming xfer request \(server\-side\). The payload is a raw xfer\-encoded byte slice; the response is also raw bytes.
### func \(\*Repo\) [HandleSyncWithOpts]()
```go
func (r *Repo) HandleSyncWithOpts(ctx context.Context, payload []byte, opts HandleOpts) ([]byte, error)
```
HandleSyncWithOpts processes an incoming xfer request with optional configuration.
### func \(\*Repo\) [Inner]()
```go
func (r *Repo) Inner() *repo.Repo
```
Inner returns the underlying internal repo handle. This is exported for use by in\-module packages \(e.g., cli/\) that need direct access to the repo DB for raw SQL or internal package calls.
### func \(\*Repo\) [ListConflictForks]()
```go
func (r *Repo) ListConflictForks() ([]string, error)
```
ListConflictForks returns filenames with unresolved conflict\-fork entries.
### func \(\*Repo\) [ListFiles]()
```go
func (r *Repo) ListFiles(rid int64) ([]FileEntry, error)
```
ListFiles returns the files in a manifest identified by blob row\-id.
### func \(\*Repo\) [ListUsers]()
```go
func (r *Repo) ListUsers() ([]User, error)
```
ListUsers returns all users in the repository.
### func \(\*Repo\) [Merge]()
```go
func (r *Repo) Merge(srcBranch, dstBranch, message, user string) (int64, string, error)
```
Merge performs a three\-way merge of srcBranch into dstBranch and creates a merge commit whose primary parent is dstBranch's tip and whose secondary parent is srcBranch's tip. Returns \(rid, uuid\) of the new commit on success.
Conflict policy: any unresolved conflict in any file aborts the whole operation with a \*MergeConflictError — no commit is written. Callers should check errors.Is\(err, ErrMergeConflict\) to detect this case.
File handling:
- Present on both sides: three\-way merge against the common ancestor.
- Present on only one side \(new file\): kept as\-is.
- In ancestor, missing on one side, unchanged on the other: agreed deletion.
- In ancestor, missing on one side, modified on the other: modify/delete conflict.
### func \(\*Repo\) [OpenCheckout]()
```go
func (r *Repo) OpenCheckout(dir string, opts CheckoutOpenOpts) (*Checkout, error)
```
OpenCheckout opens an existing checkout directory linked to this repository.
### func \(\*Repo\) [Path]()
```go
func (r *Repo) Path() string
```
Path returns the filesystem path to the repository file.
### func \(\*Repo\) [Pull]()
```go
func (r *Repo) Pull(ctx context.Context, url string, opts PullOpts) (*SyncResult, error)
```
Pull fetches commits and ancillary objects from a Fossil HTTP peer and applies them to this repo. It is a strict pull — nothing is sent.
Tiger Style: hostile inputs panic via assert at the boundary; transport failures return wrapped errors. Idempotent on a repo already at peer's tip \(returns a SyncResult with Rounds=0–1 and FilesRecvd=0\).
### func \(\*Repo\) [ReadFile]()
```go
func (r *Repo) ReadFile(rid int64, filePath string) ([]byte, error)
```
ReadFile returns the bytes of filePath as they existed in checkin rid. Returns ErrFileNotFound \(wrapped\) if the file is not tracked in that checkin. A file that exists but is empty returns \(\[\]byte\{\}, nil\).
### func \(\*Repo\) [ReadFileAt]()
```go
func (r *Repo) ReadFileAt(version string, filePath string) ([]byte, error)
```
ReadFileAt reads filePath from the checkin identified by a symbolic version name \(e.g. "tip", "trunk", a branch name, a UUID, or a UUID prefix\). It calls ResolveVersion to obtain the RID, then delegates to ReadFile. Use ReadFile directly when you already have a numeric RID.
### func \(\*Repo\) [Redo]()
```go
func (r *Repo) Redo(dir string) error
```
Redo re\-applies the last undone operation. Requires a checkout database; not yet wired.
### func \(\*Repo\) [ResolveConflictFork]()
```go
func (r *Repo) ResolveConflictFork(filename string) error
```
ResolveConflictFork marks a conflict\-fork entry as resolved.
### func \(\*Repo\) [ResolveVersion]()
```go
func (r *Repo) ResolveVersion(name string) (int64, error)
```
ResolveVersion resolves a symbolic version name to a repository artifact RID.
Resolution order:
1. "" or "tip" — newest checkin by mtime from the event table.
2. "trunk" — tip of the trunk branch via tagxref/tag; falls back to "tip" if the repository has no trunk tag.
3. Named branch — tag lookup for "sym\-\" in tagxref/tag \(e.g. "feature\-x" resolves via sym\-feature\-x\).
4. Full UUID \(≥40 chars\) — exact match against blob.uuid.
5. UUID prefix \(4–39 chars\) — unique\-prefix match; returns ErrAmbiguousVersion if more than one artifact matches.
An empty result or no match returns ErrVersionNotFound \(wrapped\). An ambiguous prefix returns ErrAmbiguousVersion \(wrapped\).
### func \(\*Repo\) [ServeHTTP]()
```go
func (r *Repo) ServeHTTP(ctx context.Context, addr string) error
```
ServeHTTP starts an HTTP server that accepts Fossil xfer requests. Blocks until ctx is cancelled.
### func \(\*Repo\) [SetCaps]()
```go
func (r *Repo) SetCaps(login, caps string) error
```
SetCaps updates a user's capability string.
### func \(\*Repo\) [SetConfig]()
```go
func (r *Repo) SetConfig(key, value string) error
```
SetConfig writes a configuration value to the repo's config table.
### func \(\*Repo\) [SetPassword]()
```go
func (r *Repo) SetPassword(login, password string) error
```
SetPassword updates a user's password.
### func \(\*Repo\) [StashApply]()
```go
func (r *Repo) StashApply(dir string, id int64) error
```
StashApply restores a stash entry by ID without removing it.
### func \(\*Repo\) [StashClear]()
```go
func (r *Repo) StashClear() error
```
StashClear removes all stash entries.
### func \(\*Repo\) [StashDrop]()
```go
func (r *Repo) StashDrop(id int64) error
```
StashDrop removes a stash entry by ID.
### func \(\*Repo\) [StashList]()
```go
func (r *Repo) StashList() ([]StashEntry, error)
```
StashList returns all stash entries.
### func \(\*Repo\) [StashPop]()
```go
func (r *Repo) StashPop(dir string) error
```
StashPop restores the most recent stash entry and removes it.
### func \(\*Repo\) [StashSave]()
```go
func (r *Repo) StashSave(dir, comment string) error
```
StashSave saves working\-tree changes to the stash. Requires a checkout database; not yet wired \(Repo only wraps the repo DB\).
### func \(\*Repo\) [Sync]()
```go
func (r *Repo) Sync(ctx context.Context, t Transport, opts SyncOpts) (*SyncResult, error)
```
Sync runs a sync session against the given transport.
### func \(\*Repo\) [Tag]()
```go
func (r *Repo) Tag(opts TagOpts) (int64, error)
```
Tag creates a control artifact that adds a tag to a target checkin. Returns the UUID of the tag control artifact.
### func \(\*Repo\) [Timeline]()
```go
func (r *Repo) Timeline(opts TimelineOpts) ([]TimelineEntry, error)
```
Timeline enumerates the repository's events newest\-first: every row of the event table by default, or just the rows matching opts.Type when set \(canonical \`fossil timeline\`'s \-t/\-\-type default: no filter unless one is given\). Unlike Ancestry, this does not start from or require any particular check\-in — it is a repository\-wide view, not a walk.
Ordering is \(mtime DESC, rid DESC\), a total order with rid as a true tie\-break at exact mtime equality — a deliberate improvement over canonical fossil, which orders by mtime DESC alone with no tie\-break, and paginates with a bare\-timestamp web cursor carrying a one\-second slop, so rows at a page boundary there can repeat or be skipped. Do not "fix" this back to canonical: it is intentional. To page through the full result set, pass the last entry's Cursor back as the next call's TimelineOpts.After — never construct a cursor from a TimelineEntry's Time by hand; see Cursor's doc comment for why that round trip is lossy.
### func \(\*Repo\) [UUIDFromRID]()
```go
func (r *Repo) UUIDFromRID(rid int64) (string, error)
```
UUIDFromRID returns the UUID \(manifest hash\) of the artifact identified by rid. The UUID is the stable, content\-addressed identifier for the artifact; the rid is a repository\-local integer that may differ across clones.
Returns ErrArtifactNotFound \(wrapped\) if no artifact with the given rid exists in the repository. The wrapped error message includes the offending rid. Other errors surface as\-is.
### func \(\*Repo\) [UVDelete]()
```go
func (r *Repo) UVDelete(name string, mtime time.Time) error
```
UVDelete marks an unversioned file as deleted \(tombstone\).
### func \(\*Repo\) [UVList]()
```go
func (r *Repo) UVList() ([]UVEntry, error)
```
UVList returns all unversioned file entries.
### func \(\*Repo\) [UVRead]()
```go
func (r *Repo) UVRead(name string) ([]byte, int64, string, error)
```
UVRead reads an unversioned file from the repository. Returns the content, mtime \(unix seconds\), and content hash.
### func \(\*Repo\) [UVWrite]()
```go
func (r *Repo) UVWrite(name string, content []byte, mtime time.Time) error
```
UVWrite writes an unversioned file to the repository.
### func \(\*Repo\) [Undo]()
```go
func (r *Repo) Undo(dir string) error
```
Undo reverts the last commit or merge. Requires a checkout database; not yet wired.
### func \(\*Repo\) [Verify]()
```go
func (r *Repo) Verify() error
```
Verify checks repository integrity \(blob checksums, delta chains\).
### func \(\*Repo\) [WithTx]()
```go
func (r *Repo) WithTx(fn func(tx *db.Tx) error) error
```
WithTx executes fn within a database transaction.
### func \(\*Repo\) [XferHandler]()
```go
func (r *Repo) XferHandler() http.HandlerFunc
```
XferHandler returns an http.HandlerFunc that decodes Fossil xfer requests, dispatches to HandleSync, and encodes the response. Use this to compose a custom mux alongside operational endpoints \(e.g., /healthz\).
## type [RevertOpts]()
RevertOpts configures reverting file changes.
```go
type RevertOpts struct {
Files []string // empty = revert all
}
```
## type [RoundStats]()
RoundStats describes the outcome of a single sync round.
```go
type RoundStats struct {
FilesSent, FilesRecvd, BytesSent, BytesRecvd, Gimmes, IGots int
}
```
## type [ScanEnd]()
ScanEnd describes the completion of a working\-tree scan.
```go
type ScanEnd struct {
FilesScanned int
}
```
## type [SessionEnd]()
SessionEnd describes the completion of a sync session.
```go
type SessionEnd struct {
Rounds, FilesSent, FilesRecvd int
}
```
## type [SessionStart]()
SessionStart describes the beginning of a sync session.
```go
type SessionStart struct {
ProjectCode string
Push, Pull, UV bool
}
```
## type [StashEntry]()
StashEntry describes a saved stash.
```go
type StashEntry struct {
ID int64
Comment string
Time string
}
```
## type [StatusEntry]()
StatusEntry describes a changed file in the working tree.
```go
type StatusEntry struct {
Name string
Change string
}
```
## type [SyncObserver]()
SyncObserver receives lifecycle callbacks during sync operations. Use NopSyncObserver\(\) for a silent no\-op, or StdoutSyncObserver\(\) for stderr logging.
```go
type SyncObserver interface {
Started(info SessionStart)
RoundStarted(round int)
RoundCompleted(round int, stats RoundStats)
Completed(info SessionEnd)
Error(err error)
HandleStarted(info HandleStart)
HandleCompleted(info HandleEnd)
TableSyncStarted(info TableSyncStart)
TableSyncCompleted(info TableSyncEnd)
}
```
### func [NopSyncObserver]()
```go
func NopSyncObserver() SyncObserver
```
NopSyncObserver returns a SyncObserver that silently discards all events.
### func [StdoutSyncObserver]()
```go
func StdoutSyncObserver() SyncObserver
```
StdoutSyncObserver returns a SyncObserver that logs events to stderr.
## type [SyncOpts]()
SyncOpts configures a sync operation.
```go
type SyncOpts struct {
Push bool
Pull bool
UV bool
ProjectCode string
ServerCode string
User string
Password string
PeerID string // identifies this leaf agent instance
MaxSend int
XTableSync bool // enable extension table sync (peer_registry, etc.)
Private bool // enable private artifact sync
Observer SyncObserver
Buggify BuggifyChecker
}
```
## type [SyncResult]()
SyncResult describes the outcome of a sync session.
```go
type SyncResult struct {
Rounds int
FilesSent int
FilesRecvd int
UVFilesSent int
UVFilesRecvd int
UVGimmesSent int
BytesSent int64
BytesRecvd int64
Errors []string
}
```
## type [TableSyncEnd]()
TableSyncEnd describes the completion of a config table sync.
```go
type TableSyncEnd struct {
Table string
RowsSent, RowsRecvd int
}
```
## type [TableSyncStart]()
TableSyncStart describes the beginning of a config table sync.
```go
type TableSyncStart struct {
Table string
}
```
## type [TagOpts]()
TagOpts configures a tag operation.
```go
type TagOpts struct {
Name string
TargetID int64
Value string
User string
Time time.Time
}
```
## type [TagSpec]()
TagSpec describes a tag to attach to an artifact.
```go
type TagSpec struct {
Name string
Value string
}
```
## type [TimelineEntry]()
TimelineEntry represents a single event as returned by Timeline. It extends LogEntry with Cursor, the pagination token for this row: pass it back as the next call's TimelineOpts.After to resume enumeration immediately after this entry. Cursor is always valid \(Cursor.Valid\(\) == true\) on every TimelineEntry Timeline produces.
TimelineEntry values should come from Timeline, not be hand\-assembled. A TimelineEntry built by embedding a LogEntry from Ancestry carries a zero\-value Cursor, which Timeline treats as "start from newest" rather than as an error.
```go
type TimelineEntry struct {
LogEntry
Cursor Cursor
}
```
## type [TimelineOpts]()
TimelineOpts configures a Timeline query: a repository\-wide enumeration of the event table.
```go
type TimelineOpts struct {
// Type restricts the enumeration to a single event kind. The zero
// value means "all kinds" — the canonical `fossil timeline` default.
Type EventKind
// After, when valid, resumes enumeration immediately following this
// cursor — the next page after whatever TimelineEntry produced it. The
// zero Cursor means "start from the newest event". See Repo.Timeline's
// doc comment for the pagination contract this forms, and Cursor's doc
// comment for why it must come from a TimelineEntry rather than be
// built by hand.
After Cursor
// Limit caps the number of entries returned. Zero or negative means
// unbounded.
Limit int
}
```
## type [Transport]()
Transport delivers sync payloads between peers. Implementations handle the network layer \(HTTP, NATS, etc.\). Payloads are opaque zlib\-compressed xfer card streams.
```go
type Transport interface {
RoundTrip(ctx context.Context, payload []byte) ([]byte, error)
}
```
### func [NewHTTPTransport]()
```go
func NewHTTPTransport(url string, opts ...HTTPOption) Transport
```
NewHTTPTransport creates a Transport that speaks Fossil's HTTP /xfer protocol.
## type [TransportFunc]()
TransportFunc adapts a plain function to the Transport interface. This is the Transport equivalent of http.HandlerFunc.
```go
type TransportFunc func(ctx context.Context, payload []byte) ([]byte, error)
```
### func \(TransportFunc\) [RoundTrip]()
```go
func (f TransportFunc) RoundTrip(ctx context.Context, payload []byte) ([]byte, error)
```
RoundTrip calls the function.
## type [UVEntry]()
UVEntry describes an unversioned file.
```go
type UVEntry struct {
Name string
Size int64
Mtime time.Time
Hash string
}
```
## type [UpdateChange]()
UpdateChange classifies how a file changed.
```go
type UpdateChange string
```
```go
const (
ChangeAdded UpdateChange = "added"
ChangeModified UpdateChange = "modified"
ChangeDeleted UpdateChange = "deleted"
)
```
## type [UpdateOpts]()
UpdateOpts configures updating to a new version with merge.
```go
type UpdateOpts struct {
TargetRID int64 // 0 = tip
}
```
## type [UpdateResult]()
UpdateResult reports what Update actually did. Paths, not counts: a caller needs to know which files to show a user, not merely how many changed. All three slices are sorted \(sort.Strings\) before Update returns, so the order is deterministic — safe for golden\-file tests or reflect.DeepEqual — rather than depending on Go's randomized map iteration order.
Outcome mapping \(Update's error return is the other half of this\):
```
clean - err == nil, Conflicted empty
conflicted - err == nil, Conflicted non-empty
failed - err != nil, UpdateResult is the zero value
```
A non\-empty Conflicted means three\-way merge could not resolve those files cleanly and wrote "\<\<\<\<\<\<\<"\-style conflict markers directly into them on disk. That is NOT an error — Update still returns a nil error, because the update itself succeeded and the working tree is usable; it just isn't clean. A caller that only checks the returned error gets today's pre\-conflict\-detection behavior. A caller that needs to warn a user about marker text in their files must check Conflicted. Every path in Conflicted also appears in FilesWritten: the marker text is what was written there.
```go
type UpdateResult struct {
FilesWritten []string // paths written (added, updated, or merged, clean or not); includes every Conflicted path
FilesRemoved []string // paths deleted from the working tree
Conflicted []string // paths that now contain conflict markers — not an error; also present in FilesWritten
}
```
## type [User]()
User describes a Fossil user.
```go
type User struct {
Login string
Caps string
}
```
## type [UserOpts]()
UserOpts configures a user creation or update.
```go
type UserOpts struct {
Login string
Password string
Caps string
}
```
Generated by [gomarkdoc]()