config loading fixtures🔗

Each case pairs a config.yaml input with the result of loading it: either the normalized repo listing, or the startup error. Paths are shown with the config file's directory as $BASE. Regenerate the result hunks with go test -run TestLoadConfig . -testmark.regen.

Good configs🔗

The minimal config: one repo, and the % placeholder saying its path matches its name.

repos:
  parnass:
    path: "%"

repo parnass: path=$BASE/parnass

Names may be slash-nested to arbitrary depth; paths may be relative (resolved against the config file's directory, even pointing outside it) or absolute; descriptions are optional.

repos:
  parnass:
    path: "%"
    description: "the showcase repo"
  work/infra/deploy:
    path: ../deploy
  elsewhere:
    path: /srv/git/elsewhere

repo elsewhere: path=/srv/git/elsewhere
repo parnass: path=$BASE/parnass description="the showcase repo"
repo work/infra/deploy: path=$PARENT/deploy

Trailing slashes on paths are normalized away.

repos:
  tidy:
    path: "sub/dir/"

repo tidy: path=$BASE/sub/dir

The base URL🔗

baseurl names the canonical outside address of this socle: it becomes the displayed clone URL and enables the go-get vanity-import answers. It is optional; without it, clone URLs derive from each request and go-get is not served.

baseurl: https://code.example
repos:
  parnass:
    path: "%"

baseurl=https://code.example
repo parnass: path=$BASE/parnass

One trailing slash is tolerated and trimmed.

baseurl: https://code.example/
repos:
  parnass:
    path: "%"

baseurl=https://code.example
repo parnass: path=$BASE/parnass

It must be an absolute http(s) URL naming only a host: no bare hostnames, no other schemes, and no path -- socle's URL space is rooted at /, so a path prefix would promise routing it can't deliver.

baseurl: code.example
repos:
  parnass:
    path: "%"

error: config $BASE/config.yaml: baseurl "code.example": must be an absolute URL with scheme http or https

baseurl: ssh://code.example
repos:
  parnass:
    path: "%"

error: config $BASE/config.yaml: baseurl "ssh://code.example": must be an absolute URL with scheme http or https

baseurl: https://code.example/git
repos:
  parnass:
    path: "%"

error: config $BASE/config.yaml: baseurl "https://code.example/git": must name only a host, with no path, query, fragment, or userinfo

Bad configs🔗

Every problem below is a startup error: socle refuses to run on a config it can't fully honor.

Unknown keys are errors, not silence; typos should not quietly change meaning.

repos:
  parnass:
    path: "%"
    exposed: true

error: config $BASE/config.yaml: yaml: unmarshal errors:
  line 4: field exposed not found in type main.repoConfig

A config with nothing to serve is a misconfiguration.

repos: {}

error: config $BASE/config.yaml: no repos configured; a socle with nothing on display is a misconfiguration

Repo names are validated: segments of [A-Za-z0-9._-], no leading dot or dash.

repos:
  .hidden:
    path: "%"

error: config $BASE/config.yaml: invalid: repo name ".hidden": segment ".hidden" starts with "."

Names ending in .git are rejected: URLs treat a trailing .git as an alias for the plain name, and configuring one would make that alias ambiguous.

repos:
  parnass.git:
    path: "%"

error: config $BASE/config.yaml: invalid: repo name "parnass.git": segment "parnass.git" ends in .git (reserved as a URL alias for the plain name)

No repo name may be a path-prefix of another; nested names would make URL dispatch ambiguous.

repos:
  work:
    path: "%"
  work/deploy:
    path: "%"

error: config $BASE/config.yaml: repo "work" is a path-prefix of repo "work/deploy"; nested names would make URL dispatch ambiguous

The path field is required; an empty entry is probably an accident, so there is no default.

repos:
  parnass:
    description: "all description, no substance"

error: config $BASE/config.yaml: repo "parnass": missing required field "path" (use "path: %" to serve the path matching the repo name)

Serving the filesystem root is refused outright.

repos:
  everything:
    path: "/"

error: config $BASE/config.yaml: repo "everything": path "/" is the filesystem root; refusing