many: `force-repo-dir` instead of `force-data-dir` #408

supakeen · 2025-12-15T10:04:13Z

Previously I deprecated data-dir and renamed it to force-data-dir to have consistent naming for options that overwrite internal state instead of appending to it (arguments that start with force- are overwrites, arguments that start with extra- are merges).

With force-data-dir we require a repositories sub directory. After some discussion we came to the idea to instead of enforcing a directory layout on the user we want to be able to point directly at a directory of repositories.

This commit deprecates force-data-dir and introduces force-repo-dir. Both write to the same internal variable.

We also allow repository files to live either in a repositories subdirectory to keep backwards compatibility for any of the arguments or to live directly at the top level of the passed directory.

We show a deprecation warning if a repositories sub directory exists and inform users that the repositories subdirectory will not be wanted in the future and how to resolve the emitted warning.

This option will be used together with the future introduction of force-defs-dir to handle definitions (and its extra-defs-dir counter part) unifying all options into a consistent naming scheme.

supakeen · 2025-12-15T10:05:31Z

Since we had some previous discussion about not growing too many arguments; this will (eventually, we need to decide a timeline) be the only argument left over. data-dir and force-data-dir are deprecated.

This also more importantly unifies the naming of arguments to be force-* for anything fully overriding builtins, and extra- for anything merging with builtins.

This also reintroduces the ability to load repositories directly from the root of the passed force-repo-dir; in the future the only option as enforcing this subdirectory layout on users is something we probably don't want to do.

We'll need to establish a timeframe for this.

After a chat in our community Matrix channel I realized that we have not documented the various ways of managing repositories in `image-builder`. Let's start that off with a small initial page that I will build on in the following commits. This relies on the implementation of the new `force-repo-dir` behavior as that's the behavior documented [1]. [1]: osbuild#408 Signed-off-by: Simon de Vlieger <[email protected]>

cmd/image-builder/main.go

thozza · 2025-12-17T10:41:30Z

cmd/image-builder/repos_test.go

