Skip to content

Migration: pkg/config → go/config

Superseded (2026-07-20): this note's thesis — "it is the toolkit's Viper layer: it carries the Viper stack so nothing else has to" — is now exactly inverted. go/config v0.3.0 replaced the container with a Viper-free Store, and GTB migrated to it; see the config Store migration. The text below is the historical record of the v0.2.0 extraction.

The configuration container has been extracted out of go-tool-base into the standalone module gitlab.com/phpboyscout/go/config (v0.1.0). It is the toolkit's Viper layer: it carries the Viper stack so nothing else has to.

What changed

  • The package gitlab.com/phpboyscout/go-tool-base/pkg/config no longer exists. It now lives at gitlab.com/phpboyscout/go/config.
  • The public API is identical. Container, Containable, Observable, Observer, Section[T], ObservedSection[T], SectionChange[T], the WithSection* binding options, Schema, FieldSchema, ValidationResult, ValidateStruct[T], SchemaOf[T], LoadFilesContainer(WithSchema), NewFilesContainer, NewReaderContainer, NewContainerFromViper, Load, LoadEmbed, LoadEnv, every With* container option, ErrNoFilesFound, ErrConfigFileNotFound, and DefaultReloadDebounce are unchanged.
  • The mocks moved and are now published by the module. mocks/pkg/config is deleted; the module ships importable mocks at gitlab.com/phpboyscout/go/config/mocks (MockContainable, MockObservable). The unused EmbeddedFileReader mock is gone — that interface no longer exists.
  • The only behavioural change: ErrNoFilesFound's message is now tool-agnostic (it no longer names GTB's init command or --config flag). Nothing matches on its text.
  • There is no GTB adapter and no compatibility shim — a clean pre-1.0 import-path change (pkg/config had zero go-tool-base imports).

How to migrate

Repoint both paths — nothing else changes:

-import "gitlab.com/phpboyscout/go-tool-base/pkg/config"
+import "gitlab.com/phpboyscout/go/config"

-import mockcfg "gitlab.com/phpboyscout/go-tool-base/mocks/pkg/config"
+import mockcfg "gitlab.com/phpboyscout/go/config/mocks"

A repository-wide substitution is sufficient (package names and every symbol are unchanged — note the mocks path first, so it isn't caught by the broader rule):

grep -rl 'go-tool-base/mocks/pkg/config' --include='*.go' . \
  | xargs sed -i 's#gitlab.com/phpboyscout/go-tool-base/mocks/pkg/config#gitlab.com/phpboyscout/go/config/mocks#g'
grep -rl 'go-tool-base/pkg/config' --include='*.go' . \
  | xargs sed -i 's#gitlab.com/phpboyscout/go-tool-base/pkg/config#gitlab.com/phpboyscout/go/config#g'
go get gitlab.com/phpboyscout/go/[email protected]
go mod tidy

If you generated your own mocks of Containable, you can now drop them and import the module's instead.

Notes

  • go-tool-base consumes go/config directly. The GTB-specific layers are unchanged and stay in the framework: the assets/init/config.yaml embedded-defaults convention, the project-local .<tool>.yaml layer, Props.Tool.EnvPrefix propagation, the root command's flag-binding options, initialiser integration, and the config command's sensitive-value masking. See the Configuration component.
  • Full documentation — sources and precedence, typed sections, hot-reload safety, validation, and the reasoning behind the wrapper — lives at config.go.phpboyscout.uk; the API reference is on pkg.go.dev.