Skip to content
go-libfossil Artifact [49f74972b3]
Login

Artifact [49f74972b3]

Check-ins Using Download Hex Wiki

Artifact 49f74972b34617bdb6d02dd0590483ee781961534c784fecc6cc9a1079737a93:

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

# libfossil

```go
import "github.com/danmestas/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\) 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 CheckoutOpts](<#CheckoutOpts>)
- [type CloneOpts](<#CloneOpts>)
- [type CloneResult](<#CloneResult>)
- [type CommitEnd](<#CommitEnd>)
- [type CommitOpts](<#CommitOpts>)
- [type CommitStart](<#CommitStart>)
- [type CreateOpts](<#CreateOpts>)
- [type DiffEntry](<#DiffEntry>)
- [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 MergeOpts](<#MergeOpts>)
- [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\) Annotate\(opts AnnotateOpts\) \(\[\]AnnotatedLine, error\)](<#Repo.Annotate>)
  - [func \(r \*Repo\) BranchTip\(name string\) \(int64, error\)](<#Repo.BranchTip>)
  - [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\) Redo\(dir string\) error](<#Repo.Redo>)
  - [func \(r \*Repo\) ResolveConflictFork\(filename string\) error](<#Repo.ResolveConflictFork>)
  - [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 LogOpts\) \(\[\]LogEntry, error\)](<#Repo.Timeline>)
  - [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 StatusOpts](<#StatusOpts>)
- [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 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 User](<#User>)
- [type UserOpts](<#UserOpts>)


## Constants

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

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

## Variables

<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="Clone"></a>
## 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.

<a name="JulianToTime"></a>
## func JulianToTime

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

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

<a name="TimeToJulian"></a>
## func TimeToJulian

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

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

<a name="AnnotateOpts"></a>
## type AnnotateOpts

AnnotateOpts configures an annotate operation.

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

<a name="AnnotatedLine"></a>
## type AnnotatedLine

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

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

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

<a name="BuggifyChecker"></a>
## type BuggifyChecker

BuggifyChecker controls fault injection for deterministic simulation testing.

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

<a name="Checkout"></a>
## 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
}
```

<a name="Checkout.Add"></a>
### 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.

<a name="Checkout.Checkin"></a>
### 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.

<a name="Checkout.Close"></a>
### func \(\*Checkout\) Close

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

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

<a name="Checkout.Dir"></a>
### func \(\*Checkout\) Dir

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

Dir returns the checkout directory path.

<a name="Checkout.Extract"></a>
### func \(\*Checkout\) Extract

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

Extract writes files from the specified checkin to the working directory.

<a name="Checkout.HasChanges"></a>
### 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.

<a name="Checkout.Remove"></a>
### 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.

<a name="Checkout.Rename"></a>
### func \(\*Checkout\) Rename

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

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

<a name="Checkout.Revert"></a>
### 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.

<a name="Checkout.Status"></a>
### 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.

<a name="Checkout.Update"></a>
### func \(\*Checkout\) Update

```go
func (c *Checkout) Update(opts UpdateOpts) error
```

Update updates the checkout to a new version, performing 3\-way merge where needed to preserve local modifications.

<a name="Checkout.Version"></a>
### func \(\*Checkout\) Version

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

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

<a name="CheckoutChange"></a>
## type CheckoutChange

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

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

<a name="CheckoutCreateOpts"></a>
## type CheckoutCreateOpts

CheckoutCreateOpts configures creating a new checkout.

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

<a name="CheckoutObserver"></a>
## 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)
}
```

<a name="NopCheckoutObserver"></a>
### func NopCheckoutObserver

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

NopCheckoutObserver returns a CheckoutObserver that silently discards all events.

<a name="StdoutCheckoutObserver"></a>
### func StdoutCheckoutObserver

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

StdoutCheckoutObserver returns a CheckoutObserver that logs events to stderr.

<a name="CheckoutOpenOpts"></a>
## 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
}
```

<a name="CheckoutOpts"></a>
## type CheckoutOpts

CheckoutOpts configures a checkout extraction.

```go
type CheckoutOpts struct {
    Dir   string
    Force bool
}
```

<a name="CloneOpts"></a>
## type CloneOpts

CloneOpts configures a clone operation.

```go
type CloneOpts struct {
    User        string
    Password    string
    ProjectCode string
    ServerCode  string
    Observer    SyncObserver
    Buggify     BuggifyChecker // fault injection for DST (nil = no faults)
}
```

