Artifact [88a83986ca]

Artifact 88a83986ca7a8cd755e4ae76cee3c9914aa5894011bc5b94ed062a610c481b4c:

• File docs/site/content/docs/quickstart.md — part of check-in [f30849a466] at 2026-04-26 14:14:53 on branch trunk — docs: usability improvements from DX audit (#9)

  Implements all seven recommended changes from the docs audit:

  1. SDK pages now show package names in nav. Add scripts/prepend-sdk-frontmatter.sh that prepends '--- title: <pkg> ---' to each gomarkdoc-generated api.md; wired into 'make docs-gen-sdk'. Sidebar previously showed five undifferentiated 'API' entries; now shows cli, db, dst, libfossil, observer/otel.

  2. /examples/ populated with paragraphs + GitHub deep-links for embed-repo-api and wasm. No longer a placeholder pointing back at the repo.

  3. Architecture page gets an inline SVG mirroring the landing-page diagram. Self-contained CSS (uses currentColor + ember accent) so it tracks Hextra's light/dark theme without depending on the landing's CSS scope.

  4. Cross-links added: quickstart -> production + extension-points, migration -> architecture, architecture -> extension-points. Extension Points and Production patterns are now reachable via prose, not just the sidebar.

  5. /docs/ landing expanded from 3 sentences to a 7-line subsection map calling out each page's purpose.

  6. Version indicator in navbar (libfossil v0.4.2). Override layouts/_partials/navbar-title.html mimics Hextra's default and appends a small mono version tag from .Site.Params.version.

  7. New /docs/production/ page covering error handling, context cancellation, telemetry wiring, repo-handle lifetime, and driver selection — the patterns the quickstart's log.Fatal shortcuts gloss over. (user: [email protected], size: 2254) [annotate] [blame] [check-ins using]

---
title: Quickstart
weight: 10
---

A five-minute tour of libfossil: clone a repo and read its history from Go.

## Install

```sh
go install github.com/danmestas/libfossil/cmd/libfossil@latest
libfossil --help
```

The binary is pure-Go and CGo-free — drop it on any host.

## Clone a repository

Clone using the Go API:

```go
package main

import (
    "context"
    "log"

    "github.com/danmestas/libfossil"
)

func main() {
    t := libfossil.NewHTTPTransport("https://example.com/repo.fossil")
    repo, _, err := libfossil.Clone(context.Background(), "./repo.fossil", t, libfossil.CloneOpts{})
    if err != nil {
        log.Fatal(err)
    }
    defer repo.Close()
}
```

## Open from Go

After cloning (above), open the same `.fossil` file from Go and read its history:

```go
package main

import (
    "fmt"
    "log"

    "github.com/danmestas/libfossil"
)

func main() {
    repo, err := libfossil.Open("repo.fossil")
    if err != nil {
        log.Fatal(err)
    }
    defer repo.Close()

    entries, err := repo.Timeline(libfossil.LogOpts{Limit: 10})
    if err != nil {
        log.Fatal(err)
    }
    for _, e := range entries {
        fmt.Println(e.UUID, e.Comment)
    }
}
```

## Sync over HTTP

```go
package main

import (
    "context"
    "log"

    "github.com/danmestas/libfossil"
)

func main() {
    repo, err := libfossil.Open("repo.fossil")
    if err != nil {
        log.Fatal(err)
    }
    defer repo.Close()

    t := libfossil.NewHTTPTransport("https://example.com/repo.fossil")
    if _, err := repo.Sync(context.Background(), t, libfossil.SyncOpts{Pull: true}); err != nil {
        log.Fatal(err)
    }
}
```

Or use the simpler `Pull` wrapper for pull-only workflows:

```go
_, err := repo.Pull(context.Background(), "https://example.com/repo.fossil", libfossil.PullOpts{})
```

## Next steps

- [Architecture](../architecture) — how the pieces fit
- [Production patterns](../production) — error handling, context, telemetry beyond `log.Fatal`
- [Extension Points](../extension-points) — observers for telemetry, custom SQLite drivers
- [Migration from Fossil](../migration-from-fossil) — command mapping from upstream
- [SDK reference](../reference/sdk) — every package, every exported symbol