func (*Checkout) Add ¶

func (c *Checkout) Add(patterns []string) (int, error)

Add adds files to version tracking. Returns the number of files added. Files already tracked are silently skipped.

func (*Checkout) Checkin ¶

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.

func (*Checkout) CheckinContext ¶ added in v0.14.0

func (c *Checkout) CheckinContext(
	ctx context.Context, opts CheckoutCommitOpts, required RequiredContentOpts,
) (int64, string, error)

CheckinContext recovers necessary parent structure from an explicit peer, outside checkout locks and repository transactions. It then gathers checkout changes afresh; no stale file list is replayed after network I/O.

func (*Checkout) Close ¶

func (c *Checkout) Close() error

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

func (*Checkout) Cone ¶ added in v0.14.0

func (c *Checkout) Cone() *Cone

Cone returns the checkout's cone, or nil when the checkout is dense.

func (*Checkout) Conflicts ¶ added in v0.11.0

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.

func (*Checkout) Dir ¶

func (c *Checkout) Dir() string

Dir returns the checkout directory path.

func (*Checkout) Extract ¶

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.

func (*Checkout) HasChanges ¶

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.

func (*Checkout) Merge ¶ added in v0.11.0

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 followed as fossil's merge follows them: a change made under one name is merged into the file under another, and a file the merged-in checkin renamed is renamed here too (CheckoutMergeFile.RenamedTo); Merge refuses to rename one onto a file the checkout keeps or an untracked file. Merging the checkout's own version or one of its ancestors does nothing. The common ancestor is the one fossil's merge diffs against: the most recent common ancestor of the merged-in checkin and the checkout's version with every checkin already merged into it.

Under a structural horizon Merge refuses, with an error matching ErrBelowHorizon, a merge whose base it does not hold or whose sides' ancestry crosses the horizon (draft-fossil-horizon-00 §5.5): only the origin can name that base, and MergeContext with a Peer asks it.

func (*Checkout) MergeContext ¶ added in v0.15.0

func (c *Checkout) MergeContext(
	ctx context.Context, opts CheckoutMergeOpts, required RequiredContentOpts,
) (CheckoutMergeResult, error)

MergeContext is Merge with the remedy of draft-fossil-horizon-00 §5.5. Under a structural horizon, when Peer is given and the ancestry of either side crosses the horizon, it asks the origin for the base (§6.2.4) even when the store's own walk finds one, since over part of the graph the common ancestor found need not be the nearest. It deepens the horizon to the base the origin names when the store does not hold it (Repo.DeepenHorizon) and merges over that base. When the origin does not answer, or without a Peer, it is Merge, which refuses a merge whose ancestry crosses the horizon; when nothing crosses it is Merge. A merge never runs against a base the store does not hold.

The query names the merged-in version over the checkout's version and each plain merge pending in it. It carries at most two such secondaries, so a merge that must ask with two merges already pending is refused: asking without them would name a base Fossil's merge would not choose.

func (*Checkout) Redo ¶ added in v0.14.0

func (c *Checkout) Redo() (UndoResult, error)

Redo reverses the last Undo, reporting the files it changed as Undo does.

func (*Checkout) Remove ¶

func (c *Checkout) Remove(patterns []string) error

Remove removes files from version tracking. Newly added files are deleted from vfile; committed files are marked as deleted.

func (*Checkout) Rename ¶

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

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

func (*Checkout) ResolveVersion ¶ added in v0.12.0

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.

func (*Checkout) ResolveWorking ¶ added in v0.12.0

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.

func (*Checkout) Revert ¶

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 renamed file goes back to its committed name, whatever holds that name now. Each file it writes or deletes is saved for undo first, so Undo brings it back.

func (*Checkout) SetCone ¶ added in v0.14.0

func (c *Checkout) SetCone(next *Cone) (ConeChange, error)

SetCone replaces the checkout's cone; nil makes it dense. Files of the checked-out version that the new cone covers and the old one did not are written; files it no longer covers are removed from the working directory (the repository keeps them). It refuses, changing nothing, when a file leaving the cone has local changes or a file entering it would overwrite an untracked file. A cone with a horizon is refused with ErrHorizonCheckout.