<a name="CloneResult"></a>
## 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
}
```

<a name="CommitEnd"></a>
## type CommitEnd

CommitEnd describes the completion of a commit operation.

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

<a name="CommitOpts"></a>
## type CommitOpts

CommitOpts configures a commit operation.

```go
type CommitOpts struct {
    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
}
```

<a name="CommitStart"></a>
## type CommitStart

CommitStart describes the beginning of a commit operation.

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

<a name="CreateOpts"></a>
## type CreateOpts

CreateOpts configures repository creation.

```go
type CreateOpts struct {
    User 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="DiffEntry"></a>
## type DiffEntry

DiffEntry describes a unified diff for a single file.

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

<a name="ExtractEnd"></a>
## type ExtractEnd

ExtractEnd describes the completion of a checkout extraction.

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

<a name="ExtractOpts"></a>
## type ExtractOpts

ExtractOpts configures file extraction from a checkin.

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

<a name="ExtractStart"></a>
## type ExtractStart

ExtractStart describes the beginning of a checkout extraction.

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

<a name="FileEntry"></a>
## type FileEntry

FileEntry describes a file in a manifest.

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

<a name="FileToCommit"></a>
## type FileToCommit

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

Fork describes a divergence point between two branches.

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

<a name="FslError"></a>
## type FslError



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

<a name="FslError.Error"></a>
### func \(\*FslError\) Error

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



<a name="FslError.Unwrap"></a>
### func \(\*FslError\) Unwrap

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



<a name="FslID"></a>
## type FslID

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

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

<a name="FslSize"></a>
## type FslSize

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

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

<a name="HTTPOption"></a>
## type HTTPOption

HTTPOption configures an HTTP transport.

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

<a name="WithHTTPClient"></a>
### func WithHTTPClient

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

WithHTTPClient sets a custom http.Client for the transport.

<a name="HandleEnd"></a>
## type HandleEnd

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

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

<a name="HandleOpts"></a>
## type HandleOpts

HandleOpts configures server\-side sync handling.

```go
type HandleOpts struct {
    Observer SyncObserver
    Buggify  BuggifyChecker
}
```

<a name="HandleStart"></a>
## type HandleStart

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

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

<a name="LogEntry"></a>
## type LogEntry

LogEntry represents a single checkin in the timeline.

```go
type LogEntry struct {
    RID     int64
    UUID    string
    Comment string
    User    string
    Time    time.Time
    Parents []string
}
```

<a name="LogOpts"></a>
## type LogOpts

LogOpts configures a log/timeline query.

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

<a name="MergeConflict"></a>
## type MergeConflict

MergeConflict describes a conflict region in a file.

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

<a name="MergeConflictError"></a>
## type MergeConflictError

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

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



<a name="MergeConflictError.Is"></a>
### func \(\*MergeConflictError\) Is

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



<a name="MergeOpts"></a>
## type MergeOpts

MergeOpts configures a merge operation.

```go
type MergeOpts struct {
    Strategy string
    Dir      string
}
```

<a name="MergeResult"></a>
## type MergeResult

MergeResult describes the outcome of a merge.

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

<a name="MockTransport"></a>
## type MockTransport

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

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

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



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

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



<a name="Repo"></a>
## type Repo

Repo is an opaque handle to a Fossil repository.

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

<a name="Create"></a>
### func Create

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

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

Open opens an existing Fossil repository.

<a name="Repo.Annotate"></a>
### 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.

<a name="Repo.BranchTip"></a>
### 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.

<a name="Repo.Close"></a>
### func \(\*Repo\) Close

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

Close closes the repository and releases resources.

<a name="Repo.Commit"></a>
### 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.

<a name="Repo.Config"></a>
### func \(\*Repo\) Config

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

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

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

CreateUser creates a new user in the repository.

<a name="Repo.DB"></a>
### 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.

<a name="Repo.DeleteUser"></a>
### func \(\*Repo\) DeleteUser

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

DeleteUser removes a user from the repository.

<a name="Repo.DetectForks"></a>
### func \(\*Repo\) DetectForks

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

DetectForks finds divergent branches in the repository.

<a name="Repo.Diff"></a>
### func \(\*Repo\) Diff

```go
func (r *Repo) Diff(ridA, ridB int64, filePath string) ([]DiffEntry, error)
```

Diff returns a unified diff for filePath between two checkins. When the file is absent from a side, that side is treated as empty bytes, so additions and deletions render as pure insert/delete hunks. Returns an empty slice when both sides are byte\-identical.

<a name="Repo.FindCommonAncestor"></a>
### func \(\*Repo\) FindCommonAncestor

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

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

GetUser returns information about a user.

<a name="Repo.HandleSync"></a>
### 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.

<a name="Repo.HandleSyncWithOpts"></a>
### 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.

<a name="Repo.Inner"></a>
### 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.

<a name="Repo.ListConflictForks"></a>
### func \(\*Repo\) ListConflictForks

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

ListConflictForks returns filenames with unresolved conflict\-fork entries.

<a name="Repo.ListFiles"></a>
### func \(\*Repo\) ListFiles

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

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

ListUsers returns all users in the repository.

<a name="Repo.Merge"></a>
### 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.

<a name="Repo.OpenCheckout"></a>
### func \(\*Repo\) OpenCheckout

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

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

Path returns the filesystem path to the repository file.

<a name="Repo.Pull"></a>
### 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\).

<a name="Repo.ReadFile"></a>
### 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\).

<a name="Repo.Redo"></a>
### 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.

<a name="Repo.ResolveConflictFork"></a>
### func \(\*Repo\) ResolveConflictFork

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

ResolveConflictFork marks a conflict\-fork entry as resolved.

<a name="Repo.ServeHTTP"></a>
### 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.

<a name="Repo.SetCaps"></a>
### func \(\*Repo\) SetCaps

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

SetCaps updates a user's capability string.

<a name="Repo.SetConfig"></a>
### func \(\*Repo\) SetConfig

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

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

<a name="Repo.SetPassword"></a>
### func \(\*Repo\) SetPassword

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

SetPassword updates a user's password.

<a name="Repo.StashApply"></a>
### func \(\*Repo\) StashApply

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

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

StashClear removes all stash entries.

<a name="Repo.StashDrop"></a>
### func \(\*Repo\) StashDrop

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

StashDrop removes a stash entry by ID.

<a name="Repo.StashList"></a>
### func \(\*Repo\) StashList

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

StashList returns all stash entries.

<a name="Repo.StashPop"></a>
### func \(\*Repo\) StashPop

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

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

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

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

<a name="Repo.Timeline"></a>
### func \(\*Repo\) Timeline

```go
func (r *Repo) Timeline(opts LogOpts) ([]LogEntry, error)
```

Timeline returns checkin log entries starting from the given RID.

<a name="Repo.UVDelete"></a>
### func \(\*Repo\) UVDelete

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

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

UVList returns all unversioned file entries.

<a name="Repo.UVRead"></a>
### 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.

<a name="Repo.UVWrite"></a>
### func \(\*Repo\) UVWrite

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

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

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

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

<a name="Repo.WithTx"></a>
### func \(\*Repo\) WithTx

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

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

RevertOpts configures reverting file changes.

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

<a name="RoundStats"></a>
## type RoundStats

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

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

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

<a name="SessionEnd"></a>
## type SessionEnd

SessionEnd describes the completion of a sync session.

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

<a name="SessionStart"></a>
## type SessionStart

SessionStart describes the beginning of a sync session.

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

<a name="StashEntry"></a>
## type StashEntry

StashEntry describes a saved stash.

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

<a name="StatusEntry"></a>
## type StatusEntry

StatusEntry describes a changed file in the working tree.

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

<a name="StatusOpts"></a>
## type StatusOpts

StatusOpts configures a working\-tree status query.

```go
type StatusOpts struct {
    Dir string
}
```

<a name="SyncObserver"></a>
## 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)
}
```

<a name="NopSyncObserver"></a>
### func NopSyncObserver

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

NopSyncObserver returns a SyncObserver that silently discards all events.

<a name="StdoutSyncObserver"></a>
### func StdoutSyncObserver

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

StdoutSyncObserver returns a SyncObserver that logs events to stderr.

<a name="SyncOpts"></a>
## 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
}
```

<a name="SyncResult"></a>
## 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
}
```

<a name="TableSyncEnd"></a>
## type TableSyncEnd

TableSyncEnd describes the completion of a config table sync.

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

<a name="TableSyncStart"></a>
## type TableSyncStart

TableSyncStart describes the beginning of a config table sync.

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

<a name="TagOpts"></a>
## type TagOpts

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

TagSpec describes a tag to attach to an artifact.

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

<a name="Transport"></a>
## 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)
}
```

<a name="NewHTTPTransport"></a>
### func NewHTTPTransport

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

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

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

RoundTrip calls the function.

<a name="UVEntry"></a>
## type UVEntry

UVEntry describes an unversioned file.

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

<a name="UpdateChange"></a>
## type UpdateChange

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

UpdateOpts configures updating to a new version with merge.

```go
type UpdateOpts struct {
    TargetRID int64 // 0 = tip
    Force     bool
}
```

<a name="User"></a>
## type User

User describes a Fossil user.

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

<a name="UserOpts"></a>
## type UserOpts

UserOpts configures a user creation or update.

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

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