Artifact [97aae38d01]

Artifact 97aae38d01b4f078178e177f2a9b519976ec4e5cbe8e5a3a6555e217ad2dbea8:

• File docs/site/content/docs/reference/sdk/libfossil/api.md — part of check-in [245a0ed306] at 2026-10-20 02:08:49 on branch feat/submanifest-reader — conformance: re-pin the three drafts to their -00 names

  zit check-in 68a3f76cb7 renames the artifact-format, repo-state and sync-protocol drafts from -01 to -00 in their headers, cross-references and reference entries, and retitles each Changes appendix "Changes in This Revision". No normative text changed and no section number moved.

  The pinned copies take zit's file names, the requirement tables pin the new hashes, and the comments, tests and docs that cited the -01 drafts cite the -00 ones. The refresh script copies every draft under its own name. The sparse-cone copy is re-pinned to d497c2432f, whose text is unchanged. Coverage counts are identical before and after. (user: [email protected], size: 86610) [annotate] [blame] [check-ins using] [more...]

---
title: libfossil
---

<!-- Code generated by gomarkdoc. DO NOT EDIT -->

# 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\) \(rid int64, uuid string, err error\)](<#Checkout.Checkin>)
  - [func \(c \*Checkout\) Close\(\) error](<#Checkout.Close>)
  - [func \(c \*Checkout\) Conflicts\(\) \(\[\]string, error\)](<#Checkout.Conflicts>)
  - [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\) Merge\(opts CheckoutMergeOpts\) \(CheckoutMergeResult, error\)](<#Checkout.Merge>)
  - [func \(c \*Checkout\) Remove\(patterns \[\]string\) error](<#Checkout.Remove>)
  - [func \(c \*Checkout\) Rename\(oldName, newName string\) error](<#Checkout.Rename>)
  - [func \(c \*Checkout\) ResolveVersion\(name string\) \(int64, error\)](<#Checkout.ResolveVersion>)
  - [func \(c \*Checkout\) ResolveWorking\(name string\) \(WorkingVersion, error\)](<#Checkout.ResolveWorking>)
  - [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 CheckoutMergeFile](<#CheckoutMergeFile>)
- [type CheckoutMergeOpts](<#CheckoutMergeOpts>)
- [type CheckoutMergeResult](<#CheckoutMergeResult>)
- [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 FramedTransport](<#FramedTransport>)
- [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\) BranchOpenLeaf\(name string\) \(rid int64, open bool, err error\)](<#Repo.BranchOpenLeaf>)
  - [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\) CurrentTrunk\(\) \(int64, error\)](<#Repo.CurrentTrunk>)
  - [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\) DisableSubmanifests\(\) error](<#Repo.DisableSubmanifests>)
  - [func \(r \*Repo\) EnableSubmanifests\(k int\) \(pinned int, warning string, err error\)](<#Repo.EnableSubmanifests>)
  - [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\) ResolveBranchStart\(name string\) \(int64, error\)](<#Repo.ResolveBranchStart>)
  - [func \(r \*Repo\) ResolveConflictFork\(filename string\) error](<#Repo.ResolveConflictFork>)
  - [func \(r \*Repo\) ResolveVersion\(name string\) \(int64, error\)](<#Repo.ResolveVersion>)
  - [func \(r \*Repo\) RetuneSubmanifests\(k int\) error](<#Repo.RetuneSubmanifests>)
  - [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\) SetHashPolicy\(name string\) error](<#Repo.SetHashPolicy>)
  - [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>)
- [type WorkingVersion](<#WorkingVersion>)


## Constants

<a name="CheckpointPassive"></a>

```go
const (
    CheckpointPassive  = db.CheckpointPassive
    CheckpointFull     = db.CheckpointFull
    CheckpointRestart  = db.CheckpointRestart
    CheckpointTruncate = db.CheckpointTruncate
)
```

<a name="PhantomSize"></a>

```go
const (
    PhantomSize         FslSize = fsltype.PhantomSize
    FossilApplicationID int32   = fsltype.FossilApplicationID
)
```

## Variables

<a name="ErrAmbiguousVersion"></a>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")
```

<a name="ErrArtifactNotFound"></a>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")
```

<a name="ErrFileNotFound"></a>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")
```

<a name="ErrMergeConflict"></a>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")
```

<a name="ErrVersionNotFound"></a>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")
```

<a name="Clone"></a>
## func [Clone](<https://github.com/danmestas/go-libfossil/blob/main/fossil.go#L89>)

```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. Artifacts the clone rounds leave missing stay phantoms unless opts.PullPhantoms is set.

<a name="JulianToTime"></a>
## func [JulianToTime](<https://github.com/danmestas/go-libfossil/blob/main/julian.go#L15>)

```go
func JulianToTime(j float64) time.Time
```

JulianToTime converts a Fossil Julian day number to time.Time.

<a name="TimeToJulian"></a>
## func [TimeToJulian](<https://github.com/danmestas/go-libfossil/blob/main/julian.go#L10>)

```go
func TimeToJulian(t time.Time) float64
```

TimeToJulian converts a time.Time to a Fossil Julian day number.

<a name="AnnotateOpts"></a>
## type [AnnotateOpts](<https://github.com/danmestas/go-libfossil/blob/main/repo_history.go#L101-L104>)

AnnotateOpts configures an annotate operation.

```go
type AnnotateOpts struct {
    FilePath string
    StartRID int64
}
```

<a name="AnnotatedLine"></a>
## type [AnnotatedLine](<https://github.com/danmestas/go-libfossil/blob/main/repo_history.go#L93-L98>)

AnnotatedLine is a single line of blame/annotate output.

```go
type AnnotatedLine struct {
    Text string
    UUID string
    User string
    Date time.Time
}
```

<a name="BisectSession"></a>
## type [BisectSession](<https://github.com/danmestas/go-libfossil/blob/main/repo_history.go#L107-L109>)

BisectSession holds state for a binary\-search bisect operation.

```go
type BisectSession struct {
    // contains filtered or unexported fields
}
```

<a name="BuggifyChecker"></a>
## type [BuggifyChecker](<https://github.com/danmestas/go-libfossil/blob/main/observer.go#L36-L38>)

BuggifyChecker controls fault injection for deterministic simulation testing.

```go
type BuggifyChecker interface {
    Check(site string, probability float64) bool
}
```

<a name="Checkout"></a>
## type [Checkout](<https://github.com/danmestas/go-libfossil/blob/main/checkout.go#L16-L18>)

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
}
```

<a name="Checkout.Add"></a>
### func \(\*Checkout\) [Add](<https://github.com/danmestas/go-libfossil/blob/main/checkout.go#L253>)

```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.

<a name="Checkout.Checkin"></a>
### func \(\*Checkout\) [Checkin](<https://github.com/danmestas/go-libfossil/blob/main/checkout.go#L308>)

```go
func (c *Checkout) Checkin(opts CheckoutCommitOpts) (rid int64, uuid string, err error)
```

Checkin creates a new checkin from the checkout working directory: every change, or only opts.Files \(a directory names every tracked file under it\). Pending merges become merge parents. Like fossil's commit, it refuses a name it does not track, a commit with nothing changed and no merge pending \(unless opts.AllowEmpty\), files that still hold merge conflict markers \(unless opts.AllowConflict\), and committing only some files of a pending merge. Returns the RID and UUID of the new checkin manifest.

<a name="Checkout.Close"></a>
### func \(\*Checkout\) [Close](<https://github.com/danmestas/go-libfossil/blob/main/checkout.go#L163>)

```go
func (c *Checkout) Close() error
```

Close closes the checkout database. Does NOT close the repo.

<a name="Checkout.Conflicts"></a>
### func \(\*Checkout\) [Conflicts](<https://github.com/danmestas/go-libfossil/blob/main/checkout.go#L372>)

```go
func (c *Checkout) Conflicts() ([]string, error)
```

Conflicts lists the files, sorted, that hold merge conflict markers: the files a merge or update left in conflict and nobody has resolved yet.

<a name="Checkout.Dir"></a>
### func \(\*Checkout\) [Dir](<https://github.com/danmestas/go-libfossil/blob/main/checkout.go#L171>)

```go
func (c *Checkout) Dir() string
```

Dir returns the checkout directory path.

<a name="Checkout.Extract"></a>
### func \(\*Checkout\) [Extract](<https://github.com/danmestas/go-libfossil/blob/main/checkout.go#L188>)

```go
func (c *Checkout) Extract(rid int64, opts ExtractOpts) error
```

Extract writes files from the specified checkin to the working directory and makes it the checkout's current version. Unless opts.Force is set it refuses, changing nothing, when the checkout has unsaved changes or when an untracked file sits where the checkin would write different content.

<a name="Checkout.HasChanges"></a>
### func \(\*Checkout\) [HasChanges](<https://github.com/danmestas/go-libfossil/blob/main/checkout.go#L220>)

```go
func (c *Checkout) HasChanges() (bool, error)
```

HasChanges reports whether the checkout has any added, removed, renamed or modified files. It reads only the checkout database, so an edit on disk counts once Status \(or an Extract or Commit\) has scanned it; adds, removals and renames always count. Missing files need the disk; Status reports them.

<a name="Checkout.Merge"></a>
### func \(\*Checkout\) [Merge](<https://github.com/danmestas/go-libfossil/blob/main/checkout.go#L349>)

```go
func (c *Checkout) Merge(opts CheckoutMergeOpts) (CheckoutMergeResult, error)
```

Merge merges another checkin into the checkout, as fossil's merge command does, leaving the result for the next Checkin to commit with the merged\-in checkin as a merge parent. A file both sides changed is merged by its strategy; when the strategy cannot reconcile the changes, fossil's conflict markers are written into the file, and the file is in conflict until they are edited out \(see Conflicts\). A conflicted merge is not an error.

Merge refuses, changing nothing, when the repository lacks content it needs or an added file would overwrite an untracked one. A file edited here but deleted in the merged\-in version is kept and reported. Renames are not followed. Merging the checkout's own version or one of its ancestors does nothing.

<a name="Checkout.Remove"></a>
### func \(\*Checkout\) [Remove](<https://github.com/danmestas/go-libfossil/blob/main/checkout.go#L265>)

```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.

<a name="Checkout.Rename"></a>
### func \(\*Checkout\) [Rename](<https://github.com/danmestas/go-libfossil/blob/main/checkout.go#L276>)

```go
func (c *Checkout) Rename(oldName, newName string) error
```

Rename marks a tracked file as renamed and moves it on disk.

<a name="Checkout.ResolveVersion"></a>
### func \(\*Checkout\) [ResolveVersion](<https://github.com/danmestas/go-libfossil/blob/main/checkout.go#L525>)

```go
func (c *Checkout) ResolveVersion(name string) (int64, error)
```

ResolveVersion resolves name as Repo.ResolveVersion does and also resolves the names relative to this checkout \(repo\-state\-00 Section 8.3\), tried after "tip" and before every other form, as fossil's symbolic\_name\_to\_rid does \(src/name.c\):

```
"current"            the checkout's version
"prev", "previous"   its primary parent
"next"               a child: a primary child first, then the newest link
```

A keyword that names nothing, such as "prev" at a root, falls through to the other forms, as in fossil. The forms that take a name, such as "root:current", resolve it the same way. "ckout" is an ordinary name here: it is a keyword only in the checkout\-inclusive request, ResolveWorking.

<a name="Checkout.ResolveWorking"></a>
### func \(\*Checkout\) [ResolveWorking](<https://github.com/danmestas/go-libfossil/blob/main/checkout.go#L555>)

```go
func (c *Checkout) ResolveWorking(name string) (WorkingVersion, error)
```

ResolveWorking is fossil's checkout\-inclusive request \("ci\+", symbolic\_name\_to\_rid in src/name.c\): while the checkout has a version, "ckout" names its working files, reported as Working. Every other name, and "ckout" in a checkout with no version, resolves as ResolveVersion does, except that only check\-ins can answer: the request is a check\-in request, so a technote or wiki page carrying the tag does not.

As repo\-state\-00 Section 8.3 says, only "ci\+" has the keyword, so ResolveVersion and Repo.ResolveBranchStart read "ckout" as an ordinary name. It is a keyword only as the whole name: in "root:ckout" or "ckout." the inner name is resolved as a plain check\-in request, as in fossil.

<a name="Checkout.Revert"></a>
### func \(\*Checkout\) [Revert](<https://github.com/danmestas/go-libfossil/blob/main/checkout.go#L290>)

```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.

<a name="Checkout.Status"></a>
### func \(\*Checkout\) [Status](<https://github.com/danmestas/go-libfossil/blob/main/checkout.go#L231>)

```go
func (c *Checkout) Status() ([]CheckoutChange, error)
```

Status scans the working directory and returns the changed files, each classified as added, deleted, missing, renamed or modified, the way fossil's changes command classifies them. Wraps ScanChanges \+ VisitChanges.

<a name="Checkout.Update"></a>
### func \(\*Checkout\) [Update](<https://github.com/danmestas/go-libfossil/blob/main/checkout.go#L202>)

```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.

<a name="Checkout.Version"></a>
### func \(\*Checkout\) [Version](<https://github.com/danmestas/go-libfossil/blob/main/checkout.go#L176>)

```go
func (c *Checkout) Version() (int64, string, error)
```

Version returns the current checkout version \(RID and UUID\).

<a name="Checkout.WouldFork"></a>
### func \(\*Checkout\) [WouldFork](<https://github.com/danmestas/go-libfossil/blob/main/checkout.go#L409>)

```go
func (c *Checkout) WouldFork() (bool, error)
```

WouldFork reports whether committing on the checkout's version would create a fork: the version already has a child on its own branch \(for example after a pull\), so the commit would become a second leaf. This is fossil's "Would fork" commit refusal; run Update first, or commit to a new branch. Another open leaf elsewhere on the branch does not count.

<a name="CheckoutChange"></a>
## type [CheckoutChange](<https://github.com/danmestas/go-libfossil/blob/main/checkout.go#L130-L133>)

CheckoutChange describes a single file change in the checkout.

```go
type CheckoutChange struct {
    Name   string
    Change string // "added", "modified", "deleted", "renamed", "missing"
}
```

<a name="CheckoutCommitOpts"></a>
## type [CheckoutCommitOpts](<https://github.com/danmestas/go-libfossil/blob/main/checkout.go#L82-L97>)

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
    // Files limits the commit to these checkout-relative paths; empty
    // commits every change.
    Files []string
    // AllowConflict commits files that still hold merge conflict markers,
    // which Checkin otherwise refuses, as fossil's commit does.
    AllowConflict bool
    // AllowEmpty commits even when nothing changed, which Checkin otherwise
    // refuses, as fossil's commit does.
    AllowEmpty bool
}
```

<a name="CheckoutCreateOpts"></a>
## type [CheckoutCreateOpts](<https://github.com/danmestas/go-libfossil/blob/main/checkout.go#L21-L24>)

CheckoutCreateOpts configures creating a new checkout.

```go
type CheckoutCreateOpts struct {
    Env      *simio.Env       // nil = real env
    Observer CheckoutObserver // nil = nop
}
```

<a name="CheckoutMergeFile"></a>
## type [CheckoutMergeFile](<https://github.com/danmestas/go-libfossil/blob/main/checkout.go#L122-L127>)

CheckoutMergeFile reports what a merge did to one file. Action is one of:

```
"updated"  - only the merged-in version changed it; its content was taken
"merged"   - both sides changed it and the strategy combined them cleanly
"conflict" - merged with conflict markers written into the file
"kept"     - could not be merged; the checkout's copy is unchanged (see Reason)
"forked"   - the conflict-fork strategy recorded every version for later
"added"    - new in the merged-in version
"deleted"  - deleted in the merged-in version, unchanged here
"mode"     - only the merged-in version changed its executable bit; taken
```

```go
type CheckoutMergeFile struct {
    Name     string
    Action   string
    Strategy string // the strategy that merged it, when one ran
    Reason   string // why the file was kept, for "kept"
}
```

<a name="CheckoutMergeOpts"></a>
## type [CheckoutMergeOpts](<https://github.com/danmestas/go-libfossil/blob/main/checkout.go#L100-L104>)

CheckoutMergeOpts configures Checkout.Merge.

```go
type CheckoutMergeOpts struct {
    Version  int64  // rid of the checkin to merge in; required
    Strategy string // strategy for every file; "" picks one per file
    DryRun   bool   // report what the merge would do, changing nothing
}
```

<a name="CheckoutMergeResult"></a>
## type [CheckoutMergeResult](<https://github.com/danmestas/go-libfossil/blob/main/checkout.go#L107-L110>)

CheckoutMergeResult reports a merge.

```go
type CheckoutMergeResult struct {
    Ancestor int64               // the common ancestor the merge diffed against
    Files    []CheckoutMergeFile // sorted by name; empty when there was nothing to merge
}
```

<a name="CheckoutObserver"></a>
## type [CheckoutObserver](<https://github.com/danmestas/go-libfossil/blob/main/observer.go#L24-L33>)

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)
}
```

<a name="NopCheckoutObserver"></a>
### func [NopCheckoutObserver](<https://github.com/danmestas/go-libfossil/blob/main/observer.go#L146>)

```go
func NopCheckoutObserver() CheckoutObserver
```

NopCheckoutObserver returns a CheckoutObserver that silently discards all events.

<a name="StdoutCheckoutObserver"></a>
### func [StdoutCheckoutObserver](<https://github.com/danmestas/go-libfossil/blob/main/observer.go#L224>)

```go
func StdoutCheckoutObserver() CheckoutObserver
```

StdoutCheckoutObserver returns a CheckoutObserver that logs events to stderr.

<a name="CheckoutOpenOpts"></a>
## type [CheckoutOpenOpts](<https://github.com/danmestas/go-libfossil/blob/main/checkout.go#L27-L31>)

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
}
```

<a name="CheckpointMode"></a>
## type [CheckpointMode](<https://github.com/danmestas/go-libfossil/blob/main/repo.go#L15>)

CheckpointMode mirrors SQLite's PRAGMA wal\_checkpoint\(\<mode\>\) argument.

```go
type CheckpointMode = db.CheckpointMode
```

<a name="CloneOpts"></a>
## type [CloneOpts](<https://github.com/danmestas/go-libfossil/blob/main/repo_sync.go#L61-L73>)

CloneOpts configures a clone operation.

```go
type CloneOpts struct {
    User     string
    Password string
    Observer SyncObserver
    Buggify  BuggifyChecker // fault injection for DST (nil = no faults)
    // PullPhantoms, when set, makes Clone fetch the artifacts the clone
    // rounds left missing with a follow-up pull session, and fail with an
    // error if any are still missing after it. That pull departs from
    // Section 8.2 of the sync draft, which sends no clone, pull or push card
    // after clone_seqno 0, so it is off by default: like fossil(1)'s clone,
    // Clone then succeeds with those artifacts left as phantoms.
    PullPhantoms bool
}
```

<a name="CloneResult"></a>
## type [CloneResult](<https://github.com/danmestas/go-libfossil/blob/main/fossil.go#L75-L82>)

CloneResult reports what happened during a clone.

```go
type CloneResult struct {
    Rounds          int
    BlobsRecvd      int
    ArtifactsLinked int
    ProjectCode     string
    ServerCode      string
    Messages        []string
}
```

<a name="CommitEnd"></a>
## type [CommitEnd](<https://github.com/danmestas/go-libfossil/blob/main/observer.go#L112-L115>)

CommitEnd describes the completion of a commit operation.

```go
type CommitEnd struct {
    UUID string
    RID  int64
}
```

<a name="CommitOpts"></a>
## type [CommitOpts](<https://github.com/danmestas/go-libfossil/blob/main/repo_checkout.go#L13-L40>)

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
}
```

<a name="CommitStart"></a>
## type [CommitStart](<https://github.com/danmestas/go-libfossil/blob/main/observer.go#L105-L109>)

CommitStart describes the beginning of a commit operation.

```go
type CommitStart struct {
    Comment string
    User    string
    Files   int
}
```

<a name="CreateOpts"></a>
## type [CreateOpts](<https://github.com/danmestas/go-libfossil/blob/main/fossil.go#L14-L26>)

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
}
```

<a name="Cursor"></a>
## type [Cursor](<https://github.com/danmestas/go-libfossil/blob/main/types.go#L51>)

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
```

<a name="DiffEntry"></a>
## type [DiffEntry](<https://github.com/danmestas/go-libfossil/blob/main/repo_history.go#L87-L90>)

DiffEntry describes a unified diff for a single file.

```go
type DiffEntry struct {
    Name    string
    Unified string
}
```

<a name="EventKind"></a>
## type [EventKind](<https://github.com/danmestas/go-libfossil/blob/main/types.go#L19>)

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
```

<a name="EventKindCheckin"></a>

```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
)
```

<a name="ExtractEnd"></a>
## type [ExtractEnd](<https://github.com/danmestas/go-libfossil/blob/main/observer.go#L86-L88>)

ExtractEnd describes the completion of a checkout extraction.

```go
type ExtractEnd struct {
    FilesWritten int
}
```

<a name="ExtractOpts"></a>
## type [ExtractOpts](<https://github.com/danmestas/go-libfossil/blob/main/checkout.go#L34-L36>)

ExtractOpts configures file extraction from a checkin.

```go
type ExtractOpts struct {
    Force bool // overwrite uncommitted changes
}
```

<a name="ExtractStart"></a>
## type [ExtractStart](<https://github.com/danmestas/go-libfossil/blob/main/observer.go#L80-L83>)

ExtractStart describes the beginning of a checkout extraction.

```go
type ExtractStart struct {
    RID int64
    Dir string
}
```

<a name="FileEntry"></a>
## type [FileEntry](<https://github.com/danmestas/go-libfossil/blob/main/repo_checkout.go#L56-L60>)

FileEntry describes a file in a manifest.

```go
type FileEntry struct {
    Name string
    UUID string
    Perm string
}
```

<a name="FileToCommit"></a>
## type [FileToCommit](<https://github.com/danmestas/go-libfossil/blob/main/repo_checkout.go#L43-L47>)

FileToCommit describes a file to include in a commit.

```go
type FileToCommit struct {
    Name    string
    Content []byte
    Perm    string
}
```

<a name="Fork"></a>
## type [Fork](<https://github.com/danmestas/go-libfossil/blob/main/repo_merge.go#L30-L34>)

Fork describes a divergence point between two branches.

```go
type Fork struct {
    Ancestor  int64
    LocalTip  int64
    RemoteTip int64
}
```

<a name="FramedTransport"></a>
## type [FramedTransport](<https://github.com/danmestas/go-libfossil/blob/main/transport.go#L36-L42>)

FramedTransport is an optional interface a Transport may also implement when it can report the framing signal — such as an HTTP Content\-Type header — that accompanied a reply. Sync uses that signal to select the reply's §4 framing instead of assuming the §4.1 compressed container, which matters when the peer is a different Fossil\-protocol implementation that legitimately replies with the uncompressed plain\-card framing \(e.g. a real Fossil server's clone reply\).

It is optional in the same way http.Flusher is optional on an http.ResponseWriter: a Transport whose framing is fixed by convention \(both ends always emit the compressed container\) need not implement it, and sync falls back to assuming the compressed framing for such a Transport. Callers type\-assert a Transport to FramedTransport and use RoundTripFramed when it is available. Reporting the signal as a return value keeps it per\-call, with no shared mutable state to make a reused Transport unsafe across concurrent calls.

```go
type FramedTransport interface {
    Transport
    // RoundTripFramed behaves like RoundTrip but also returns the framing
    // signal (e.g. the reply's Content-Type) the wire carried for this reply,
    // or "" when the transport observed none.
    RoundTripFramed(ctx context.Context, payload []byte) (resp []byte, contentType string, err error)
}
```

<a name="FslError"></a>
## type [FslError](<https://github.com/danmestas/go-libfossil/blob/main/errors.go#L61-L65>)



```go
type FslError struct {
    Code  RC
    Msg   string
    Cause error
}
```

<a name="FslError.Error"></a>
### func \(\*FslError\) [Error](<https://github.com/danmestas/go-libfossil/blob/main/errors.go#L67>)

```go
func (e *FslError) Error() string
```



<a name="FslError.Unwrap"></a>
### func \(\*FslError\) [Unwrap](<https://github.com/danmestas/go-libfossil/blob/main/errors.go#L71>)

```go
func (e *FslError) Unwrap() error
```



<a name="FslID"></a>
## type [FslID](<https://github.com/danmestas/go-libfossil/blob/main/types.go#L6>)

FslID is a row\-id in the blob table \(content\-addressed artifacts\).

```go
type FslID = fsltype.FslID
```

<a name="FslSize"></a>
## type [FslSize](<https://github.com/danmestas/go-libfossil/blob/main/types.go#L9>)

FslSize represents a blob size; negative values indicate phantom blobs.

```go
type FslSize = fsltype.FslSize
```

<a name="HTTPOption"></a>
## type [HTTPOption](<https://github.com/danmestas/go-libfossil/blob/main/transport.go#L54>)

HTTPOption configures an HTTP transport.

```go
type HTTPOption func(*httpTransport)
```

<a name="WithHTTPClient"></a>
### func [WithHTTPClient](<https://github.com/danmestas/go-libfossil/blob/main/transport.go#L57>)

```go
func WithHTTPClient(c *http.Client) HTTPOption
```

WithHTTPClient sets a custom http.Client for the transport.

<a name="HandleEnd"></a>
## type [HandleEnd](<https://github.com/danmestas/go-libfossil/blob/main/observer.go#L64-L66>)

HandleEnd describes the completion of a server\-side sync handle.

```go
type HandleEnd struct {
    FilesSent, FilesRecvd int
}
```

<a name="HandleOpts"></a>
## type [HandleOpts](<https://github.com/danmestas/go-libfossil/blob/main/repo_sync.go#L47-L58>)

HandleOpts configures server\-side sync handling.

```go
type HandleOpts struct {
    Observer SyncObserver
    Buggify  BuggifyChecker
    // LoginCookie is the value of the request's x-f-l-c cookie, which
    // carries the login card once the client has seen a server-version
    // that reads it (§6.5). This server announces such a release, so fossil
    // and go-libfossil clients move their login there after the first
    // round: an embedder that serves HandleSyncWithOpts over HTTP must pass
    // the cookie through, or those rounds arrive as nobody. XferHandler and
    // ServeHTTP read it themselves.
    LoginCookie string
}
```

<a name="HandleStart"></a>
## type [HandleStart](<https://github.com/danmestas/go-libfossil/blob/main/observer.go#L59-L61>)

HandleStart describes the beginning of a server\-side sync handle.

```go
type HandleStart struct {
    RemoteAddr string
}
```

<a name="LogEntry"></a>
## type [LogEntry](<https://github.com/danmestas/go-libfossil/blob/main/repo_history.go#L61-L69>)

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
}
```

<a name="LogOpts"></a>
## type [LogOpts](<https://github.com/danmestas/go-libfossil/blob/main/repo_history.go#L27-L30>)

LogOpts configures an Ancestry query: a first\-parent walk starting from a specific check\-in.

```go
type LogOpts struct {
    Start int64
    Limit int
}
```

<a name="MergeConflict"></a>
## type [MergeConflict](<https://github.com/danmestas/go-libfossil/blob/main/repo_merge.go#L23-L27>)

MergeConflict describes a conflict region in a file.

```go
type MergeConflict struct {
    Name      string
    StartLine int
    EndLine   int
}
```

<a name="MergeConflictError"></a>
## type [MergeConflictError](<https://github.com/danmestas/go-libfossil/blob/main/repo_merge.go#L43-L45>)

MergeConflictError reports which files had unresolved merge conflicts. Files is sorted alphabetically for deterministic output.

```go
type MergeConflictError struct {
    Files []string
}
```

<a name="MergeConflictError.Error"></a>
### func \(\*MergeConflictError\) [Error](<https://github.com/danmestas/go-libfossil/blob/main/repo_merge.go#L47>)

```go
func (e *MergeConflictError) Error() string
```



<a name="MergeConflictError.Is"></a>
### func \(\*MergeConflictError\) [Is](<https://github.com/danmestas/go-libfossil/blob/main/repo_merge.go#L51>)

```go
func (e *MergeConflictError) Is(target error) bool
```



<a name="MergeResult"></a>
## type [MergeResult](<https://github.com/danmestas/go-libfossil/blob/main/repo_merge.go#L17-L20>)

MergeResult describes the outcome of a merge.

```go
type MergeResult struct {
    Clean     bool
    Conflicts []MergeConflict
}
```

<a name="MockTransport"></a>
## type [MockTransport](<https://github.com/danmestas/go-libfossil/blob/main/transport.go#L124-L126>)

MockTransport is a test double that delegates to a handler function.

```go
type MockTransport struct {
    Handler func(req []byte) []byte
}
```

<a name="MockTransport.RoundTrip"></a>
### func \(\*MockTransport\) [RoundTrip](<https://github.com/danmestas/go-libfossil/blob/main/transport.go#L129>)

```go
func (t *MockTransport) RoundTrip(_ context.Context, payload []byte) ([]byte, error)
```

RoundTrip calls the Handler function if set, otherwise returns empty bytes.

<a name="PullOpts"></a>
## type [PullOpts](<https://github.com/danmestas/go-libfossil/blob/main/repo_pull.go#L11-L22>)

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
}
```

<a name="RC"></a>
## type [RC](<https://github.com/danmestas/go-libfossil/blob/main/errors.go#L8>)



```go
type RC int
```

<a name="RCOK"></a>

```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
)
```

<a name="RC.String"></a>
### func \(RC\) [String](<https://github.com/danmestas/go-libfossil/blob/main/errors.go#L54>)

```go
func (rc RC) String() string
```



<a name="Repo"></a>
## type [Repo](<https://github.com/danmestas/go-libfossil/blob/main/repo.go#L9-L12>)

Repo is an opaque handle to a Fossil repository.

```go
type Repo struct {
    // contains filtered or unexported fields
}
```

<a name="Create"></a>
### func [Create](<https://github.com/danmestas/go-libfossil/blob/main/fossil.go#L29>)

```go
func Create(path string, opts CreateOpts) (*Repo, error)
```

Create creates a new Fossil repository at the given path.

<a name="Open"></a>
### func [Open](<https://github.com/danmestas/go-libfossil/blob/main/fossil.go#L66>)

```go
func Open(path string) (*Repo, error)
```

Open opens an existing Fossil repository.

<a name="Repo.Ancestry"></a>
### func \(\*Repo\) [Ancestry](<https://github.com/danmestas/go-libfossil/blob/main/repo_checkout.go#L128>)

```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.

<a name="Repo.Annotate"></a>
### func \(\*Repo\) [Annotate](<https://github.com/danmestas/go-libfossil/blob/main/repo_history.go#L112>)

```go
func (r *Repo) Annotate(opts AnnotateOpts) ([]AnnotatedLine, error)
```

Annotate attributes each line of a file to the commit that last changed it.

<a name="Repo.BranchOpenLeaf"></a>
### func \(\*Repo\) [BranchOpenLeaf](<https://github.com/danmestas/go-libfossil/blob/main/repo_merge.go#L133>)

```go
func (r *Repo) BranchOpenLeaf(name string) (rid int64, open bool, err error)
```

BranchOpenLeaf names one open leaf of the named branch \(repo\-state\-00 Section 9\): a check\-in whose active branch tag is name, that is a leaf and that is not closed. When the branch has several, the one with the greatest event.mtime is returned, as the draft requires of any report that names a single open leaf. open is false, with a nil error, when the branch has no open leaf: it is not open. An empty name is an error, as in BranchTip; the main branch is named by CurrentTrunk and MainBranch.

Unlike BranchTip, which returns the branch's newest check\-in whether or not it is a leaf or closed, this is fossil's \`branch info\` answer. fossil's query \(branch\_is\_open, src/branch.c\) takes whichever open leaf it meets first; this follows the draft's greatest\-mtime rule.

<a name="Repo.BranchTip"></a>
### func \(\*Repo\) [BranchTip](<https://github.com/danmestas/go-libfossil/blob/main/repo_merge.go#L99>)

```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.

<a name="Repo.Checkpoint"></a>
### func \(\*Repo\) [Checkpoint](<https://github.com/danmestas/go-libfossil/blob/main/repo.go#L47>)

```go
func (r *Repo) Checkpoint(mode CheckpointMode) error
```

Checkpoint runs PRAGMA wal\_checkpoint\(\<mode\>\) 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.

<a name="Repo.Close"></a>
### func \(\*Repo\) [Close](<https://github.com/danmestas/go-libfossil/blob/main/repo.go#L35>)

```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.

<a name="Repo.Commit"></a>
### func \(\*Repo\) [Commit](<https://github.com/danmestas/go-libfossil/blob/main/repo_checkout.go#L73>)

```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\).

<a name="Repo.Config"></a>
### func \(\*Repo\) [Config](<https://github.com/danmestas/go-libfossil/blob/main/repo_admin.go#L73>)

```go
func (r *Repo) Config(key string) (string, error)
```

Config reads a configuration value from the repo's config table.

<a name="Repo.CreateCheckout"></a>
### func \(\*Repo\) [CreateCheckout](<https://github.com/danmestas/go-libfossil/blob/main/checkout.go#L138>)

```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.

<a name="Repo.CreateUser"></a>
### func \(\*Repo\) [CreateUser](<https://github.com/danmestas/go-libfossil/blob/main/repo_admin.go#L23>)

```go
func (r *Repo) CreateUser(opts UserOpts) error
```

CreateUser creates a new user in the repository.

<a name="Repo.CurrentTrunk"></a>
### func \(\*Repo\) [CurrentTrunk](<https://github.com/danmestas/go-libfossil/blob/main/repo_history.go#L296>)

```go
func (r *Repo) CurrentTrunk() (int64, error)
```

CurrentTrunk returns the current trunk \(repo\-state\-00 Section 9\): the check\-in that the main\-branch setting's name resolves to by ResolveVersion's procedure, "trunk" when the setting is unset. Only check\-ins can answer, as in fossil's check\-in request, so a technote tagged with the name does not. The setting is local and not synced, so two repositories holding the same artifacts can name different trunks. fossil resolves it the same way where it needs one: update outside a checkout \(src/update.c, a "ci" request\) and open with no version \(src/db.c\). A name that resolves to nothing returns ErrVersionNotFound \(wrapped\).

<a name="Repo.DB"></a>
### func \(\*Repo\) [DB](<https://github.com/danmestas/go-libfossil/blob/main/repo.go#L56>)

```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.

<a name="Repo.DeleteUser"></a>
### func \(\*Repo\) [DeleteUser](<https://github.com/danmestas/go-libfossil/blob/main/repo_admin.go#L54>)

```go
func (r *Repo) DeleteUser(login string) error
```

DeleteUser removes a user from the repository.

<a name="Repo.DetectForks"></a>
### func \(\*Repo\) [DetectForks](<https://github.com/danmestas/go-libfossil/blob/main/repo_merge.go#L65>)

```go
func (r *Repo) DetectForks() ([]Fork, error)
```

DetectForks finds divergent branches in the repository.

<a name="Repo.Diff"></a>
### func \(\*Repo\) [Diff](<https://github.com/danmestas/go-libfossil/blob/main/repo_history.go#L151>)

```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.

<a name="Repo.DisableSubmanifests"></a>
### func \(\*Repo\) [DisableSubmanifests](<https://github.com/danmestas/go-libfossil/blob/main/repo_submanifest.go#L60>)

```go
func (r *Repo) DisableSubmanifests() error
```

DisableSubmanifests turns tree manifest emission off: later commits are flat, and the pinned k is kept for a later EnableSubmanifests. Existing trees remain \-\- artifact names are immutable, so they cannot be retired \-\- and keep being served, though peers that do not announce sub\-manifest support are still refused them. Unlike the CLI's disable, it returns no note saying so; an embedder that wants to tell its operator must do it itself.

<a name="Repo.EnableSubmanifests"></a>
### func \(\*Repo\) [EnableSubmanifests](<https://github.com/danmestas/go-libfossil/blob/main/repo_submanifest.go#L26>)

```go
func (r *Repo) EnableSubmanifests(k int) (pinned int, warning string, err error)
```

EnableSubmanifests turns on tree manifest emission \(draft\-fossil\-submanifests\-00 §8.1\): from the next commit, check\-ins carry their file sets as sub\-manifest trees. k is the partition parameter, 1 to 12, or 0 to select one. A valid pinned k is kept, and an explicit k that differs from it is refused: changing it is RetuneSubmanifests. A stored k outside 1..12 is no valid pin: an explicit k replaces it, and k = 0 is refused, naming the stored value. With no stored k, an explicit k is pinned, or one is selected as zit selects it: the §6.3 cost over one check\-in's file set, refined by replaying recent history. The check\-in analyzed is the current trunk \(CurrentTrunk, the main\-branch tip, which the next commit most plausibly descends from\); when no check\-in is on the main branch, it is the newest check\-in by time, the highest rid breaking a tie. A request that cannot be met \-\- k outside 1..12, no check\-in at all to select from, or a file set no k partitions \-\- changes neither setting. It returns the pinned k and the warning the operator must be shown: peers that do not announce sub\-manifest support, every fossil among them, are refused trees, and trees cannot be retired.

<a name="Repo.FindCommonAncestor"></a>
### func \(\*Repo\) [FindCommonAncestor](<https://github.com/danmestas/go-libfossil/blob/main/repo_merge.go#L56>)

```go
func (r *Repo) FindCommonAncestor(ridA, ridB int64) (int64, error)
```

FindCommonAncestor finds the nearest common ancestor of two checkins.

<a name="Repo.GetUser"></a>
### func \(\*Repo\) [GetUser](<https://github.com/danmestas/go-libfossil/blob/main/repo_admin.go#L32>)

```go
func (r *Repo) GetUser(login string) (User, error)
```

GetUser returns information about a user.

<a name="Repo.HandleSync"></a>
### func \(\*Repo\) [HandleSync](<https://github.com/danmestas/go-libfossil/blob/main/repo_sync.go#L249>)

```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.

<a name="Repo.HandleSyncWithOpts"></a>
### func \(\*Repo\) [HandleSyncWithOpts](<https://github.com/danmestas/go-libfossil/blob/main/repo_sync.go#L254>)

```go
func (r *Repo) HandleSyncWithOpts(ctx context.Context, payload []byte, opts HandleOpts) ([]byte, error)
```

HandleSyncWithOpts processes an incoming xfer request with optional configuration.

<a name="Repo.Inner"></a>
### func \(\*Repo\) [Inner](<https://github.com/danmestas/go-libfossil/blob/main/repo.go#L30>)

```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.

<a name="Repo.ListConflictForks"></a>
### func \(\*Repo\) [ListConflictForks](<https://github.com/danmestas/go-libfossil/blob/main/repo_merge.go#L82>)

```go
func (r *Repo) ListConflictForks() ([]string, error)
```

ListConflictForks returns filenames with unresolved conflict\-fork entries.

<a name="Repo.ListFiles"></a>
### func \(\*Repo\) [ListFiles](<https://github.com/danmestas/go-libfossil/blob/main/repo_checkout.go#L194>)

```go
func (r *Repo) ListFiles(rid int64) ([]FileEntry, error)
```

ListFiles returns the files in a manifest identified by blob row\-id.

<a name="Repo.ListUsers"></a>
### func \(\*Repo\) [ListUsers](<https://github.com/danmestas/go-libfossil/blob/main/repo_admin.go#L41>)

```go
func (r *Repo) ListUsers() ([]User, error)
```

ListUsers returns all users in the repository.

<a name="Repo.Merge"></a>
### func \(\*Repo\) [Merge](<https://github.com/danmestas/go-libfossil/blob/main/repo_merge.go#L157>)

```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.

<a name="Repo.OpenCheckout"></a>
### func \(\*Repo\) [OpenCheckout](<https://github.com/danmestas/go-libfossil/blob/main/checkout.go#L150>)

```go
func (r *Repo) OpenCheckout(dir string, opts CheckoutOpenOpts) (*Checkout, error)
```

OpenCheckout opens an existing checkout directory linked to this repository.

<a name="Repo.Path"></a>
### func \(\*Repo\) [Path](<https://github.com/danmestas/go-libfossil/blob/main/repo.go#L25>)

```go
func (r *Repo) Path() string
```

Path returns the filesystem path to the repository file.

<a name="Repo.Pull"></a>
### func \(\*Repo\) [Pull](<https://github.com/danmestas/go-libfossil/blob/main/repo_pull.go#L30>)

```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\).

<a name="Repo.ReadFile"></a>
### func \(\*Repo\) [ReadFile](<https://github.com/danmestas/go-libfossil/blob/main/repo_history.go#L243>)

```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\).

<a name="Repo.ReadFileAt"></a>
### func \(\*Repo\) [ReadFileAt](<https://github.com/danmestas/go-libfossil/blob/main/repo_history.go#L827>)

```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.

<a name="Repo.Redo"></a>
### func \(\*Repo\) [Redo](<https://github.com/danmestas/go-libfossil/blob/main/repo_extras.go#L132>)

```go
func (r *Repo) Redo(dir string) error
```

Redo re\-applies the last undone operation. Requires a checkout database; not yet wired.

<a name="Repo.ResolveBranchStart"></a>
### func \(\*Repo\) [ResolveBranchStart](<https://github.com/danmestas/go-libfossil/blob/main/repo_history.go#L320>)

```go
func (r *Repo) ResolveBranchStart(name string) (int64, error)
```

ResolveBranchStart resolves name as ResolveVersion does, then returns the first check\-in of the branch the result is on: fossil's branch\-type \("br"\) request \(repo\-state\-00 Section 8.3\), the start of the branch rather than the check\-in its name most recently points at. As Section 8.3 requires, the request is rewritten to a check\-in request first: only check\-ins can match, so a technote tagged with the branch name does not shadow the branch.

Section 8.3 walks back from the result of every form. fossil\(1\) walks only from a "tag:NAME" or plain\-name result \(symbolic\_name\_to\_rid, src/name.c\), so there a hash, "tip" or a date names the check\-in itself; this follows the draft.

<a name="Repo.ResolveConflictFork"></a>
### func \(\*Repo\) [ResolveConflictFork](<https://github.com/danmestas/go-libfossil/blob/main/repo_merge.go#L91>)

```go
func (r *Repo) ResolveConflictFork(filename string) error
```

ResolveConflictFork marks a conflict\-fork entry as resolved.

<a name="Repo.ResolveVersion"></a>
### func \(\*Repo\) [ResolveVersion](<https://github.com/danmestas/go-libfossil/blob/main/repo_history.go#L283>)

```go
func (r *Repo) ResolveVersion(name string) (int64, error)
```

ResolveVersion resolves a symbolic version name to a repository artifact RID.

It follows fossil's symbolic\_name\_to\_rid \(src/name.c\) for the forms go\-libfossil supports, in fossil's order:

1. "tip" — newest check\-in by event.mtime. "" is treated as "tip".
2. "rid:N" — the literal RID N, when that artifact exists.
3. "tag:NAME" — the check\-in carrying sym\-NAME with the greatest event.mtime \(forces a tag lookup even for a hex NAME\).
4. "root:BR" / "start:BR" / "merge\-in:BR" — the origin, first check\-in, or most recent merge\-in of branch BR \(BR itself resolved recursively\).
5. "NAME:TIMESTAMP" — the check\-in carrying sym\-NAME with the greatest event.mtime at or before TIMESTAMP \(UTC\).
6. Artifact hash or 4–64 char hex prefix — unique match against blob.uuid, tried before a plain tag; more than one match is ambiguous.
7. Plain symbolic name — the check\-in carrying sym\-NAME with the greatest event.mtime \(resolves "trunk" and branch names\).
8. Trailing\-punctuation retry — a name pasted from prose that ends in one or two punctuation characters is retried without them.

No match returns ErrVersionNotFound \(wrapped\); a hex prefix matching more than one artifact returns ErrAmbiguousVersion \(wrapped\).

The names relative to an open checkout \("current", "prev", "next"\) are ordinary names here, as in fossil outside a checkout; Checkout's ResolveVersion resolves them.

<a name="Repo.RetuneSubmanifests"></a>
### func \(\*Repo\) [RetuneSubmanifests](<https://github.com/danmestas/go-libfossil/blob/main/repo_submanifest.go#L47>)

```go
func (r *Repo) RetuneSubmanifests(k int) error
```

RetuneSubmanifests pins a new partition parameter k, 1 to 12, for the commits that follow \(draft\-fossil\-submanifests\-00 §6.4\). It is forward only: existing check\-ins are unchanged, and the next tree shares only the sub\-manifests whose bytes are the same under both values.

<a name="Repo.ServeHTTP"></a>
### func \(\*Repo\) [ServeHTTP](<https://github.com/danmestas/go-libfossil/blob/main/repo_sync.go#L288>)

```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.

Requests are authorized against the user table: one without a login card gets nobody's capabilities, which in a new repository allow clone and pull but not push. Grant more with SetCaps.

<a name="Repo.SetCaps"></a>
### func \(\*Repo\) [SetCaps](<https://github.com/danmestas/go-libfossil/blob/main/repo_admin.go#L68>)

```go
func (r *Repo) SetCaps(login, caps string) error
```

SetCaps updates a user's capability string.

<a name="Repo.SetConfig"></a>
### func \(\*Repo\) [SetConfig](<https://github.com/danmestas/go-libfossil/blob/main/repo_admin.go#L82>)

```go
func (r *Repo) SetConfig(key, value string) error
```

SetConfig writes a configuration value to the repo's config table.

<a name="Repo.SetHashPolicy"></a>
### func \(\*Repo\) [SetHashPolicy](<https://github.com/danmestas/go-libfossil/blob/main/repo_admin.go#L94>)

```go
func (r *Repo) SetHashPolicy(name string) error
```

SetHashPolicy sets the repository's hash policy by name, as \`fossil hash\-policy NEW\-POLICY\` does. name must be exactly one of sha1, auto, sha3, sha3\-only or shun\-sha1: the match is case\-sensitive, and any other string is an error that leaves the policy unchanged. Asking for auto in a repository that already holds a SHA3\-named artifact sets sha3.

<a name="Repo.SetPassword"></a>
### func \(\*Repo\) [SetPassword](<https://github.com/danmestas/go-libfossil/blob/main/repo_admin.go#L59>)

```go
func (r *Repo) SetPassword(login, password string) error
```

SetPassword updates a user's password.

<a name="Repo.StashApply"></a>
### func \(\*Repo\) [StashApply](<https://github.com/danmestas/go-libfossil/blob/main/repo_extras.go#L105>)

```go
func (r *Repo) StashApply(dir string, id int64) error
```

StashApply restores a stash entry by ID without removing it.

<a name="Repo.StashClear"></a>
### func \(\*Repo\) [StashClear](<https://github.com/danmestas/go-libfossil/blob/main/repo_extras.go#L120>)

```go
func (r *Repo) StashClear() error
```

StashClear removes all stash entries.

<a name="Repo.StashDrop"></a>
### func \(\*Repo\) [StashDrop](<https://github.com/danmestas/go-libfossil/blob/main/repo_extras.go#L115>)

```go
func (r *Repo) StashDrop(id int64) error
```

StashDrop removes a stash entry by ID.

<a name="Repo.StashList"></a>
### func \(\*Repo\) [StashList](<https://github.com/danmestas/go-libfossil/blob/main/repo_extras.go#L110>)

```go
func (r *Repo) StashList() ([]StashEntry, error)
```

StashList returns all stash entries.

<a name="Repo.StashPop"></a>
### func \(\*Repo\) [StashPop](<https://github.com/danmestas/go-libfossil/blob/main/repo_extras.go#L100>)

```go
func (r *Repo) StashPop(dir string) error
```

StashPop restores the most recent stash entry and removes it.

<a name="Repo.StashSave"></a>
### func \(\*Repo\) [StashSave](<https://github.com/danmestas/go-libfossil/blob/main/repo_extras.go#L95>)

```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\).

<a name="Repo.Sync"></a>
### func \(\*Repo\) [Sync](<https://github.com/danmestas/go-libfossil/blob/main/repo_sync.go#L205>)

```go
func (r *Repo) Sync(ctx context.Context, t Transport, opts SyncOpts) (*SyncResult, error)
```

Sync runs a sync session against the given transport.

<a name="Repo.Tag"></a>
### func \(\*Repo\) [Tag](<https://github.com/danmestas/go-libfossil/blob/main/repo_extras.go#L53>)

```go
func (r *Repo) Tag(opts TagOpts) (int64, error)
```

Tag creates a control artifact that adds a tag to a target artifact. Returns the UUID of the tag control artifact.

As \`fossil tag add\` does, a name with a reserved prefix \("wiki\-", "tkt\-", "event\-"\) is refused, and when the target is a check\-in the name is placed in the symbolic namespace with a "sym\-" prefix so it resolves as a tag in commands such as update and merge; other artifact types keep the name bare. Pass the raw name: fossil prefixes the raw name, so "x" becomes "sym\-x" and "sym\-x" becomes "sym\-sym\-x" on a check\-in.

<a name="Repo.Timeline"></a>
### func \(\*Repo\) [Timeline](<https://github.com/danmestas/go-libfossil/blob/main/repo_checkout.go#L166>)

```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.

<a name="Repo.UUIDFromRID"></a>
### func \(\*Repo\) [UUIDFromRID](<https://github.com/danmestas/go-libfossil/blob/main/repo_ids.go#L16>)

```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.

<a name="Repo.UVDelete"></a>
### func \(\*Repo\) [UVDelete](<https://github.com/danmestas/go-libfossil/blob/main/repo_extras.go#L149>)

```go
func (r *Repo) UVDelete(name string, mtime time.Time) error
```

UVDelete marks an unversioned file as deleted \(tombstone\).

<a name="Repo.UVList"></a>
### func \(\*Repo\) [UVList](<https://github.com/danmestas/go-libfossil/blob/main/repo_extras.go#L167>)

```go
func (r *Repo) UVList() ([]UVEntry, error)
```

UVList returns all unversioned file entries.

<a name="Repo.UVRead"></a>
### func \(\*Repo\) [UVRead](<https://github.com/danmestas/go-libfossil/blob/main/repo_extras.go#L162>)

```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.

<a name="Repo.UVWrite"></a>
### func \(\*Repo\) [UVWrite](<https://github.com/danmestas/go-libfossil/blob/main/repo_extras.go#L137>)

```go
func (r *Repo) UVWrite(name string, content []byte, mtime time.Time) error
```

UVWrite writes an unversioned file to the repository.

<a name="Repo.Undo"></a>
### func \(\*Repo\) [Undo](<https://github.com/danmestas/go-libfossil/blob/main/repo_extras.go#L126>)

```go
func (r *Repo) Undo(dir string) error
```

Undo reverts the last commit or merge. Requires a checkout database; not yet wired.

<a name="Repo.Verify"></a>
### func \(\*Repo\) [Verify](<https://github.com/danmestas/go-libfossil/blob/main/repo.go#L62>)

```go
func (r *Repo) Verify() error
```

Verify checks repository integrity \(blob checksums, delta chains\).

<a name="Repo.WithTx"></a>
### func \(\*Repo\) [WithTx](<https://github.com/danmestas/go-libfossil/blob/main/repo.go#L59>)

```go
func (r *Repo) WithTx(fn func(tx *db.Tx) error) error
```

WithTx executes fn within a database transaction.

<a name="Repo.XferHandler"></a>
### func \(\*Repo\) [XferHandler](<https://github.com/danmestas/go-libfossil/blob/main/repo_sync.go#L277>)

```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\).

<a name="RevertOpts"></a>
## type [RevertOpts](<https://github.com/danmestas/go-libfossil/blob/main/checkout.go#L75-L77>)

RevertOpts configures reverting file changes.

```go
type RevertOpts struct {
    Files []string // empty = revert all
}
```

<a name="RoundStats"></a>
## type [RoundStats](<https://github.com/danmestas/go-libfossil/blob/main/observer.go#L54-L56>)

RoundStats describes the outcome of a single sync round.

```go
type RoundStats struct {
    FilesSent, FilesRecvd, BytesSent, BytesRecvd, Gimmes, IGots int
}
```

<a name="ScanEnd"></a>
## type [ScanEnd](<https://github.com/danmestas/go-libfossil/blob/main/observer.go#L100-L102>)

ScanEnd describes the completion of a working\-tree scan.

```go
type ScanEnd struct {
    FilesScanned int
}
```

<a name="SessionEnd"></a>
## type [SessionEnd](<https://github.com/danmestas/go-libfossil/blob/main/observer.go#L49-L51>)

SessionEnd describes the completion of a sync session.

```go
type SessionEnd struct {
    Rounds, FilesSent, FilesRecvd int
}
```

<a name="SessionStart"></a>
## type [SessionStart](<https://github.com/danmestas/go-libfossil/blob/main/observer.go#L43-L46>)

SessionStart describes the beginning of a sync session.

```go
type SessionStart struct {
    ProjectCode    string
    Push, Pull, UV bool
}
```

<a name="StashEntry"></a>
## type [StashEntry](<https://github.com/danmestas/go-libfossil/blob/main/repo_extras.go#L21-L25>)

StashEntry describes a saved stash.

```go
type StashEntry struct {
    ID      int64
    Comment string
    Time    string
}
```

<a name="StatusEntry"></a>
## type [StatusEntry](<https://github.com/danmestas/go-libfossil/blob/main/repo_checkout.go#L63-L66>)

StatusEntry describes a changed file in the working tree.

```go
type StatusEntry struct {
    Name   string
    Change string
}
```

<a name="SyncObserver"></a>
## type [SyncObserver](<https://github.com/danmestas/go-libfossil/blob/main/observer.go#L10-L20>)

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)
}
```

<a name="NopSyncObserver"></a>
### func [NopSyncObserver](<https://github.com/danmestas/go-libfossil/blob/main/observer.go#L132>)

```go
func NopSyncObserver() SyncObserver
```

NopSyncObserver returns a SyncObserver that silently discards all events.

<a name="StdoutSyncObserver"></a>
### func [StdoutSyncObserver](<https://github.com/danmestas/go-libfossil/blob/main/observer.go#L188>)

```go
func StdoutSyncObserver() SyncObserver
```

StdoutSyncObserver returns a SyncObserver that logs events to stderr.

<a name="SyncOpts"></a>
## type [SyncOpts](<https://github.com/danmestas/go-libfossil/blob/main/repo_sync.go#L13-L31>)

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
    // ShareLinks is fossil's --share-links mode (§9.5): a pulling session
    // asks the server for the URLs of other copies of the repository and
    // keeps each valid one as config link:URL. Off by default.
    ShareLinks bool
    Observer   SyncObserver
    Buggify    BuggifyChecker
}
```

<a name="SyncResult"></a>
## type [SyncResult](<https://github.com/danmestas/go-libfossil/blob/main/repo_sync.go#L34-L44>)

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
}
```

<a name="TableSyncEnd"></a>
## type [TableSyncEnd](<https://github.com/danmestas/go-libfossil/blob/main/observer.go#L74-L77>)

TableSyncEnd describes the completion of a config table sync.

```go
type TableSyncEnd struct {
    Table               string
    RowsSent, RowsRecvd int
}
```

<a name="TableSyncStart"></a>
## type [TableSyncStart](<https://github.com/danmestas/go-libfossil/blob/main/observer.go#L69-L71>)

TableSyncStart describes the beginning of a config table sync.

```go
type TableSyncStart struct {
    Table string
}
```

<a name="TagOpts"></a>
## type [TagOpts](<https://github.com/danmestas/go-libfossil/blob/main/repo_extras.go#L28-L34>)

TagOpts configures a tag operation.

```go
type TagOpts struct {
    Name     string
    TargetID int64
    Value    string
    User     string
    Time     time.Time
}
```

<a name="TagSpec"></a>
## type [TagSpec](<https://github.com/danmestas/go-libfossil/blob/main/repo_checkout.go#L50-L53>)

TagSpec describes a tag to attach to an artifact.

```go
type TagSpec struct {
    Name  string
    Value string
}
```

<a name="TimelineEntry"></a>
## type [TimelineEntry](<https://github.com/danmestas/go-libfossil/blob/main/repo_history.go#L81-L84>)

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
}
```

<a name="TimelineOpts"></a>
## type [TimelineOpts](<https://github.com/danmestas/go-libfossil/blob/main/repo_history.go#L34-L48>)

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
}
```

<a name="Transport"></a>
## type [Transport](<https://github.com/danmestas/go-libfossil/blob/main/transport.go#L16-L18>)

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)
}
```

<a name="NewHTTPTransport"></a>
### func [NewHTTPTransport](<https://github.com/danmestas/go-libfossil/blob/main/transport.go#L45>)

```go
func NewHTTPTransport(url string, opts ...HTTPOption) Transport
```

NewHTTPTransport creates a Transport that speaks Fossil's HTTP /xfer protocol.

<a name="TransportFunc"></a>
## type [TransportFunc](<https://github.com/danmestas/go-libfossil/blob/main/transport.go#L138>)

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)
```

<a name="TransportFunc.RoundTrip"></a>
### func \(TransportFunc\) [RoundTrip](<https://github.com/danmestas/go-libfossil/blob/main/transport.go#L141>)

```go
func (f TransportFunc) RoundTrip(ctx context.Context, payload []byte) ([]byte, error)
```

RoundTrip calls the function.

<a name="UVEntry"></a>
## type [UVEntry](<https://github.com/danmestas/go-libfossil/blob/main/repo_extras.go#L37-L42>)

UVEntry describes an unversioned file.

```go
type UVEntry struct {
    Name  string
    Size  int64
    Mtime time.Time
    Hash  string
}
```

<a name="UpdateChange"></a>
## type [UpdateChange](<https://github.com/danmestas/go-libfossil/blob/main/observer.go#L91>)

UpdateChange classifies how a file changed.

```go
type UpdateChange string
```

<a name="ChangeAdded"></a>

```go
const (
    ChangeAdded    UpdateChange = "added"
    ChangeModified UpdateChange = "modified"
    ChangeDeleted  UpdateChange = "deleted"
)
```

<a name="UpdateOpts"></a>
## type [UpdateOpts](<https://github.com/danmestas/go-libfossil/blob/main/checkout.go#L39-L44>)

UpdateOpts configures updating to a new version with merge.

```go
type UpdateOpts struct {
    // TargetRID is the check-in to update to. 0 picks it as fossil's update
    // does with no version named: the newest open leaf descended from the
    // checkout on its branch. Update fails when several such leaves remain.
    TargetRID int64
}
```

<a name="UpdateResult"></a>
## type [UpdateResult](<https://github.com/danmestas/go-libfossil/blob/main/checkout.go#L68-L72>)

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
}
```

<a name="User"></a>
## type [User](<https://github.com/danmestas/go-libfossil/blob/main/repo_admin.go#L17-L20>)

User describes a Fossil user.

```go
type User struct {
    Login string
    Caps  string
}
```

<a name="UserOpts"></a>
## type [UserOpts](<https://github.com/danmestas/go-libfossil/blob/main/repo_admin.go#L10-L14>)

UserOpts configures a user creation or update.

```go
type UserOpts struct {
    Login    string
    Password string
    Caps     string
}
```

<a name="WorkingVersion"></a>
## type [WorkingVersion](<https://github.com/danmestas/go-libfossil/blob/main/checkout.go#L535-L542>)

WorkingVersion is the answer of a checkout\-inclusive request: a check\-in, or the checkout's working files.

```go
type WorkingVersion struct {
    // RID is the check-in the name resolves to. When Working is set it is
    // the checkout's version, the check-in the working files started from.
    RID int64
    // Working reports that the name was "ckout": the request asks for the
    // files on disk, edits included, rather than for any stored check-in.
    Working bool
}
```

Generated by [gomarkdoc](<https://github.com/princjef/gomarkdoc>)