Skip to content

doc: list the sources find() actually consults, in order - #2177

Open
ump45nose wants to merge 1 commit into
spf13:masterfrom
ump45nose:doc/find-precedence-matches-get
Open

ump45nose wants to merge 1 commit into
spf13:masterfrom
ump45nose:doc/find-precedence-matches-get

Conversation

@ump45nose

@ump45nose ump45nose commented Oct 19, 2026 •

Copy link
Copy Markdown

What

The find() doc comment lists the lookup order as "flag, env, config file, key/value store". The function consults two more sources, and the comment omits the one that comes first and the one that comes last-but-one.

Why

find() walks, in this order (inline step comments are authoritative):

step line source
1 viper.go:1212 (// Set() override first) v.searchMap(v.override, path)
2 viper.go:1221 (// PFlag override next) bound pflags
3 viper.go:1271 (// Env override next) env
4 viper.go:1295 (// Config file next) config
5 viper.go:1304 (// K/V store next) remote key/value store
6 viper.go:1313 (// Default next) v.searchMap(v.defaults, path)

and only after all six, at viper.go:1322-1324, the "Lastly … the flag's default value" fallback the comment already describes.

So the list as written (a) starts at "flag" although Set() overrides are consulted before it — which is exactly the precedence users trip over when a Set() value shadows a flag — and (b) never mentions defaults, which are consulted before the flag default.

The same file already documents the complete order twice, in the package comment (viper.go:75-81) and on Get (viper.go:703 and viper.go:708-712: "override, flag, env, config file, key/value store, default"). Only find()'s copy is short, so this brings one comment in line with the other two rather than inventing wording.

Change

One comment line: the order list becomes override, flag, env, config file, key/value store, default. Comment-only; no behavior change.

Testing

gofmt-neutral (a line comment, no code or alignment touched) and no behavior change, so make lint / go test ./... were not re-run; I could not execute the Go toolchain in my environment. The order above is read directly from find() at master (528f741).

Notes

Correction (body edit): my first version of this note said the PR was labelled release-note/ignore. It is not — I have no triage permission on this repository, so I could not add the label, and the "Check minimum labels" step in .github/workflows/checks.yaml:16-33 will stay red until a maintainer applies release-note/ignore (or another accepted label) to this docs-only change.

Relation to my other open PRs

Independent: #2170 rewords the remote-provider SetConfigType examples in README.md, #2167 documents AutomaticEnv, #2166 the pflag wrappers, #2165 DecodeHook's default — none touch find() or the precedence list.

Submitted with AI assistance; the doc/code discrepancy was verified line by line against find() and the Get/package comments before opening.

find() reads the override map first (viper.go:1212) and the defaults map
before the flag-default fallback (viper.go:1313), but the comment's list
started at flag and omitted defaults. The Get doc a few hundred lines above
(viper.go:712) already states the full order.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant