chore: Add fast-copy strict control (#5966)

* feat: Adding `fast-copy` strict control

* feat: Adding in `fastwalk` and `WalkDirParallel` in `vfs`

* chore: Use options pattern over long parameter list

* fix: Addressing lint findings

* docs: Docs update

* fix: Adding symlink following

* fix: Fixing usage of `CopyFolderContents`

* docs: Reverting change to `mark-many-as-read` experiment

* docs: Documenting `fast-copy` in changelog

* fix: Addressing review notes

* fix: Addressing review feedback

Author: yhakbar

docs/src/data/changelog/v1.0.4/fast-copy-strict-control.mdx

@@ -0,0 +1,14 @@
+---
+version: "v1.0.4"
+category: "performance-improvements"
+---
+
+#### `fast-copy` strict control
+
+With the new [`fast-copy`](/reference/strict-controls/active#fast-copy) strict control enabled, Terragrunt compiles each `include_in_copy` and `exclude_from_copy` pattern once and evaluates it inline during a single copy walk. This avoids re-walking subdirectories for every pattern, which should result in noticeable speed improvements for large source modules.
+
+```bash
+terragrunt run plan --strict-control fast-copy
+```
+
+The new matcher does not collapse `**` to zero path segments when a neighbor is a wildcard, so `a/**/*.tf` matches `a/sub/main.tf` but not `a/main.tf`. Patterns that relied on the old collapsing behavior should use brace alternation like `{*.tf,**/*.tf}` to cover both depths.

docs/src/data/strict-controls/fast-copy.mdx

@@ -0,0 +1,13 @@
+---
+name: fast-copy
+status: active
+since: "1.0.4"
+---
+
+Switches `include_in_copy` and `exclude_from_copy` pattern matching from [zglob](https://pkg.go.dev/github.com/mattn/go-zglob) to [gobwas/glob](https://pkg.go.dev/github.com/gobwas/glob) when Terragrunt copies a module's source folder.
+
+### `fast-copy` - Reason
+
+The default implementation runs zglob once per pattern and recursively re-expands every directory match, which can dominate copy time on large module sources. gobwas compiles each pattern once and matches inline during the existing copy walk.
+
+gobwas does not collapse `**` when a neighbor is a wildcard, so `a/**/*.tf` matches `a/sub/main.tf` but not `a/main.tf`. Patterns that depended on zero-depth `**` collapsing need brace alternation like `{*.tf,**/*.tf}` to cover both depths.

go.mod

@@ -85,6 +85,7 @@ require (
 	github.com/aws/aws-sdk-go-v2/service/s3 v1.99.0
 	github.com/aws/aws-sdk-go-v2/service/sts v1.41.10
 	github.com/aws/smithy-go v1.24.3
+	github.com/charlievieth/fastwalk v1.0.14
 	github.com/charmbracelet/colorprofile v0.4.2
 	github.com/charmbracelet/x/ansi v0.11.6
 	github.com/charmbracelet/x/term v0.2.2

go.sum

@@ -279,6 +279,8 @@ github.com/cenkalti/backoff/v5 v5.0.3/go.mod h1:rkhZdG3JZukswDf7f0cwqPNk4K0sa+F9
 github.com/census-instrumentation/opencensus-proto v0.2.1/go.mod h1:f6KPmirojxKA12rnyqOA5BBL4O983OfeGPqjHWSTneU=
 github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
 github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/charlievieth/fastwalk v1.0.14 h1:3Eh5uaFGwHZd8EGwTjJnSpBkfwfsak9h6ICgnWlhAyg=
+github.com/charlievieth/fastwalk v1.0.14/go.mod h1:diVcUreiU1aQ4/Wu3NbxxH4/KYdKpLDojrQ1Bb2KgNY=
 github.com/charmbracelet/colorprofile v0.4.2 h1:BdSNuMjRbotnxHSfxy+PCSa4xAmz7szw70ktAtWRYrY=
 github.com/charmbracelet/colorprofile v0.4.2/go.mod h1:0rTi81QpwDElInthtrQ6Ni7cG0sDtwAd4C4le060fT8=
 github.com/charmbracelet/ultraviolet v0.0.0-20260205113103-524a6607adb8 h1:eyFRbAmexyt43hVfeyBofiGSEmJ7krjLOYt/9CF5NKA=

internal/glob/glob.go

@@ -14,8 +14,8 @@
 // literals. With literals on both sides, "a/**/b" matches "a/b" as well as
 // "a/x/b". If either neighbor is a wildcard (for example "a/**/*.tf" or
 // "*/**/b.tf"), "**" does not collapse and a zero-depth match fails. Use
-// brace alternation — for example "{*.tf,**/*.tf}" — to cover both depths
-// when the trailing segment contains a wildcard.
+// brace alternation like "{*.tf,**/*.tf}" to cover both depths when the
+// trailing segment contains a wildcard.
 //
 // # When to use what
 //

internal/runner/run/download_source.go

@@ -96,14 +96,15 @@ func DownloadTerraformSource(
 		// Always include the .tflint.hcl file, if it exists
 		includeInCopy := slices.Concat(cfg.Terraform.IncludeInCopy, []string{tfLintConfig})
 
-		err = util.CopyFolderContents(
-			l,
-			opts.WorkingDir,
-			terraformSource.WorkingDir,
-			ModuleManifestName,
-			includeInCopy,
-			cfg.Terraform.ExcludeFromCopy,
-		)
+		copyOpts := []util.CopyOption{
+			util.WithIncludeInCopy(includeInCopy...),
+			util.WithExcludeFromCopy(cfg.Terraform.ExcludeFromCopy...),
+		}
+		if isFastCopyEnabled(opts.StrictControls) {
+			copyOpts = append(copyOpts, util.WithFastCopy())
+		}
+
+		err = util.CopyFolderContents(l, opts.WorkingDir, terraformSource.WorkingDir, ModuleManifestName, copyOpts...)
 		if err != nil {
 			return nil, err
 		}
@@ -316,6 +317,7 @@ func UpdateGetters(l log.Logger, opts *Options, cfg *runcfg.RunConfig) func(*get
 			Logger:          l,
 			IncludeInCopy:   cfg.Terraform.IncludeInCopy,
 			ExcludeFromCopy: cfg.Terraform.ExcludeFromCopy,
+			FastCopy:        isFastCopyEnabled(opts.StrictControls),
 		}
 		client.Getters["http"] = &getter.HttpGetter{Netrc: true}
 		client.Getters["https"] = &getter.HttpGetter{Netrc: true}

internal/runner/run/download_source_test.go

@@ -566,8 +566,6 @@ func copyFolder(t *testing.T, src string, dest string) {
 		filepath.FromSlash(src),
 		filepath.FromSlash(dest),
 		".terragrunt-test",
-		nil,
-		nil,
 	)
 	require.NoError(t, err)
 }

internal/runner/run/file_copy_getter.go

@@ -5,11 +5,18 @@ import (
 	"os"
 
 	"github.com/gruntwork-io/terragrunt/internal/errors"
+	"github.com/gruntwork-io/terragrunt/internal/strict"
+	"github.com/gruntwork-io/terragrunt/internal/strict/controls"
 	"github.com/gruntwork-io/terragrunt/internal/util"
 	"github.com/gruntwork-io/terragrunt/pkg/log"
 	"github.com/hashicorp/go-getter"
 )
 
+// isFastCopyEnabled reports whether the `fast-copy` strict control is enabled.
+func isFastCopyEnabled(strictControls strict.Controls) bool {
+	return len(strictControls.FilterByNames(controls.FastCopy).FilterByEnabled()) > 0
+}
+
 // SourceManifestName is the manifest for files copied from the URL specified in the terraform { source = "<URL>" } config
 const SourceManifestName = ".terragrunt-source-manifest"
 
@@ -24,6 +31,11 @@ type FileCopyGetter struct {
 	// Terragrunt, which will skip hidden folders.
 	IncludeInCopy   []string
 	ExcludeFromCopy []string
+
+	// FastCopy routes the [util.CopyFolderContents] call through the
+	// fast-copy path. Set at construction time from the `fast-copy`
+	// strict control.
+	FastCopy bool
 }
 
 // Get replaces the original FileGetter
@@ -42,7 +54,15 @@ func (g *FileCopyGetter) Get(dst string, u *url.URL) error {
 		return errors.Errorf("source path must be a directory")
 	}
 
-	return util.CopyFolderContents(g.Logger, path, dst, SourceManifestName, g.IncludeInCopy, g.ExcludeFromCopy)
+	copyOpts := []util.CopyOption{
+		util.WithIncludeInCopy(g.IncludeInCopy...),
+		util.WithExcludeFromCopy(g.ExcludeFromCopy...),
+	}
+	if g.FastCopy {
+		copyOpts = append(copyOpts, util.WithFastCopy())
+	}
+
+	return util.CopyFolderContents(g.Logger, path, dst, SourceManifestName, copyOpts...)
 }
 
 // GetFile The original FileGetter already knows how to do file copying so long as we set the Copy flag to true, so just

internal/strict/controls/controls.go

@@ -79,6 +79,10 @@ const (
 
 	// DisableDependentModules is the control that prevents the use of the deprecated `--disable-dependent-modules` flag.
 	DisableDependentModules = "disable-dependent-modules"
+
+	// FastCopy is the control that switches `include_in_copy` and
+	// `exclude_from_copy` pattern matching from zglob to gobwas.
+	FastCopy = "fast-copy"
 )
 
 //nolint:lll
@@ -290,6 +294,11 @@ func New() strict.Controls {
 			Error:       errors.New("The `--disable-dependent-modules` flag is no longer supported. Dependent modules discovery has been removed from `terragrunt render`."),
 			Warning:     "The `--disable-dependent-modules` flag is deprecated and will be removed in a future version of Terragrunt. Dependent modules discovery has been removed from `terragrunt render`, so this flag has no effect.",
 		},
+		&Control{
+			Name:        FastCopy,
+			Description: "Switches `include_in_copy` and `exclude_from_copy` pattern matching from zglob to gobwas. `**` no longer collapses when adjacent to a wildcard, so `a/**/*.tf` will not match `a/foo.tf`. Use brace alternation like `{*.tf,**/*.tf}` to cover both depths.",
+			Category:    stageCategory,
+		},
 	}
 
 	return controls.Sort()