func (*Checkout) SetConeContext ¶ added in v0.14.0

func (c *Checkout) SetConeContext(
	ctx context.Context, next *Cone, required RequiredContentOpts,
) (ConeChange, error)

SetConeContext recovers only structure needed to enumerate next and payloads newly entering the checkout. Explicit widening durably extends store coverage; an attempted fetch retains that intent even on failure. No-peer refusal does not change policy. Planning and local checks repeat before files move. A cone with a horizon is refused with ErrHorizonCheckout before anything moves.

func (*Checkout) Status ¶

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.

func (*Checkout) Undo ¶ added in v0.14.0

func (c *Checkout) Undo() (UndoResult, error)

Undo reverses the last operation that saved undo state, such as Update, as fossil's undo does: the files it changed come back, and the checkout's file list and version are as they were before it. Fossil's undo reads the same state, so either tool can undo the other's update.

func (*Checkout) Update ¶

func (c *Checkout) Update(opts UpdateOpts) (UpdateResult, error)

Update moves the checkout to a new version as fossil's update does, carrying uncommitted changes into it: a locally edited file is merged three ways (the checkout's version as base, the working file as local, the target as other), one the target deletes is kept untracked, and pending adds and removals stay pending. See UpdateResult for how to distinguish a clean update from one that wrote conflict markers into working-tree files.

func (*Checkout) UpdateContext ¶ added in v0.14.0

func (c *Checkout) UpdateContext(
	ctx context.Context, opts UpdateOpts, required RequiredContentOpts,
) (UpdateResult, error)

UpdateContext recovers necessary structure and selected update payloads from an explicit peer before checkout mutation. An implicit target is resolved once; after recovery the local update replans against fresh working files.

func (*Checkout) Version ¶

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

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

func (*Checkout) WouldFork ¶

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.

func (*Cone) Covers ¶ added in v0.14.0

func (c *Cone) Covers(path string) bool

Covers reports whether the cone covers path.

func (*Cone) Decide ¶ added in v0.14.0

func (c *Cone) Decide(path string) (covered bool, member string)

Decide reports whether the cone covers path and the member that decided: the longest member covering it, of either polarity, or "" when none does. Under longest match the deciding member is often not the first one listed, so naming it is what explains a verdict.

func (*Cone) Digest ¶ added in v0.14.0

func (c *Cone) Digest() string

Digest is the SHA3-256 of the cone's canonical serialization, in hex: equal for equal coverage, and the same value zit computes.

func (*Cone) Exclude ¶ added in v0.14.0

func (c *Cone) Exclude() []string

Exclude returns the exclusion members, sorted.

func (*Cone) Horizon ¶ added in v0.15.0

func (c *Cone) Horizon() (Horizon, bool)

Horizon returns the cone's horizon, if it has one.

func (*Cone) Include ¶ added in v0.14.0

func (c *Cone) Include() []string

Include returns the inclusion members, sorted.

func (*Cone) String ¶ added in v0.14.0

func (c *Cone) String() string

String lists the members in sorted order, an exclusion marked with '!'. A horizon leads, as "horizon <check-in> <rule> content".

func (*Cone) With ¶ added in v0.14.0

func (c *Cone) With(include, exclude []string) (*Cone, error)

With returns the cone with more members: the incremental form of widening (or, with exclusions, of narrowing).

func (*Cone) WithHorizon ¶ added in v0.15.0

func (c *Cone) WithHorizon(h *Horizon) (*Cone, error)

WithHorizon returns the cone with its horizon replaced by h, keeping the path members; nil drops the horizon. Dropping the horizon of a horizon-only cone is an error, since nothing is left: make the store dense with Repo.SetStoreCone(nil).

func (*Cone) Without ¶ added in v0.14.0

func (c *Cone) Without(paths []string) (*Cone, error)

Without returns the cone with every member equal to one of paths removed, of either polarity. A path that is not a member removes nothing.

func (*FslError) Error ¶

func (e *FslError) Error() string

func (*FslError) Unwrap ¶

func (e *FslError) Unwrap() error

