Add --locked flag to verify lockfile is in sync

CHANGELOG.md

@@ -8,6 +8,12 @@
 - Add `--stdin-filepath` flag to `buf format`, which reads a single `.proto` file from
   stdin and writes the formatted result to stdout. The path is not read from disk, and is
   only used to report parse errors and diffs.
+- Add `--locked` flag to `buf build`, `buf breaking`, `buf export`, `buf generate`,
+  `buf lint`, `buf ls-files`, `buf push`, and `buf stats`, which errors if the `buf.lock`
+  of the input does not satisfy its `buf.yaml`. A module dependency, remote plugin, or
+  remote policy declared with an explicit reference, such as
+  `buf.build/bufbuild/protovalidate:v0.14.1`, must be pinned to the commit that the
+  reference resolves to.
 
 ## [v1.73.0] - 2026-09-11
 

cmd/buf/internal/command/breaking/breaking.go

@@ -53,6 +53,7 @@ const (
 	againstRegistryFlagName   = "against-registry"
 	excludePathsFlagName      = "exclude-path"
 	disableSymlinksFlagName   = "disable-symlinks"
+	lockedFlagName            = "locked"
 )
 
 // NewCommand returns a new Command.
@@ -92,6 +93,7 @@ type flags struct {
 	AgainstRegistry   bool
 	ExcludePaths      []string
 	DisableSymlinks   bool
+	Locked            bool
 	// special
 	InputHashtag string
 }
