Added --with-git flag for opt-in dist-git creation

Author: Antonio Salinas

docs/user/reference/cli/azldev_component_build.md

@@ -26,6 +26,7 @@ type ComponentBuildOptions struct {
 
 	ContinueOnError   bool
 	NoCheck           bool
+	WithGitRepo       bool
 	SourcePackageOnly bool
 	BuildEnvPolicy    BuildEnvPreservePolicy
 
@@ -94,6 +95,8 @@ builds can consume.`,
 	cmd.Flags().BoolVarP(&options.ContinueOnError, "continue-on-error", "k", false,
 		"Continue building when some components fail")
 	cmd.Flags().BoolVar(&options.NoCheck, "no-check", false, "Skip package %check tests")
+	cmd.Flags().BoolVar(&options.WithGitRepo, "with-git", false,
+		"Create a dist-git repository with synthetic commit history (requires a project git repository)")
 	cmd.Flags().BoolVar(&options.SourcePackageOnly, "srpm-only", false, "Build SRPM (source RPM) *only*")
 	cmd.Flags().Var(&options.BuildEnvPolicy, "preserve-buildenv",
 		fmt.Sprintf("Preserve build environment {%s, %s, %s}",
@@ -212,7 +215,12 @@ func BuildComponent(
 		return nil
 	}, &err)
 
-	sourcePreparer, err := sources.NewPreparer(sourceManager, env.FS(), env, env)
+	var preparerOpts []sources.PreparerOption
+	if options.WithGitRepo {
+		preparerOpts = append(preparerOpts, sources.WithGitRepo())
+	}
+
+	sourcePreparer, err := sources.NewPreparer(sourceManager, env.FS(), env, env, preparerOpts...)
 	if err != nil {
 		return ComponentBuildResults{},
 			fmt.Errorf("failed to create source preparer for component %q:\n%w", component.GetName(), err)

docs/user/reference/cli/azldev_component_prepare-sources.md

@@ -63,6 +63,7 @@ overlays to the copy and displays the resulting diff between the two trees.`,
 // DiffComponentSources computes the diff between original and overlaid sources for a single component.
 // When color is enabled and the output format is not JSON, the returned value is a pre-colorized
 // string. Otherwise it is [*dirdiff.DiffResult] for structured output.
+
 func DiffComponentSources(env *azldev.Env, options *DiffSourcesOptions) (interface{}, error) {
 	resolver := components.NewResolver(env)
 

internal/app/azldev/cmds/component/build.go

@@ -20,6 +20,7 @@ type PrepareSourcesOptions struct {
 
 	OutputDir    string
 	SkipOverlays bool
+	WithGitRepo  bool
 	Force        bool
 }
 
@@ -65,6 +66,8 @@ Only one component may be selected at a time.`,
 	_ = cmd.MarkFlagDirname("output-dir")
 
 	cmd.Flags().BoolVar(&options.SkipOverlays, "skip-overlays", false, "skip applying overlays to prepared sources")
+	cmd.Flags().BoolVar(&options.WithGitRepo, "with-git", false,
+		"Create a dist-git repository with synthetic commit history (requires a project git repository)")
 	cmd.Flags().BoolVar(&options.Force, "force", false, "delete and recreate the output directory if it already exists")
 
 	return cmd
@@ -114,7 +117,12 @@ func PrepareComponentSources(env *azldev.Env, options *PrepareSourcesOptions) er
 		return err
 	}
 
-	preparer, err := sources.NewPreparer(sourceManager, env.FS(), env, env)
+	var preparerOpts []sources.PreparerOption
+	if options.WithGitRepo {
+		preparerOpts = append(preparerOpts, sources.WithGitRepo())
+	}
+
+	preparer, err := sources.NewPreparer(sourceManager, env.FS(), env, env, preparerOpts...)
 	if err != nil {
 		return fmt.Errorf("failed to create source preparer:\n%w", err)
 	}

internal/app/azldev/cmds/component/diffsources.go

@@ -8,12 +8,15 @@ import (
 	"errors"
 	"fmt"
 	"log/slog"
+	"os"
 	"path/filepath"
 	"slices"
 	"strings"
+	"time"
 	"unicode"
 
 	gogit "github.com/go-git/go-git/v5"
+	"github.com/go-git/go-git/v5/plumbing/object"
 	"github.com/microsoft/azure-linux-dev-tools/internal/app/azldev/core/components"
 	"github.com/microsoft/azure-linux-dev-tools/internal/global/opctx"
 	"github.com/microsoft/azure-linux-dev-tools/internal/projectconfig"
@@ -51,20 +54,40 @@ type SourcePreparer interface {
 	DiffSources(ctx context.Context, component components.Component, baseDir string) (*dirdiff.DiffResult, error)
 }
 
+// PreparerOption is a functional option for configuring a [SourcePreparer].
+type PreparerOption func(*sourcePreparerImpl)
+
+// WithGitRepo returns a [PreparerOption] that enables dist-git repository
+// creation during source preparation. When set, the upstream .git directory
+// is preserved and synthetic commit history is generated on top of it. This
+// requires the project configuration to reside inside a git repository.
+// Without this option, no dist-git is created and synthetic history is skipped.
+func WithGitRepo() PreparerOption {
+	return func(p *sourcePreparerImpl) {
+		p.withGitRepo = true
+	}
+}
+
 // Standard implementation of the [SourcePreparer] interface.
 type sourcePreparerImpl struct {
 	sourceManager sourceproviders.SourceManager
 	fs            opctx.FS
 	eventListener opctx.EventListener
 	dryRunnable   opctx.DryRunnable
+
+	// withGitRepo, when true, enables dist-git creation by preserving the
+	// upstream .git directory and generating synthetic commit history.
+	withGitRepo bool
 }
 
-// NewPreparer creates a new [SourcePreparer] instance. All arguments are required.
+// NewPreparer creates a new [SourcePreparer] instance. All positional arguments
+// are required. Optional behavior can be configured via [PreparerOption] values.
 func NewPreparer(
 	sourceManager sourceproviders.SourceManager,
 	fs opctx.FS,
 	eventListener opctx.EventListener,
 	dryRunnable opctx.DryRunnable,
+	opts ...PreparerOption,
 ) (SourcePreparer, error) {
 	if sourceManager == nil {
 		return nil, errors.New("source manager cannot be nil")
@@ -89,6 +112,12 @@ func NewPreparer(
 		dryRunnable:   dryRunnable,
 	}
 
+	for _, opt := range opts {
+		if opt != nil {
+			opt(impl)
+		}
+	}
+
 	return impl, nil
 }
 
@@ -103,11 +132,11 @@ func (p *sourcePreparerImpl) PrepareSources(
 			component.GetName(), err)
 	}
 
-	// Preserve the upstream .git directory when overlays will be applied. This is
-	// required so that overlay commits can be appended on top of the upstream commit
-	// log during synthetic history generation.
+	// Preserve the upstream .git directory only when dist-git creation is
+	// requested via --with-git. This is required so that overlay commits can be
+	// appended on top of the upstream commit log during synthetic history generation.
 	var fetchOpts []sourceproviders.FetchComponentOption
-	if applyOverlays {
+	if applyOverlays && p.withGitRepo {
 		fetchOpts = append(fetchOpts, sourceproviders.WithPreserveGitDir())
 	}
 
@@ -122,11 +151,22 @@ func (p *sourcePreparerImpl) PrepareSources(
 		return nil
 	}
 
-	return p.applyOverlaysToSources(ctx, component, outputDir)
+	if err := p.applyOverlaysToSources(ctx, component, outputDir); err != nil {
+		return err
+	}
+
+	// Record the changes as synthetic git history when dist-git creation is enabled.
+	if p.withGitRepo {
+		if err := p.trySyntheticHistory(component, outputDir); err != nil {
+			return fmt.Errorf("failed to generate synthetic history for component %#q:\n%w",
+				component.GetName(), err)
+		}
+	}
+
+	return nil
 }
 
-// applyOverlaysToSources writes the macros file and then applies all overlays and
-// records synthetic git history.
+// applyOverlaysToSources writes the macros file and then applies all overlays.
 func (p *sourcePreparerImpl) applyOverlaysToSources(
 	ctx context.Context, component components.Component, outputDir string,
 ) error {
@@ -145,23 +185,19 @@ func (p *sourcePreparerImpl) applyOverlaysToSources(
 		macrosFileName = filepath.Base(macrosFilePath)
 	}
 
-	// Apply all overlays and record synthetic git history.
-	err = p.applyOverlaysWithHistory(ctx, component, outputDir, macrosFileName)
-	if err != nil {
+	// Apply all overlays to prepared sources.
+	if err := p.applyOverlays(ctx, component, outputDir, macrosFileName); err != nil {
 		return fmt.Errorf("failed to apply overlays for component %#q:\n%w", component.GetName(), err)
 	}
 
 	return nil
 }
 
-// applyOverlaysWithHistory applies all overlays (user-defined and system-generated) to the
-// component sources, then attempts to record the changes as synthetic git history.
-//
-// Overlay application is fully decoupled from git history generation: overlays are always
-// applied first, then the changes are optionally committed. If the sources directory does
-// not contain a git repository (e.g. local or unspecified spec sources), overlays are still
-// applied but no synthetic history is created.
-func (p *sourcePreparerImpl) applyOverlaysWithHistory(
+// applyOverlays applies all overlays (user-defined and system-generated) to the
+// component sources. Overlay application is decoupled from git history generation:
+// overlays modify the working tree; synthetic history is recorded separately by
+// [trySyntheticHistory].
+func (p *sourcePreparerImpl) applyOverlays(
 	_ context.Context, component components.Component, sourcesDirPath, macrosFileName string,
 ) error {
 	event := p.eventListener.StartEvent("Applying overlays", "component", component.GetName())
@@ -175,7 +211,10 @@ func (p *sourcePreparerImpl) applyOverlaysWithHistory(
 
 	// Collect all overlays in application order. This ensures every change is
 	// captured in the synthetic history, including build configuration changes.
-	allOverlays := p.collectOverlays(component, macrosFileName)
+	allOverlays, err := p.collectOverlays(component, macrosFileName)
+	if err != nil {
+		return fmt.Errorf("failed to collect overlays for component %#q:\n%w", component.GetName(), err)
+	}
 
 	if len(allOverlays) == 0 {
 		return nil
@@ -186,21 +225,14 @@ func (p *sourcePreparerImpl) applyOverlaysWithHistory(
 		return fmt.Errorf("failed to apply overlays for component %#q:\n%w", component.GetName(), err)
 	}
 
-	// Record the changes as synthetic git history. This is required for rpmautospec
-	// release numbering and delta builds, so failure here is fatal.
-	if err := p.trySyntheticHistory(component, sourcesDirPath); err != nil {
-		return fmt.Errorf("failed to generate synthetic history for component %#q:\n%w",
-			component.GetName(), err)
-	}
-
 	return nil
 }
 
 // collectOverlays gathers all overlays for a component into a single ordered slice:
-// component overlays first, followed by macros-load, check-skip, and file-header overlays.
+// user overlays first, followed by macros-load, check-skip, and file-header overlays.
 func (p *sourcePreparerImpl) collectOverlays(
 	component components.Component, macrosFileName string,
-) []projectconfig.ComponentOverlay {
+) ([]projectconfig.ComponentOverlay, error) {
 	config := component.GetConfig()
 
 	var allOverlays []projectconfig.ComponentOverlay
@@ -210,10 +242,7 @@ func (p *sourcePreparerImpl) collectOverlays(
 	if macrosFileName != "" {
 		macroOverlays, err := synthesizeMacroLoadOverlays(macrosFileName)
 		if err != nil {
-			slog.Error("Failed to compute macros load overlays",
-				"component", component.GetName(), "error", err)
-
-			panic(fmt.Sprintf("failed to compute macros load overlays for component %q: %v", component.GetName(), err))
+			return nil, fmt.Errorf("failed to compute macros load overlays:\n%w", err)
 		}
 
 		allOverlays = append(allOverlays, macroOverlays...)
@@ -222,38 +251,57 @@ func (p *sourcePreparerImpl) collectOverlays(
 	allOverlays = append(allOverlays, synthesizeCheckSkipOverlays(config.Build.Check)...)
 	allOverlays = append(allOverlays, generateFileHeaderOverlay()...)
 
-	return allOverlays
+	return allOverlays, nil
 }
 
-// trySyntheticHistory attempts to create synthetic git commits on top of the upstream
-// repository. All file changes must already be present in the working tree before calling
-// this function — it only handles staging and committing.
-//
-// Returns nil when there is no .git directory (legitimate for local/unspecified specs).
-// Returns a non-nil error if a .git directory exists but history generation fails.
-func (p *sourcePreparerImpl) trySyntheticHistory(
-	component components.Component,
-	sourcesDirPath string,
-) error {
-	// Check for an upstream git repository in the sources directory. Local and
-	// unspecified spec sources won't have a .git directory — that's expected.
-	gitDirPath := filepath.Join(sourcesDirPath, ".git")
+// initSourcesRepo initializes a new git repository in sourcesDirPath, stages all files,
+// and creates an initial commit. This is used for components that don't have an upstream
+// dist-git so that Affects commits can still be layered on top.
+func initSourcesRepo(sourcesDirPath string) (*gogit.Repository, error) {
+	slog.Info("Initializing git repository for sources", "path", sourcesDirPath)
 
-	hasGitDir, err := fileutils.Exists(p.fs, gitDirPath)
+	repo, err := gogit.PlainInit(sourcesDirPath, false)
 	if err != nil {
-		return fmt.Errorf("failed to check for .git directory at %#q:\n%w", gitDirPath, err)
+		return nil, fmt.Errorf("failed to initialize git repository at %#q:\n%w", sourcesDirPath, err)
 	}
 
-	if !hasGitDir {
-		slog.Debug("No .git directory in sources; skipping synthetic history",
-			"component", component.GetName())
+	worktree, err := repo.Worktree()
+	if err != nil {
+		return nil, fmt.Errorf("failed to get worktree:\n%w", err)
+	}
 
-		return nil
+	if err := worktree.AddWithOptions(&gogit.AddOptions{All: true}); err != nil {
+		return nil, fmt.Errorf("failed to stage files:\n%w", err)
+	}
+
+	_, err = worktree.Commit("Initial sources", &gogit.CommitOptions{
+		Author: &object.Signature{
+			Name:  "azldev",
+			Email: "azldev@microsoft.com",
+			When:  time.Unix(0, 0).UTC(),
+		},
+	})
+	if err != nil {
+		return nil, fmt.Errorf("failed to create initial commit:\n%w", err)
 	}
 
+	return repo, nil
+}
+
+// trySyntheticHistory attempts to create synthetic git commits on top of the
+// component's sources directory. If no .git directory exists, one is initialized
+// with an initial commit so Affects commits can be layered on uniformly for all
+// component types.
+//
+// Returns nil when there are no Affects commits to apply.
+// Returns a non-nil error if history generation fails.
+func (p *sourcePreparerImpl) trySyntheticHistory(
+	component components.Component,
+	sourcesDirPath string,
+) error {
 	config := component.GetConfig()
 
-	// Build commit metadata from Affects commits and dirty state.
+	// Build commit metadata from Affects commits.
 	commits, err := buildSyntheticCommits(config, component.GetName())
 	if err != nil {
 		return fmt.Errorf("failed to build synthetic commits:\n%w", err)
@@ -266,10 +314,31 @@ func (p *sourcePreparerImpl) trySyntheticHistory(
 		return nil
 	}
 
-	// Open the upstream git repository where synthetic commits will be recorded.
+	// Check for an existing git repository in the sources directory.
+	// Use os.Stat rather than p.fs because go-git's PlainInit/PlainOpen always
+	// operate on the real OS filesystem — the check must use the same source of
+	// truth to avoid disagreement when p.fs is an in-memory FS (e.g. unit tests).
+	gitDirPath := filepath.Join(sourcesDirPath, ".git")
+
+	_, statErr := os.Stat(gitDirPath)
+
+	if statErr != nil && !os.IsNotExist(statErr) {
+		return fmt.Errorf("failed to check for .git directory at %#q:\n%w", gitDirPath, statErr)
+	}
+
+	if os.IsNotExist(statErr) {
+		slog.Info("No .git directory in sources; initializing repository",
+			"component", component.GetName())
+
+		if _, err := initSourcesRepo(sourcesDirPath); err != nil {
+			return fmt.Errorf("failed to initialize sources repository:\n%w", err)
+		}
+	}
+
+	// Open the git repository where synthetic commits will be recorded.
 	sourcesRepo, err := gogit.PlainOpen(sourcesDirPath)
 	if err != nil {
-		return fmt.Errorf("failed to open upstream repository at %#q:\n%w", sourcesDirPath, err)
+		return fmt.Errorf("failed to open sources repository at %#q:\n%w", sourcesDirPath, err)
 	}
 
 	if err := CommitSyntheticHistory(sourcesRepo, commits); err != nil {