func (HorizonRule) String ¶ added in v0.15.0

func (r HorizonRule) String() string

String names the rule as the operator spells it.

func (*MergeConflictError) Error ¶

func (e *MergeConflictError) Error() string

func (*MergeConflictError) Is ¶

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

func (*MockTransport) RoundTrip ¶

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

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

func (RC) String ¶

func (rc RC) String() string

func (*RefusedError) Error ¶ added in v0.17.0

func (e *RefusedError) Error() string

Error returns Message.

func (*Repo) Ancestry ¶

func (r *Repo) Ancestry(opts LogOpts) ([]LogEntry, error)

Ancestry walks the primary-parent chain starting from opts.Start: it emits that check-in, follows plink where isprim=1 to its parent, and repeats until the chain ends or opts.Limit is reached. This only ever sees first-parent ancestors of opts.Start — a merge's second parent, a sibling branch head, or any check-in outside that one chain will never appear. Use Timeline for a repository-wide view.

func (*Repo) Annotate ¶

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

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

On a store whose cone has a horizon, lines the walk cannot attribute past the horizon are reported as originating at it, marked BelowHorizon; AnnotateContext fetches the history that attributes them on a content horizon store.

func (*Repo) AnnotateContext ¶ added in v0.17.0

func (r *Repo) AnnotateContext(
	ctx context.Context, opts AnnotateOpts, required RequiredContentOpts,
) ([]AnnotatedLine, error)

AnnotateContext is Annotate with a demand fetch: on a content-horizon store, each version of the file the walk reads below the horizon and the store does not hold is fetched from Peer as the walk reaches it, so only what the walk reads is fetched and lines are attributed to the check-ins below the horizon that added them. A walk needing more than one demand fetch's 200 payloads stops there and returns what it attributed, the rest marked BelowHorizon, as does a walk that crosses a structural horizon, since naming those check-ins is a deepen. A start check-in below the horizon is fetched as ReadFileContext fetches it.

func (*Repo) AttachmentAdd ¶ added in v0.17.0

func (r *Repo) AttachmentAdd(target, name string, content []byte, opts AttachmentOpts) (artifact string, err error)

AttachmentAdd attaches content to target under name, as `fossil attachment add` does, and returns the hash of the control artifact. content is stored as one ordinary blob; only name's final path component is kept. The attachment table and timeline reflect it when AttachmentAdd returns, and both artifacts are queued to sync. The attachment becomes the latest for name: a zero opts.Time stamps it after whatever is latest now, and an explicit one no later than that is refused.

target is a wiki page's exact name, or a ticket's or tech note's id or a unique prefix of it. Fossil is told the kind; here it is inferred, and a name more than one kind answers to is refused as ambiguous.

Content that is a well-formed external-attachment stub is refused, since it would read back as an external attachment rather than as the bytes given: use AttachmentAddExternal. Content that parses as a fossil artifact is compressed and its name gains ".gz", as fossil does.

func (*Repo) AttachmentAddExternal ¶ added in v0.17.0

func (r *Repo) AttachmentAddExternal(target string, ref ExternalRef, opts AttachmentOpts) (artifact string, err error)

AttachmentAddExternal attaches the file ref names without its bytes, and returns the hash of the control artifact. The blob stored is the stub Quarry writes, and the control artifact's N card carries ref.Type, so stock fossil shows a small text file under ref.Name. The host stores the bytes; this records only where they are found. target resolves as in AttachmentAdd.

func (*Repo) AttachmentDelete ¶ added in v0.17.0

func (r *Repo) AttachmentDelete(target, name string, opts AttachmentOpts) (artifact string, err error)

AttachmentDelete removes the current attachment name from target, as fossil's attachment page does: a new control artifact whose A card names no file. The bytes stay in history. It returns the artifact's hash, and ErrAttachmentNotFound when target has no current attachment by that name. opts.Time, when set, must be later than the attachment's; when zero, the deletion is stamped after it even if it lies in the future.

func (*Repo) AttachmentRead ¶ added in v0.17.0

func (r *Repo) AttachmentRead(target, name string) (a Attachment, content []byte, err error)