@@ -71,8 +71,8 @@ func TestNewRepoRegistryImplDatadir(t *testing.T) {

 	// create a custom datadir with testdistro-1.json, the basefilename


Nitpick: the comment should be amended, since it still mentions datadir.

thozza · 2025-12-17T10:51:03Z

cmd/image-builder/repos_test.go

+	repoDir := t.TempDir()
+	repoFile := filepath.Join(repoDir, "repositories", "testdistro-1.json")


It may be beneficial to test this also without the repositories sub-directory.

I've added a second test that tests without the repositories sub directory but is otherwise the same.

thozza · 2025-12-17T10:53:25Z

cmd/image-builder/main.go

+	rootCmd.PersistentFlags().StringVar(&forceRepoDir, "force-data-dir", "", `Override the default data directory for e.g. custom repositories/*.json data`)
+	rootCmd.PersistentFlags().MarkDeprecated("force-data-dir", `Use --force-repo-dir instead`)
+	rootCmd.PersistentFlags().StringVar(&forceRepoDir, "data-dir", "", `Override the default data directory for e.g. custom repositories/*.json data`)
 	rootCmd.PersistentFlags().MarkDeprecated("data-dir", `Use --force-data-dir instead`)


You may want to fix the deprecation message here to suggest --force-repo-dir instead.

thozza · 2025-12-17T10:55:44Z

cmd/image-builder/main.go

 	switch name {
 	case "data-dir":
-		name = "force-data-dir"
+		name = "force-repo-dir"


Should the force-data-dir option be normalized as well?

Good catch yes, I've added normalization for that one too.

thozza · 2025-12-17T10:57:03Z

cmd/image-builder/repos.go

+		if _, err := os.Stat(withRepoSubdir); err == nil {
+			// we don't care about the error case here, we just want to know
+			// if it exists; not if we can't read it or other errors
+			fmt.Fprintf(os.Stderr, "WARNING: `force-repo-dir` found a `repositories` subdirectory at '%s', in the future `image-builder` will not descend into this subdirectory to look for repository files. Please move any repository files directly into the directory '%s' and remove the `repositories` subdirectory to silence this warning.\n", withRepoSubdir, repoDir)


Mentioning the force-repo-dir option here may be misleading, since one could specify --data-dir and get the warning about an option that they didn't use.

Done, now doesn't mention an option name at all; that isn't perfect since the user has to extrapolate but it's also less confusing (and I don't want to mention all options).

thozza · 2026-01-13T19:51:41Z

I accidentally approved the PR, while there are still comments that I wanted to be addressed. Although I can't remove the approval, also don't want to formally request changes. Since the branch has conflicts, it can't be merged as is anyway, so this is all good from my PoV. Sorry for the noise.

After a chat in our community Matrix channel I realized that we have not documented the various ways of managing repositories in `image-builder`. Let's start that off with a small initial page that I will build on in the following commits. This relies on the implementation of the new `force-repo-dir` behavior as that's the behavior documented [1]. [1]: osbuild#408 Signed-off-by: Simon de Vlieger <[email protected]>

Previously I deprecated `data-dir` and renamed it to `force-data-dir` to have consistent naming for options that overwrite internal state instead of appending to it (arguments that start with `force-` are overwrites, arguments that start with `extra-` are merges). With `force-data-dir` we require a `repositories` sub directory. After some discussion we came to the idea to instead of enforcing a directory layout on the user we want to be able to point directly at a directory of repositories. This commit deprecates `force-data-dir` and introduces `force-repo-dir`. Both write to the same internal variable. We also allow repository files to live *either* in a `repositories` subdirectory to keep backwards compatibility for any of the arguments or to live directly at the top level of the passed directory. We show a deprecation warning if a `repositories` sub directory exists and inform users that the `repositories` subdirectory will not be wanted in the future and how to resolve the emitted warning. This option will be used together with the future introduction of `force-defs-dir` to handle definitions (and its `extra-defs-dir` counter part) unifying all options into a consistent naming scheme. Signed-off-by: Simon de Vlieger <[email protected]>

lzap

Very long warning, three lines on 80x25 terminal, this will be quite effective. :D

I am wondering why you used backtics and single quotes is that some kind of standard or convention in CLI? I would probably use %q for both to save keystrokes.

supakeen · 2026-01-29T08:49:24Z

Very long warning, three lines on 80x25 terminal, this will be quite effective. :D

I am wondering why you used backtics and single quotes is that some kind of standard or convention in CLI? I would probably use %q for both to save keystrokes.

I think it's partial markdown and partial representation of strings (in Python).

achilleas-k · 2026-01-29T12:11:03Z

Throwing a tiny spanner in the works here after all this time but:

The description of every --force-... option begins with Override .... Wouldn't --override-... be a better name for the options? Character count is one reason to go with force, I suppose, but I also don't know if force is a good term here. It doesn't align with the general use of --force / -f as a clarg in my mind.

supakeen · 2026-01-29T12:27:20Z

Throwing a tiny spanner in the works here after all this time but:

The description of every --force-... option begins with Override .... Wouldn't --override-... be a better name for the options? Character count is one reason to go with force, I suppose, but I also don't know if force is a good term here. It doesn't align with the general use of --force / -f as a clarg in my mind.

I don't know, force is what we've used and is being used by the koji plugin/other places at the moment so I'm not super enticed to rename it to override everywhere without having a bit more of a compatibility timeline in place :) To me it's a clear term but I can see that names are difficult (force- and extra-).

supakeen requested a review from a team as a code owner December 15, 2025 10:04

supakeen requested review from bcl, mvo5 and thozza and removed request for a team December 15, 2025 10:04

supakeen force-pushed the repo-dir branch from cc219e4 to 85f1e46 Compare December 15, 2025 10:35

supakeen requested a review from achilleas-k December 15, 2025 10:55

lzap reviewed Dec 15, 2025

View reviewed changes

cmd/image-builder/main.go Outdated Show resolved Hide resolved

supakeen force-pushed the repo-dir branch from 85f1e46 to 71c1265 Compare December 15, 2025 12:25

supakeen requested a review from lzap December 15, 2025 12:25

lzap previously approved these changes Dec 15, 2025

View reviewed changes

thozza reviewed Dec 17, 2025

View reviewed changes

thozza previously approved these changes Jan 13, 2026

View reviewed changes

bcl requested a review from thozza January 14, 2026 00:00

supakeen mentioned this pull request Jan 23, 2026

doc: initial repository blurb #379

Draft

supakeen dismissed stale reviews from thozza and lzap via d72ce2f January 27, 2026 09:13

supakeen force-pushed the repo-dir branch from 71c1265 to d72ce2f Compare January 27, 2026 09:13

supakeen force-pushed the repo-dir branch from d72ce2f to be99cb6 Compare January 27, 2026 09:21

supakeen requested a review from lzap January 27, 2026 11:52

lzap approved these changes Jan 29, 2026

View reviewed changes

		@@ -71,8 +71,8 @@ func TestNewRepoRegistryImplDatadir(t *testing.T) {

		// create a custom datadir with testdistro-1.json, the basefilename

		repoDir := t.TempDir()
		repoFile := filepath.Join(repoDir, "repositories", "testdistro-1.json")

many: force-repo-dir instead of force-data-dir #408

Are you sure you want to change the base?

many: force-repo-dir instead of force-data-dir #408

Conversation

supakeen commented Dec 15, 2025

Uh oh!

supakeen commented Dec 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thozza commented Jan 13, 2026

Uh oh!

lzap left a comment

Choose a reason for hiding this comment

Uh oh!

supakeen commented Jan 29, 2026

Uh oh!

achilleas-k commented Jan 29, 2026

Uh oh!

supakeen commented Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

many: `force-repo-dir` instead of `force-data-dir` #408

many: `force-repo-dir` instead of `force-data-dir` #408

supakeen commented Dec 15, 2025 •

edited

Loading

supakeen commented Jan 29, 2026 •

edited

Loading