docs: Docs update

Author: yhakbar

docs/src/data/changelog/v1.0.3/mark-many-as-read.mdx

@@ -3,7 +3,7 @@ version: "v1.0.3"
 category: "experiments-added"
 ---
 
-#### `mark-many-as-read` — Mark many files as read in one step
+#### `mark-many-as-read`: mark many files as read in one step
 
 Enable the new [`mark-many-as-read`](/reference/experiments) experiment to turn on two behaviors that each mark many files as read in a single call: automatic marking of files inside a local `terraform { source = "..." }` block, and the new `mark_glob_as_read` HCL function.
 

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

@@ -3,12 +3,10 @@ name: fast-copy
 status: active
 ---
 
-Use a compile-once, single-walk implementation for `include_in_copy` and `exclude_from_copy` expansion when Terragrunt copies a module's source folder. Faster on large module sources because the walk no longer pre-expands every pattern in a separate pass per nested directory.
+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
 
-`include_in_copy` and `exclude_from_copy` patterns have historically been expanded with [zglob](https://pkg.go.dev/github.com/mattn/go-zglob), once per pattern, with directory matches recursively re-expanded. On large source trees the pre-expansion can dominate the cost of the copy itself.
+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.
 
-Enabling `fast-copy` switches pattern matching to [gobwas/glob](https://pkg.go.dev/github.com/gobwas/glob), compiles each pattern once, and evaluates matches inline during the existing copy walk.
-
-The semantics differ from zglob in one place worth knowing: gobwas does not collapse `**` when one of its neighbors is a wildcard. For example, `a/**/*.tf` matches `a/sub/main.tf` but not `a/main.tf`. Patterns that depended on zero-depth `**` collapsing should use brace alternation, for example `{*.tf,**/*.tf}`, to cover both depths.
+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.

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/file_copy_getter.go

@@ -32,9 +32,9 @@ type FileCopyGetter struct {
 	IncludeInCopy   []string
 	ExcludeFromCopy []string
 
-	// FastCopy opts the underlying [util.CopyFolderContents] call into the
-	// compile-once, single-walk implementation. Set via the `fast-copy`
-	// strict control at construction time.
+	// FastCopy routes the [util.CopyFolderContents] call through the
+	// fast-copy path. Set at construction time from the `fast-copy`
+	// strict control.
 	FastCopy bool
 }
 

internal/strict/controls/controls.go

@@ -80,10 +80,8 @@ const (
 	// DisableDependentModules is the control that prevents the use of the deprecated `--disable-dependent-modules` flag.
 	DisableDependentModules = "disable-dependent-modules"
 
-	// FastCopy opts into a compile-once, single-walk implementation of
-	// `include_in_copy` / `exclude_from_copy` expansion in
-	// `util.CopyFolderContents`. Faster on large module sources, but
-	// switches pattern matching from zglob to gobwas semantics.
+	// FastCopy is the control that switches `include_in_copy` and
+	// `exclude_from_copy` pattern matching from zglob to gobwas.
 	FastCopy = "fast-copy"
 )
 
@@ -298,7 +296,7 @@ func New() strict.Controls {
 		},
 		&Control{
 			Name:        FastCopy,
-			Description: "Switches `include_in_copy` / `exclude_from_copy` expansion in `util.CopyFolderContents` to a compile-once, single-walk implementation. Pattern matching moves from zglob to gobwas semantics, so `**` no longer collapses when adjacent to a wildcard (for example `a/**/*.tf` will not match `a/foo.tf`). Use brace alternation such as `{*.tf,**/*.tf}` to cover both depths.",
+			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,
 		},
 	}

internal/util/file.go

@@ -112,7 +112,7 @@ func CanonicalResolvedPath(path, basePath string) (string, error) {
 
 // GrepFilesWithSuffix returns true if regex matches the contents of any file
 // under rootDir whose name ends with suffix. The walk stops as soon as a match
-// is found. A missing rootDir is not an error — the function returns false.
+// is found. A missing rootDir is not an error; the function returns false.
 func GrepFilesWithSuffix(fsys vfs.FS, regex *regexp.Regexp, rootDir, suffix string) (bool, error) {
 	var found bool
 
@@ -449,10 +449,10 @@ func CopyFolderContents(l log.Logger, source, destination, manifestFile string,
 	})
 }
 
-// copyFolderContentsFast is the compile-once, single-walk path for
-// [CopyFolderContents]. See the `fast-copy` strict control. The walk
-// itself runs via [fastwalk.Walk] so directory reads and filter checks
-// proceed in parallel.
+// copyFolderContentsFast is the [CopyFolderContents] path used when the
+// `fast-copy` strict control is enabled. Include and exclude patterns
+// are compiled once and the source tree is walked once through
+// [vfs.WalkDirParallel].
 func copyFolderContentsFast(
 	l log.Logger,
 	source,
@@ -491,9 +491,8 @@ func copyFolderContentsFast(
 		}
 	}()
 
-	// fastwalk runs walkFn concurrently across workers; the gob-encoded
-	// manifest is not safe for concurrent writes, so every AddFile is
-	// guarded by this mutex.
+	// The walk is parallel. The gob-encoded manifest is not safe for
+	// concurrent writes, so AddFile is guarded.
 	var manifestMu sync.Mutex
 
 	walkFn := func(absolutePath string, d fs.DirEntry, walkErr error) error {
@@ -514,9 +513,8 @@ func copyFolderContentsFast(
 
 		isDir := d.IsDir()
 
-		// Preserve the cache-dir skip that expandGlobPath enforced at
-		// expansion time. Must run before include matching — otherwise a
-		// user include like "**" would pull .terragrunt-cache back in.
+		// Skip .terragrunt-cache before include matching. A user
+		// include like "**" would otherwise pull it back in.
 		if strings.Contains(rel, TerragruntCacheDir) {
 			if isDir {
 				return fs.SkipDir
@@ -536,9 +534,9 @@ func copyFolderContentsFast(
 		included := include.matches(rel)
 
 		if !included && TerragruntExcludes(filepath.FromSlash(rel)) {
-			// Mirror the legacy ancestor pass: a directory on the path
-			// toward a potential include match must still be descended
-			// into, even when TerragruntExcludes would reject it.
+			// A directory on the way to a potential include match must
+			// still be descended into even when TerragruntExcludes
+			// would reject it.
 			if isDir && include.isAncestor(rel) {
 				return nil
 			}
@@ -558,9 +556,9 @@ func copyFolderContentsFast(
 				return errors.New(err)
 			}
 
-			// MkdirAll may already have created `dest` with default perms
-			// from a sibling file-copy worker racing ahead. Chmod
-			// normalizes the directory to the source's mode.
+			// A sibling file-copy worker may have created `dest`
+			// already with default perms. Chmod forces the source's
+			// mode.
 			if err := os.MkdirAll(dest, info.Mode().Perm()); err != nil {
 				return errors.New(err)
 			}
@@ -594,24 +592,22 @@ func copyFolderContentsFast(
 	return nil
 }
 
-// includePatterns holds the compiled include matcher plus a cheap
-// "is rel an ancestor of any potential match" predicate. Ancestor
-// acceptance is what makes the walk descend through dot-prefixed parents
-// like `_module/.region3` to reach an include hidden underneath.
+// includePatterns holds the compiled include matcher and an ancestor
+// predicate. The predicate lets the walk descend through dot-prefixed
+// parents like `_module/.region3` to reach an include below.
 type includePatterns struct {
-	// match is a single combined matcher built by OR-ing every user
-	// pattern as `{<p>,<p>/**}` inside one brace alternation. One
-	// `Match` call per entry replaces N per-pattern checks.
+	// match is a single matcher that OR-s every user pattern as
+	// `{<p>,<p>/**}` so one Match call per entry covers all of them.
 	match glob.Matcher
 
-	// ancestor is a combined matcher over the strict path prefixes of
-	// each pattern that does not contain `**`. A rel matching this is a
-	// directory on the way to a potential include match.
+	// ancestor matches the path prefixes of every pattern that does
+	// not contain `**`. A rel that matches is a directory on the way
+	// to a potential include match.
 	ancestor glob.Matcher
 
-	// descendAny is true if any pattern contains a `**` segment — in that
-	// case any directory could be on the path to a match, so accept all
-	// non-excluded paths as ancestors regardless of `ancestor`.
+	// descendAny is true when any pattern contains a `**` segment. In
+	// that case every directory is a possible ancestor, so `ancestor`
+	// is not consulted.
 	descendAny bool
 }
 
@@ -631,11 +627,10 @@ func (p includePatterns) isAncestor(rel string) bool {
 	return p.ancestor != nil && p.ancestor.Match(rel)
 }
 
-// compileIncludePatterns compiles user `include_in_copy` patterns into one
-// combined matcher that covers each pattern and all its descendants — so a
-// match behaves like the recursive expansion in [expandGlobPath] — plus an
-// ancestor matcher that flags directories on the path toward a potential
-// match.
+// compileIncludePatterns compiles user `include_in_copy` patterns into
+// one combined matcher that covers each pattern and all its descendants,
+// reproducing the recursive expansion in [expandGlobPath], plus an
+// ancestor matcher for directories on the path toward a potential match.
 func compileIncludePatterns(patterns []string) (includePatterns, error) {
 	out := includePatterns{}
 

internal/util/file_test.go

@@ -761,14 +761,14 @@ func TestRelPathForLog(t *testing.T) {
 	}
 }
 
-// buildCopyBenchTree lays out a synthetic module source with `topDirs`
-// top-level directories. Each top-level dir gets a deeply nested chain
-// (`chainDepth` levels) with `filesPerLevel` files at every level, so a
-// bare-directory include pattern like the top-level name triggers the
-// legacy expandGlobPath recursion once per nested directory.
+// buildCopyBenchTree lays out a synthetic module source: topDirs
+// top-level directories, each a chain chainDepth levels deep with
+// filesPerLevel files at every level. A bare-directory include pattern
+// like the top-level name triggers the legacy expandGlobPath recursion
+// once per nested directory.
 //
-// Returns the tree root and the list of top-level directory names, which
-// become the include-in-copy patterns fed to the benchmark.
+// Returns the tree root and the top-level directory names, which the
+// benchmark uses as include patterns.
 func buildCopyBenchTree(b *testing.B, topDirs, chainDepth, filesPerLevel int) (string, []string) {
 	b.Helper()
 
@@ -783,29 +783,20 @@ func buildCopyBenchTree(b *testing.B, topDirs, chainDepth, filesPerLevel int) (s
 		current := filepath.Join(root, name)
 
 		for depth := range chainDepth {
-			if err := os.MkdirAll(current, 0o755); err != nil {
-				b.Fatalf("mkdir: %v", err)
-			}
+			require.NoError(b, os.MkdirAll(current, 0o755))
 
 			for f := range filesPerLevel {
 				p := filepath.Join(current, fmt.Sprintf("f%02d.tf", f))
-				if err := os.WriteFile(p, content, 0o644); err != nil {
-					b.Fatalf("write: %v", err)
-				}
+				require.NoError(b, os.WriteFile(p, content, 0o644))
 			}
 
 			current = filepath.Join(current, fmt.Sprintf("level%02d", depth))
 		}
 	}
 
 	cache := filepath.Join(root, util.TerragruntCacheDir, "should-be-skipped")
-	if err := os.MkdirAll(cache, 0o755); err != nil {
-		b.Fatalf("mkdir cache: %v", err)
-	}
-
-	if err := os.WriteFile(filepath.Join(cache, "skip.tf"), content, 0o644); err != nil {
-		b.Fatalf("write cache file: %v", err)
-	}
+	require.NoError(b, os.MkdirAll(cache, 0o755))
+	require.NoError(b, os.WriteFile(filepath.Join(cache, "skip.tf"), content, 0o644))
 
 	return root, names
 }

internal/util/grep_test.go

@@ -47,7 +47,7 @@ func TestGrepFilesWithSuffix(t *testing.T) {
 		{
 			name: "no match when suffix differs",
 			files: map[string]string{
-				// .tf, not .tf.json — must be skipped.
+				// .tf, not .tf.json, must be skipped.
 				"/mod/backend.tf": `terraform { backend "s3" {} }`,
 			},
 			root:   "/mod",

internal/vfs/vfs.go

@@ -147,18 +147,15 @@ func TryLock(fs FS, name string) (Unlocker, bool, error) {
 	return locker.TryLock(name)
 }
 
-// WalkDirParallel walks the file tree rooted at root the same way
-// [WalkDir] does, but reads directories in parallel on filesystems where
-// that is safe. On a [NewOSFS] filesystem the walk is driven by
-// [fastwalk.Walk]; on any other FS (for example [NewMemMapFS]) it
-// transparently degrades to the sequential [WalkDir].
+// WalkDirParallel walks the file tree rooted at root like [WalkDir]
+// does. On a [NewOSFS] filesystem it reads directories in parallel via
+// [fastwalk.Walk]. On any other FS, including [NewMemMapFS], it falls
+// back to the sequential [WalkDir].
 //
-// Unlike [WalkDir], the parallel walk does not guarantee any ordering
-// across directories — fn may be called concurrently from multiple
-// goroutines. Callers that care about deterministic order, or that write
-// to shared state from fn, must use [WalkDir] or serialize access
-// themselves. [fs.SkipDir] and [fs.SkipAll] continue to work as with the
-// sequential walk.
+// The parallel walk calls fn concurrently from multiple goroutines and
+// gives no ordering guarantee across directories. Callers that depend
+// on deterministic order, or that write to shared state from fn, must
+// use [WalkDir] or serialize access themselves.
 func WalkDirParallel(fsys FS, root string, fn fs.WalkDirFunc) error {
 	if _, ok := fsys.(*osFS); !ok {
 		return WalkDir(fsys, root, fn)