AttachmentRead returns target's current attachment name and its bytes. For an external attachment the bytes are not here: content is nil and a.External says where the host keeps them. It returns ErrAttachmentNotFound when there is no such current attachment.

func (*Repo) Attachments ¶ added in v0.17.0

func (r *Repo) Attachments(target string) ([]Attachment, error)

Attachments returns target's current attachments, the most recently attached first: one per name, leaving out deleted ones, as fossil lists them on the target's page. target resolves as in AttachmentAdd.

func (*Repo) BranchOpenLeaf ¶ added in v0.12.0

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.

func (*Repo) BranchTip ¶

func (r *Repo) BranchTip(name string) (int64, error)

BranchTip returns the RID of the most recent checkin on the named branch. Resolves via the 'branch' propagating tag: the tip is the checkin with the latest event.mtime whose tagxref still has that branch value active. Returns an error if no such branch exists in the repository.

func (*Repo) Checkpoint ¶

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.

func (*Repo) Close ¶

func (r *Repo) Close() error

Close closes the repository and releases resources. As part of close, a WAL TRUNCATE checkpoint is run so the on-disk repo file is readable by external fossil/SQLite tooling.

func (*Repo) Commit ¶

func (r *Repo) Commit(opts CommitOpts) (int64, string, error)

Commit creates a new checkin manifest with the given files and returns the RID (row ID) and UUID of the newly created artifact. When ParentID is non-zero, files tracked at the parent but absent from opts.Files are carried forward into the new manifest (full-tree semantics — see the CommitOpts.Files doc).

func (*Repo) CommitContext ¶ added in v0.14.0

func (r *Repo) CommitContext(
	ctx context.Context, opts CommitOpts, required RequiredContentOpts,
) (int64, string, error)

CommitContext creates a commit, recovering required parent structure from Peer when necessary. Recovery runs without a write transaction and never broadens the store cone. The operation is retried once from the caller's original inputs after revalidating immutable parents and construction policy.

func (*Repo) CompactStore ¶ added in v0.14.0

func (r *Repo) CompactStore(ctx context.Context) (int, error)

CompactStore is the narrow-then-compact deletion (§5.4), the only one the sparse draft defines: it turns held blobs that only out-of-cone F cards name into elided phantoms and returns how many it dropped. Structural artifacts, sub-manifest nodes whose cards prove an elision, unsent or private content and the delta bases of retained artifacts stay held. A later widening fetches the dropped blobs again; it is not reversible locally.

func (*Repo) Config ¶

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

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

func (*Repo) CreateCheckout ¶

func (r *Repo) CreateCheckout(dir string, opts CheckoutCreateOpts) (*Checkout, error)

CreateCheckout creates a new checkout directory linked to this repository. The directory is created if it does not exist. The checkout is initialized to the tip checkin.

func (*Repo) CreateUser ¶

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

CreateUser creates a new user in the repository.

func (*Repo) CurrentTrunk ¶ added in v0.12.0

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

func (*Repo) DB ¶

func (r *Repo) DB() *db.DB

DB returns the underlying database handle for raw SQL queries. Use this when the high-level Repo methods don't cover your use case.

func (*Repo) DeepenHorizon ¶ added in v0.15.0

func (r *Repo) DeepenHorizon(
	ctx context.Context, target string, required RequiredContentOpts,
) (*SyncResult, error)

DeepenHorizon moves the store cone's horizon to an ancestor C' of its C from which target is reachable, and synchronizes at C' through Peer (draft-fossil-horizon-00 §5.8): target itself when it is C's ancestor, else a common ancestor of the two, asked of the origin when the store cannot see one. The rule, the depth and the path members stay; nothing held is replaced. A structural store discards the seed for C before it takes the one for C', and a transfer that fails puts both back.

target is a full check-in hash, which may name a check-in the store does not hold, or any name ResolveVersion resolves. Deepening needs a Peer and a store cone with a horizon.

func (*Repo) DeleteUser ¶

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

DeleteUser removes a user from the repository.

func (*Repo) DetectForks ¶

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

DetectForks finds divergent branches in the repository.