@@ -105,6 +107,7 @@ func (f *flags) Bind(flagSet *pflag.FlagSet) {
 	bufcli.BindInputHashtag(flagSet, &f.InputHashtag)
 	bufcli.BindExcludePaths(flagSet, &f.ExcludePaths, excludePathsFlagName)
 	bufcli.BindDisableSymlinks(flagSet, &f.DisableSymlinks, disableSymlinksFlagName)
+	bufcli.BindLocked(flagSet, &f.Locked, lockedFlagName)
 	flagSet.StringVar(
 		&f.ErrorFormat,
 		errorFormatFlagName,
@@ -201,6 +204,7 @@ func run(
 		wasmRuntime,
 		bufctl.WithTargetPaths(flags.Paths, flags.ExcludePaths),
 		bufctl.WithConfigOverride(flags.Config),
+		bufctl.WithLocked(flags.Locked),
 	)
 	if err != nil {
 		return err

cmd/buf/internal/command/build/build.go

@@ -43,6 +43,7 @@ const (
 	configFlagName                        = "config"
 	excludePathsFlagName                  = "exclude-path"
 	disableSymlinksFlagName               = "disable-symlinks"
+	lockedFlagName                        = "locked"
 	typeFlagName                          = "type"
 )
 
@@ -80,6 +81,7 @@ type flags struct {
 	Config                        string
 	ExcludePaths                  []string
 	DisableSymlinks               bool
+	Locked                        bool
 	Types                         []string
 	// special
 	InputHashtag string
@@ -97,6 +99,7 @@ func (f *flags) Bind(flagSet *pflag.FlagSet) {
 	bufcli.BindPaths(flagSet, &f.Paths, pathsFlagName)
 	bufcli.BindExcludePaths(flagSet, &f.ExcludePaths, excludePathsFlagName)
 	bufcli.BindDisableSymlinks(flagSet, &f.DisableSymlinks, disableSymlinksFlagName)
+	bufcli.BindLocked(flagSet, &f.Locked, lockedFlagName)
 	flagSet.BoolVar(
 		&f.ExcludeSourceRetentionOptions,
 		excludeSourceRetentionOptionsFlagName,
@@ -164,6 +167,7 @@ func run(
 		bufctl.WithImageExcludeImports(flags.ExcludeImports),
 		bufctl.WithImageIncludeTypes(flags.Types),
 		bufctl.WithConfigOverride(flags.Config),
+		bufctl.WithLocked(flags.Locked),
 	)
 	if err != nil {
 		return err

cmd/buf/internal/command/export/export.go

@@ -44,6 +44,7 @@ const (
 	configFlagName          = "config"
 	excludePathsFlagName    = "exclude-path"
 	disableSymlinksFlagName = "disable-symlinks"
+	lockedFlagName          = "locked"
 	allFlagName             = "all"
 )
 
@@ -103,6 +104,7 @@ type flags struct {
 	Config          string
 	ExcludePaths    []string
 	DisableSymlinks bool
+	Locked          bool
 	All             bool
 
 	// special
@@ -115,6 +117,7 @@ func newFlags() *flags {
 
 func (f *flags) Bind(flagSet *pflag.FlagSet) {
 	bufcli.BindDisableSymlinks(flagSet, &f.DisableSymlinks, disableSymlinksFlagName)
+	bufcli.BindLocked(flagSet, &f.Locked, lockedFlagName)
 	bufcli.BindInputHashtag(flagSet, &f.InputHashtag)
 	bufcli.BindExcludeImports(flagSet, &f.ExcludeImports, excludeImportsFlagName)
 	bufcli.BindPaths(flagSet, &f.Paths, pathsFlagName)
@@ -162,6 +165,7 @@ func run(
 		input,
 		bufctl.WithTargetPaths(flags.Paths, flags.ExcludePaths),
 		bufctl.WithConfigOverride(flags.Config),
+		bufctl.WithLocked(flags.Locked),
 	)
 	if err != nil {
 		return err

cmd/buf/internal/command/generate/generate.go

@@ -50,6 +50,7 @@ const (
 	includeWKTFlagName          = "include-wkt"
 	excludePathsFlagName        = "exclude-path"
 	disableSymlinksFlagName     = "disable-symlinks"
+	lockedFlagName              = "locked"
 	typeFlagName                = "type"
 	typeDeprecatedFlagName      = "include-types"
 	excludeTypeFlagName         = "exclude-type"
@@ -416,6 +417,7 @@ type flags struct {
 	IncludeWKTOverride     *bool
 	ExcludePaths           []string
 	DisableSymlinks        bool
+	Locked                 bool
 	// We may be able to bind two flags to one string slice but I don't
 	// want to find out what will break if we do.
 	Types           []string
@@ -431,6 +433,7 @@ func newFlags() *flags {
 
 func (f *flags) Bind(flagSet *pflag.FlagSet) {
 	bufcli.BindDisableSymlinks(flagSet, &f.DisableSymlinks, disableSymlinksFlagName)
+	bufcli.BindLocked(flagSet, &f.Locked, lockedFlagName)
 	bufcli.BindInputHashtag(flagSet, &f.InputHashtag)
 	bufcli.BindPaths(flagSet, &f.Paths, pathsFlagName)
 	bufcli.BindExcludePaths(flagSet, &f.ExcludePaths, excludePathsFlagName)
@@ -557,6 +560,7 @@ func run(
 		flags.ExcludePaths,
 		append(flags.Types, flags.TypesDeprecated...),
 		flags.ExcludeTypes,
+		flags.Locked,
 	)
 	if err != nil {
 		return err
@@ -632,6 +636,7 @@ func getInputImages(
 	excludePathsOverride []string,
 	includeTypesOverride []string,
 	excludeTypesOverride []string,
+	locked bool,
 ) ([]bufimage.Image, error) {
 	// If input is specified on the command line, we use that. If input is not
 	// specified on the command line, use the default input.
@@ -658,6 +663,7 @@ func getInputImages(
 			bufctl.WithTargetPaths(targetPathsOverride, excludePathsOverride),
 			bufctl.WithImageIncludeTypes(includeTypes),
 			bufctl.WithImageExcludeTypes(excludeTypes),
+			bufctl.WithLocked(locked),
 		)
 		if err != nil {
 			return nil, err
@@ -689,6 +695,7 @@ func getInputImages(
 			bufctl.WithTargetPaths(targetPaths, excludePaths),
 			bufctl.WithImageIncludeTypes(includeTypes),
 			bufctl.WithImageExcludeTypes(excludeTypes),
+			bufctl.WithLocked(locked),
 		)
 		if err != nil {
 			return nil, err

cmd/buf/internal/command/lint/lint.go

@@ -37,6 +37,7 @@ const (
 	pathsFlagName           = "path"
 	excludePathsFlagName    = "exclude-path"
 	disableSymlinksFlagName = "disable-symlinks"
+	lockedFlagName          = "locked"
 )
 
 // NewCommand returns a new Command.
@@ -68,6 +69,7 @@ type flags struct {
 	Paths           []string
 	ExcludePaths    []string
 	DisableSymlinks bool
+	Locked          bool
 	// special
 	InputHashtag string
 }
@@ -81,6 +83,7 @@ func (f *flags) Bind(flagSet *pflag.FlagSet) {
 	bufcli.BindPaths(flagSet, &f.Paths, pathsFlagName)
 	bufcli.BindExcludePaths(flagSet, &f.ExcludePaths, excludePathsFlagName)
 	bufcli.BindDisableSymlinks(flagSet, &f.DisableSymlinks, disableSymlinksFlagName)
+	bufcli.BindLocked(flagSet, &f.Locked, lockedFlagName)
 	flagSet.StringVar(
 		&f.ErrorFormat,
 		errorFormatFlagName,
@@ -138,6 +141,7 @@ func run(
 		wasmRuntime,
 		bufctl.WithTargetPaths(flags.Paths, flags.ExcludePaths),
 		bufctl.WithConfigOverride(flags.Config),
+		bufctl.WithLocked(flags.Locked),
 	)
 	if err != nil {
 		return err

cmd/buf/internal/command/lsfiles/lsfiles.go

@@ -45,6 +45,7 @@ const (
 	pathsFlagName             = "path"
 	excludePathsFlagName      = "exclude-path"
 	disableSymlinksFlagName   = "disable-symlinks"
+	lockedFlagName            = "locked"
 	asImportPathsFlagName     = "as-import-paths"
 
 	formatText   = "text"
@@ -94,6 +95,7 @@ type flags struct {
 	Paths             []string
 	ExcludePaths      []string
 	DisableSymlinks   bool
+	Locked            bool
 	// Deprecated. This flag no longer has any effect as we don't build images anymore.
 	ErrorFormat string
 	// Deprecated
@@ -111,6 +113,7 @@ func (f *flags) Bind(flagSet *pflag.FlagSet) {
 	bufcli.BindPaths(flagSet, &f.Paths, pathsFlagName)
 	bufcli.BindExcludePaths(flagSet, &f.ExcludePaths, excludePathsFlagName)
 	bufcli.BindDisableSymlinks(flagSet, &f.DisableSymlinks, disableSymlinksFlagName)
+	bufcli.BindLocked(flagSet, &f.Locked, lockedFlagName)
 	flagSet.StringVar(
 		&f.Config,
 		configFlagName,
@@ -187,6 +190,7 @@ func run(
 		input,
 		bufctl.WithTargetPaths(flags.Paths, flags.ExcludePaths),
 		bufctl.WithConfigOverride(flags.Config),
+		bufctl.WithLocked(flags.Locked),
 	)
 	if err != nil {
 		return err

cmd/buf/internal/command/push/push.go

@@ -43,6 +43,7 @@ const (
 	labelFlagName              = "label"
 	errorFormatFlagName        = "error-format"
 	disableSymlinksFlagName    = "disable-symlinks"
+	lockedFlagName             = "locked"
 	createFlagName             = "create"
 	createVisibilityFlagName   = "create-visibility"
 	createDefaultLabelFlagName = "create-default-label"
@@ -97,6 +98,7 @@ type flags struct {
 	Labels             []string
 	ErrorFormat        string
 	DisableSymlinks    bool
+	Locked             bool
 	Create             bool
 	CreateVisibility   string
 	CreateDefaultLabel string
@@ -114,6 +116,7 @@ func newFlags() *flags {
 func (f *flags) Bind(flagSet *pflag.FlagSet) {
 	bufcli.BindInputHashtag(flagSet, &f.InputHashtag)
 	bufcli.BindDisableSymlinks(flagSet, &f.DisableSymlinks, disableSymlinksFlagName)
+	bufcli.BindLocked(flagSet, &f.Locked, lockedFlagName)
 	bufcli.BindCreateVisibility(flagSet, &f.CreateVisibility, createVisibilityFlagName, createFlagName)
 	flagSet.StringSliceVar(
 		&f.Labels,
@@ -324,6 +327,7 @@ func getBuildableWorkspace(
 		// that we don't want to deal with. If we have a v1 workspace, just outlaw pushing the whole
 		// workspace, and force people into the pre-refactor behavior.
 		bufctl.WithIgnoreAndDisallowV1BufWorkYAMLs(),
+		bufctl.WithLocked(flags.Locked),
 	)
 	if err != nil {
 		return nil, err

cmd/buf/internal/command/stats/stats.go

@@ -33,6 +33,7 @@ import (
 const (
 	formatFlagName          = "format"
 	disableSymlinksFlagName = "disable-symlinks"
+	lockedFlagName          = "locked"
 )
 
 // NewCommand returns a new Command.
@@ -61,6 +62,7 @@ func NewCommand(
 type flags struct {
 	Format          string
 	DisableSymlinks bool
+	Locked          bool
 
 	// special
 	InputHashtag string
@@ -78,6 +80,7 @@ func (f *flags) Bind(flagSet *pflag.FlagSet) {
 		fmt.Sprintf(`The output format to use. Must be one of %s`, bufprint.AllFormatsString),
 	)
 	bufcli.BindDisableSymlinks(flagSet, &f.DisableSymlinks, disableSymlinksFlagName)
+	bufcli.BindLocked(flagSet, &f.Locked, lockedFlagName)
 	bufcli.BindInputHashtag(flagSet, &f.InputHashtag)
 }
 
@@ -104,6 +107,7 @@ func run(
 	workspace, err := controller.GetWorkspace(
 		ctx,
 		input,
+		bufctl.WithLocked(flags.Locked),
 	)
 	if err != nil {
 		return err

private/buf/bufcli/flags_args.go

@@ -148,6 +148,17 @@ By default, symlinks are followed in this CLI, but never followed on the Buf Sch
 	)
 }
 
+// BindLocked binds the locked flag.
+func BindLocked(flagSet *pflag.FlagSet, addr *bool, flagName string) {
+	flagSet.BoolVar(
+		addr,
+		flagName,
+		false,
+		`Error if the buf.lock is out of sync with the buf.yaml
+A module dependency, remote plugin, or remote policy declared in the buf.yaml with an explicit reference must be pinned to the commit that the reference resolves to in the buf.lock. Run "buf dep update", "buf plugin update", or "buf policy update" to update the buf.lock`,
+	)
+}
+
 // BindVisibility binds the visibility flag.
 func BindVisibility(flagSet *pflag.FlagSet, addr *string, flagName string, emptyDefault bool) {
 	defaultVisibility := privateVisibility