func (*Repo) Diff ¶

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

Diff returns the unified diff(s) between ridA and ridB.

When filePath is non-empty, returns 0 or 1 entries for that single file: the file is treated as empty bytes on any side where it is absent, so additions and deletions render as pure insert/delete hunks. An empty slice is returned when both sides are byte-identical.

When filePath is empty, returns one entry per file that changed between the two checkins (the union of files across both sides where the content UUID differs or the file exists on only one side). Entries are sorted by Name for deterministic ordering. An empty slice is returned when the two checkins have identical file sets and content.

Whole-checkin enumeration is currently name-keyed: a rename with no content change surfaces as a delete of the old name plus an add of the new name, and permission-only changes are not reflected. Proper rename and perm-change detection (via the underlying mlink table) is tracked as a follow-up; per-file diff behaviour for an explicitly named file is unchanged.

func (*Repo) DiffContext ¶ added in v0.17.0

func (r *Repo) DiffContext(
	ctx context.Context, ridA, ridB int64, filePath string, required RequiredContentOpts,
) ([]DiffEntry, error)

DiffContext is Diff with ReadFileContext's demand fetch: what both sides lack below the horizon is fetched in one round.

func (*Repo) DisableSubmanifests ¶ added in v0.14.0

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.

func (*Repo) EnableSubmanifests ¶ added in v0.14.0

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.

func (*Repo) FindCommonAncestor ¶

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

FindCommonAncestor finds the most recent common ancestor of two checkins, the merge base fossil's merge-base command names.

func (*Repo) GetUser ¶

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

GetUser returns information about a user.

func (*Repo) HandleSync ¶

func (r *Repo) HandleSync(ctx context.Context, payload []byte) ([]byte, error)

HandleSync processes an incoming xfer request (server-side). The payload is a raw xfer-encoded byte slice; the response is also raw bytes.

func (*Repo) HandleSyncWithOpts ¶

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

HandleSyncWithOpts processes an incoming xfer request with optional configuration.

When opts.MaxStoredBytes refuses the request, it returns both the encoded reply, which holds only the error card naming the artifact, and a *RefusedError carrying that card's text (match it with errors.As). The request was rolled back, so nothing from it is stored. A host serving the reply over HTTP sends it as usual, and the client prints the error; a host whose storage aborts the whole call on any rollback can report RefusedError.Message itself. Every other error returns a nil reply.

func (*Repo) HorizonCost ¶ added in v0.15.0

func (r *Repo) HorizonCost(checkin string) ([]HorizonRuleCost, error)

HorizonCost reports, for each rule in order (descendants, leaves), what a horizon at checkin would hold, so the choice of rule is made with its cost in view (§3.4). checkin is any name ResolveVersion accepts. The figures are read from this repository, which must hold the history: a blob it does not hold is left out of the byte counts, and a sub-manifest it lacks is an error.

func (*Repo) Inner ¶

func (r *Repo) Inner() *repo.Repo

Inner returns the underlying internal repo handle. This is exported for use by in-module packages (e.g., cli/) that need direct access to the repo DB for raw SQL or internal package calls.

func (*Repo) ListConflictForks ¶

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

ListConflictForks returns filenames with unresolved conflict-fork entries.

func (*Repo) ListFiles ¶

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

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

func (*Repo) ListFilesIn ¶ added in v0.16.2

func (r *Repo) ListFilesIn(rid int64, c *Cone) ([]FileEntry, error)

ListFilesIn is ListFiles narrowed to the files c covers; a nil cone lists every file. The cone is applied as a range predicate at the one enumeration seam every file set comes from (draft-fossil-sparse-cone-00 §4.1), so the result is ListFiles filtered by c.Covers, flat or tree, and a cone's horizon plays no part. On a tree manifest the walk skips every sub-manifest whose key range c cannot cover, so the cost follows the cone plus the spine rather than the whole tree (§4.5). Over a sparse store that makes it the listing that does not reach an elided out-of-cone node; a cone that reaches a node the store lacks still fails, naming it.

func (*Repo) ListUsers ¶

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

ListUsers returns all users in the repository.

func (*Repo) Merge ¶

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.

Files are matched across the three versions following renames, as fossil's merge matches them: a file srcBranch renamed and dstBranch did not takes srcBranch's name, and the commit records the rename; a file dstBranch renamed keeps its name.

func (*Repo) OpenCheckout ¶

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

OpenCheckout opens an existing checkout directory linked to this repository.

func (*Repo) Path ¶

func (r *Repo) Path() string

Path returns the filesystem path to the repository file.

func (*Repo) Pull ¶

func (r *Repo) Pull(ctx context.Context, url string, opts PullOpts) (*SyncResult, error)

Pull fetches commits and ancillary objects from a Fossil HTTP peer and applies them to this repo. It is a strict pull — nothing is sent.

Tiger Style: hostile inputs panic via assert at the boundary; transport failures return wrapped errors. Idempotent on a repo already at peer's tip (returns a SyncResult with Rounds=0–1 and FilesRecvd=0).

func (*Repo) ReadBlob ¶ added in v0.16.2

func (r *Repo) ReadBlob(uuid string) ([]byte, error)

ReadBlob returns the content of the artifact named uuid, a full SHA1 or SHA3-256 hash in lowercase hex, such as the UUID ListFiles reports for a file. An unknown hash returns ErrArtifactNotFound (wrapped). An artifact the store knows but does not hold, such as one elided below a horizon or outside a sparse cone, fails as ReadFile of a path naming it does.

func (*Repo) ReadFile ¶

func (r *Repo) ReadFile(rid int64, filePath string) ([]byte, error)

ReadFile returns the bytes of filePath as they existed in checkin rid. Returns ErrFileNotFound (wrapped) if the file is not tracked in that checkin. A file that exists but is empty returns ([]byte{}, nil).

func (*Repo) ReadFileAt ¶

func (r *Repo) ReadFileAt(version string, filePath string) ([]byte, error)

ReadFileAt reads filePath from the checkin identified by a symbolic version name (e.g. "tip", "trunk", a branch name, a UUID, or a UUID prefix). It calls ResolveVersion to obtain the RID, then delegates to ReadFile. Use ReadFile directly when you already have a numeric RID.

func (*Repo) ReadFileAtContext ¶ added in v0.17.0

func (r *Repo) ReadFileAtContext(
	ctx context.Context, version string, filePath string, required RequiredContentOpts,
) ([]byte, error)

ReadFileAtContext is ReadFileAt with ReadFileContext's demand fetch. The version is resolved locally; a structural store resolves a check-in below its horizon by the full hash its phantom carries.

func (*Repo) ReadFileContext ¶ added in v0.17.0

func (r *Repo) ReadFileContext(
	ctx context.Context, rid int64, filePath string, required RequiredContentOpts,
) ([]byte, error)

ReadFileContext is ReadFile that, when the check-in's file lies below the store cone's horizon and the store does not hold it, fetches exactly the artifacts the read needs from Peer and reads again: the payload, and for a structural store first the check-in's manifest, baseline and nodes. This is the targeted demand fetch of draft-fossil-horizon-00 §4.4: the store cone and its horizon do not move, and what is fetched is held content a later CompactStore may drop. Without a Peer the read fails as ReadFile does, matching ErrBelowHorizon and naming the horizon. A read needing more than one demand fetch carries is refused; DeepenHorizon is its remedy.

func (*Repo) Redo ¶

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

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

func (*Repo) ResolveBranchStart ¶ added in v0.12.0

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.

func (*Repo) ResolveConflictFork ¶

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

ResolveConflictFork marks a conflict-fork entry as resolved.

func (*Repo) ResolveVersion ¶

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.

func (*Repo) RetuneSubmanifests ¶ added in v0.14.0

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.

func (*Repo) ServeHTTP ¶

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. Like XferHandler it serves with default HandleOpts, so no HandleOpts.MaxStoredBytes budget applies.

func (*Repo) SetCaps ¶

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

SetCaps updates a user's capability string.

func (*Repo) SetConfig ¶

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

SetConfig writes a configuration value to the repo's config table. A SettingHorizonSeedKey value that is neither an SSH public key nor an OpenPGP fingerprint is refused.

func (*Repo) SetContentCache ¶ added in v0.16.2

func (r *Repo) SetContentCache(bytes int64)

SetContentCache attaches a cache of expanded artifact content, bounded by bytes, that ReadFile, ReadFileAt, ReadBlob, ListFiles, ListFilesIn, Diff and Annotate share. It replaces any cache already attached; bytes <= 0 detaches it. The default is no cache. It is safe to call while other goroutines read.

The bound covers expanded content; the parses of the few check-in manifests read most recently are kept beside it. Any write through this Repo empties the cache. A write by another process, or through another Repo opened on the same file, does not: attach a cache only where this Repo is the store's one writer, or where no other writer purges, compacts or narrows it.

func (*Repo) SetHashPolicy ¶ added in v0.12.0

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.

func (*Repo) SetPassword ¶

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

SetPassword updates a user's password.

func (*Repo) SetStoreCone ¶ added in v0.14.0

func (r *Repo) SetStoreCone(c *Cone) error

SetStoreCone replaces the store cone; nil makes the store dense. It moves no content. Narrowing deletes nothing (§5.4). Widening makes the newly covered elided phantoms wanted again, and the next pull fetches them. While a cone is set, a commit carries no R card (§4.3).

A cone may carry a horizon (draft-fossil-horizon-00): setting one elides blobs only check-ins below it name, and SetStoreCone moves no content, as for any narrowing. Setting an older check-in, or nil, widens, and SetStoreConeContext fetches what the deeper horizon keeps.

func (*Repo) SetStoreConeContext ¶ added in v0.14.0

func (r *Repo) SetStoreConeContext(
	ctx context.Context, next *Cone, required RequiredContentOpts,
) (*SyncResult, error)

SetStoreConeContext is the policy form of demand fetch (draft-fossil-sparse-cone-00 §6.4): it replaces the store cone and, when that makes elided artifacts wanted again, pulls them from Peer through an ordinary cone-scoped synchronization. With artifacts to fetch and no Peer it refuses, naming the elided count and the missing peer, and leaves the cone unchanged. A transfer that fails after the cone is replaced keeps the wider policy, so the next ordinary pull heals it. Narrowing needs no peer.

func (*Repo) StashApply ¶

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

StashApply restores a stash entry by ID without removing it.

func (*Repo) StashClear ¶

func (r *Repo) StashClear() error

StashClear removes all stash entries.

func (*Repo) StashDrop ¶

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

StashDrop removes a stash entry by ID.

func (*Repo) StashList ¶

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

StashList returns all stash entries.

func (*Repo) StashPop ¶

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

StashPop restores the most recent stash entry and removes it.

func (*Repo) StashSave ¶

func (r *Repo) StashSave(dir, comment string) error

StashSave saves working-tree changes to the stash. Requires a checkout database; not yet wired (Repo only wraps the repo DB).

func (*Repo) StoreCone ¶ added in v0.14.0

func (r *Repo) StoreCone() (*Cone, error)

StoreCone returns the repository's store cone, or nil when the store is dense. A store cone (draft-fossil-sparse-cone-00 §5) is local policy: an artifact the cone leaves out may be deliberately absent, an elided phantom, which synchronization does not request and verification counts apart from damage. A cone this version cannot read is lost policy and reads as nil, so the store heals toward dense.

func (*Repo) Sync ¶

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

Sync runs a sync session against the given transport.

func (*Repo) Tag ¶

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.

func (*Repo) TicketAdd ¶ added in v0.17.0

func (r *Repo) TicketAdd(opts TicketOpts) (ticketUUID, artifact string, err error)

TicketAdd creates a ticket, as `fossil ticket add` does, and returns its new id and the hash of the artifact that created it. The ticket table reflects it when TicketAdd returns, and the artifact is queued to sync.

func (*Repo) TicketChanges ¶ added in v0.17.0

func (r *Repo) TicketChanges(ticket string) ([]TicketChange, error)

TicketChanges returns the changes of the ticket whose id is or starts with ticket, oldest first: the order fossil applies them in, as `fossil ticket history` lists them.

func (*Repo) TicketList ¶ added in v0.17.0

func (r *Repo) TicketList() ([]Ticket, error)

TicketList returns every ticket, the most recently changed first.

func (*Repo) TicketSet ¶ added in v0.17.0

func (r *Repo) TicketSet(ticket string, opts TicketOpts) (artifact string, err error)

TicketSet changes the ticket whose id is or starts with ticket, as `fossil ticket set` does, and returns the hash of the change artifact.

func (*Repo) Timeline ¶

func (r *Repo) Timeline(opts TimelineOpts) ([]TimelineEntry, error)

Timeline enumerates the repository's events newest-first: every row of the event table by default, or just the rows matching opts.Type when set (canonical `fossil timeline`'s -t/--type default: no filter unless one is given). Unlike Ancestry, this does not start from or require any particular check-in — it is a repository-wide view, not a walk.

Ordering is (mtime DESC, rid DESC), a total order with rid as a true tie-break at exact mtime equality — a deliberate improvement over canonical fossil, which orders by mtime DESC alone with no tie-break, and paginates with a bare-timestamp web cursor carrying a one-second slop, so rows at a page boundary there can repeat or be skipped. Do not "fix" this back to canonical: it is intentional. To page through the full result set, pass the last entry's Cursor back as the next call's TimelineOpts.After — never construct a cursor from a TimelineEntry's Time by hand; see Cursor's doc comment for why that round trip is lossy.

func (*Repo) TimelineSince ¶ added in v0.17.0

func (r *Repo) TimelineSince(hash string, kinds ...EventKind) ([]TimelineEntry, error)

TimelineSince returns the timeline entries whose artifacts arrived in this repository after the artifact with full hash hash: stored by a later receipt (a later push, pull or local write), or later within the same one. kinds, when given, keeps only entries of those kinds. The entries are in Timeline's order, newest first; an empty result is an empty slice, not nil. A hash the repository does not hold is an error.

Arrival, not timestamp, is what "after" means, because the question this answers is what a push brought in: an artifact made on a machine whose clock runs behind the given artifact's still arrived after it. Arrival order is this repository's own, so two clones can answer differently.

func (*Repo) UUIDFromRID ¶

func (r *Repo) UUIDFromRID(rid int64) (string, error)

UUIDFromRID returns the UUID (manifest hash) of the artifact identified by rid. The UUID is the stable, content-addressed identifier for the artifact; the rid is a repository-local integer that may differ across clones.

Returns ErrArtifactNotFound (wrapped) if no artifact with the given rid exists in the repository. The wrapped error message includes the offending rid. Other errors surface as-is.

func (*Repo) UVDelete ¶

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

UVDelete marks an unversioned file as deleted (tombstone).

func (*Repo) UVList ¶

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

UVList returns all unversioned file entries.

func (*Repo) UVRead ¶

func (r *Repo) UVRead(name string) ([]byte, int64, string, error)

UVRead reads an unversioned file from the repository. Returns the content, mtime (unix seconds), and content hash.

func (*Repo) UVWrite ¶

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

UVWrite writes an unversioned file to the repository.

func (*Repo) Undo ¶

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

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

func (*Repo) Verify ¶

func (r *Repo) Verify() error

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

func (*Repo) VerifySeed ¶ added in v0.15.0

func (r *Repo) VerifySeed(ctx context.Context, required RequiredContentOpts) (*SeedVerification, error)

VerifySeed verifies a structural store's seed by deepening (draft-fossil-horizon-00 §5.9): it fetches every manifest below the horizon from Peer, so the store holds the real tag artifacts and primary-parent chains, discards the seed, and compares what the store now derives at each entry with what the seed asserted. The price is that history, and the store stays a content-horizon store at the same C, which holds no seed; a failed transfer puts the structural cone and seed back.

func (*Repo) WithTx ¶

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

WithTx executes fn within a database transaction.

func (*Repo) XferHandler ¶

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). It serves with default HandleOpts, so no HandleOpts.MaxStoredBytes budget applies.

func (TransportFunc) RoundTrip ¶

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

RoundTrip calls the function.