feat: Adding mutable attribute for clones to force copy instead of hard links

Author: yhakbar

docs/src/content/docs/03-features/02-stacks/03-explicit.mdx

@@ -412,6 +412,8 @@ When `update_source_with_cas = true` is set:
 
 Consumers do not set `update_source_with_cas` themselves. When the `cas` experiment is enabled and the source is remote, Terragrunt uses the CAS path automatically. The attribute only has effect inside catalog files, where it flags nested `source` attributes for rewriting.
 
+`unit` and `stack` blocks also accept a `mutable` attribute. When `mutable = true`, the unit's or stack's content under `.terragrunt-stack` is copied from the CAS store instead of hardlinked. The default is `false`, which lets CAS hardlink files for speed and deduplication. Set this when you intend to edit files in `.terragrunt-stack` directly: hardlinked files share an inode with the shared store, so editing them in place would corrupt it.
+
 Given the catalog files above, and an ordinary consumer stack like:
 
 ```hcl

docs/src/content/docs/04-reference/01-hcl/02-blocks.mdx

@@ -69,6 +69,13 @@ The `terraform` block supports the following arguments:
 
   *Note that if you wish to exclude files from being copied from a terraform module source, you should use the [before_hook](/features/units/hooks) feature.*
 
+- `mutable` (attribute): When `true`, content fetched into `.terragrunt-cache` is copied from the
+  [content-addressable storage (CAS)](/features/caching/cas) instead of hardlinked. The default is `false`,
+  which lets CAS hardlink files from its shared store for speed and deduplication. Set this to `true` when you
+  intend to edit files inside `.terragrunt-cache` directly: hardlinked files share an inode with the CAS store,
+  so editing them in place would corrupt the store. The flag has no effect when CAS is not used to fetch the
+  source; the standard download path already produces an independent copy.
+
 - `copy_terraform_lock_file` (attribute): In certain use cases, you don't want to check the terraform provider lock
   file into your source repository from your working directory as described in
   [Lock File Handling](/reference/lock-files). This attribute allows you to disable the copy

internal/cas/cas.go

@@ -47,6 +47,11 @@ type CloneOptions struct {
 	// If zero, CAS falls back to its configured clone depth (default shallow depth 1).
 	// Set to -1 for full history (Terragrunt omits --depth; git rejects --depth 0).
 	Depth int
+
+	// Mutable, when true, copies blobs into the target directory instead of
+	// hardlinking them from the CAS store. The destination tree becomes safe
+	// to mutate without corrupting the shared store.
+	Mutable bool
 }
 
 // CAS clones a git repository using content-addressable storage.
@@ -191,7 +196,12 @@ func (c *CAS) Clone(ctx context.Context, l log.Logger, opts *CloneOptions, url s
 			return err
 		}
 
-		return LinkTree(childCtx, c.blobStore, c.treeStore, tree, targetDir)
+		var linkOpts []LinkTreeOption
+		if opts.Mutable {
+			linkOpts = append(linkOpts, WithForceCopy())
+		}
+
+		return LinkTree(childCtx, c.blobStore, c.treeStore, tree, targetDir, linkOpts...)
 	})
 }
 

internal/cas/content.go

@@ -40,49 +40,72 @@ func NewContent(store *Store) *Content {
 	}
 }
 
-// Link creates a hard link from the store to the target path
-func (c *Content) Link(ctx context.Context, hash, targetPath string) error {
+// LinkOption configures a single Content.Link call.
+type LinkOption func(*linkOpts)
+
+type linkOpts struct {
+	forceCopy bool
+}
+
+// WithLinkForceCopy makes Link copy the file from the store into the target
+// path instead of creating a hard link, so the destination is safe to mutate
+// without affecting the shared store.
+func WithLinkForceCopy() LinkOption {
+	return func(o *linkOpts) { o.forceCopy = true }
+}
+
+// Link creates a hard link from the store to the target path. When
+// WithLinkForceCopy is supplied it skips the hard link and copies the file,
+// producing a writable, independent inode at the target.
+func (c *Content) Link(ctx context.Context, hash, targetPath string, opts ...LinkOption) error {
+	var o linkOpts
+	for _, opt := range opts {
+		opt(&o)
+	}
+
 	return telemetry.TelemeterFromContext(ctx).Collect(ctx, "cas_link", map[string]any{
-		"hash": hash,
-		"path": targetPath,
+		"hash":       hash,
+		"path":       targetPath,
+		"force_copy": o.forceCopy,
 	}, func(childCtx context.Context) error {
 		sourcePath := c.getPath(hash)
 
-		// Try to create hard link directly (most efficient path)
-		if err := vfs.Link(c.fs, sourcePath, targetPath); err != nil {
-			// Check if it's because target already exists
-			if os.IsExist(err) {
+		if !o.forceCopy {
+			// Try to create hard link directly (most efficient path)
+			if err := vfs.Link(c.fs, sourcePath, targetPath); err == nil {
+				return nil
+			} else if os.IsExist(err) {
 				// File already exists, which is fine
 				return nil
 			}
+			// Fall through to copy on link failure.
+		}
 
-			// If hard link fails for other reasons, try to copy the file
-			data, readErr := vfs.ReadFile(c.fs, sourcePath)
-			if readErr != nil {
-				return &WrappedError{
-					Op:   "read_source",
-					Path: sourcePath,
-					Err:  ErrReadFile,
-				}
+		data, readErr := vfs.ReadFile(c.fs, sourcePath)
+		if readErr != nil {
+			return &WrappedError{
+				Op:   "read_source",
+				Path: sourcePath,
+				Err:  ErrReadFile,
 			}
+		}
 
-			// Write to temporary file first
-			tempPath := targetPath + ".tmp"
-			if err := vfs.WriteFile(c.fs, tempPath, data, RegularFilePerms); err != nil {
-				return &WrappedError{
-					Op:   "write_target",
-					Path: tempPath,
-					Err:  err,
-				}
+		// Write to temporary file first
+		tempPath := targetPath + ".tmp"
+		if err := vfs.WriteFile(c.fs, tempPath, data, RegularFilePerms); err != nil {
+			return &WrappedError{
+				Op:   "write_target",
+				Path: tempPath,
+				Err:  err,
 			}
+		}
 
-			// Atomic rename to final path
-			if err := c.fs.Rename(tempPath, targetPath); err != nil {
-				return &WrappedError{
-					Op:   "rename_target",
-					Path: tempPath,
-					Err:  err,
-				}
+		// Atomic rename to final path
+		if err := c.fs.Rename(tempPath, targetPath); err != nil {
+			return &WrappedError{
+				Op:   "rename_target",
+				Path: tempPath,
+				Err:  err,
 			}
 		}
 

internal/cas/content_test.go

@@ -155,6 +155,45 @@ func TestContent_Link(t *testing.T) {
 		assert.True(t, os.SameFile(sourceInfo, targetInfo), "expected hard link (same inode)")
 	})
 
+	t.Run("force copy creates independent inode on real filesystem", func(t *testing.T) {
+		t.Parallel()
+
+		osFs := vfs.NewOSFS()
+		storeDir := t.TempDir()
+		targetDir := t.TempDir()
+		store := cas.NewStore(storeDir).WithFS(osFs)
+
+		content := cas.NewContent(store)
+		testHash := testHashValue
+		testData := []byte("test content")
+
+		err := content.Store(l, testHash, testData)
+		require.NoError(t, err)
+
+		targetPath := filepath.Join(targetDir, "test.txt")
+		err = content.Link(t.Context(), testHash, targetPath, cas.WithLinkForceCopy())
+		require.NoError(t, err)
+
+		sourcePath := filepath.Join(storeDir, testHash[:2], testHash)
+		sourceInfo, err := os.Stat(sourcePath)
+		require.NoError(t, err)
+		targetInfo, err := os.Stat(targetPath)
+		require.NoError(t, err)
+		assert.False(t, os.SameFile(sourceInfo, targetInfo), "expected independent inode (copy, not hard link)")
+
+		copied, err := os.ReadFile(targetPath)
+		require.NoError(t, err)
+		assert.Equal(t, testData, copied)
+
+		// The destination must be writable so callers can mutate it without
+		// touching the shared store.
+		require.NoError(t, os.WriteFile(targetPath, []byte("mutated"), 0644))
+
+		stored, err := os.ReadFile(sourcePath)
+		require.NoError(t, err)
+		assert.Equal(t, testData, stored, "store blob must not change when target is mutated")
+	})
+
 	t.Run("link to existing file", func(t *testing.T) {
 		t.Parallel()
 

internal/cas/local.go

@@ -21,7 +21,12 @@ const DefaultLocalHashAlgorithm = HashSHA256
 
 // StoreLocalDirectory persists all content from a local source directory into the CAS
 // and then links the persisted files to the target directory.
-func (c *CAS) StoreLocalDirectory(ctx context.Context, l log.Logger, sourceDir, targetDir string) error {
+func (c *CAS) StoreLocalDirectory(
+	ctx context.Context,
+	l log.Logger,
+	sourceDir, targetDir string,
+	opts ...LinkTreeOption,
+) error {
 	hash, treeData, err := c.buildLocalTree(sourceDir, DefaultLocalHashAlgorithm)
 	if err != nil {
 		return fmt.Errorf("failed to hash local directory %s: %w", sourceDir, err)
@@ -36,7 +41,7 @@ func (c *CAS) StoreLocalDirectory(ctx context.Context, l log.Logger, sourceDir,
 		return fmt.Errorf("failed to parse local tree: %w", err)
 	}
 
-	return LinkTree(ctx, c.blobStore, c.treeStore, tree, targetDir)
+	return LinkTree(ctx, c.blobStore, c.treeStore, tree, targetDir, opts...)
 }
 
 // ComputeLocalRootHash walks dir in deterministic (lexical) order and produces a

internal/cas/protocol.go

@@ -103,7 +103,13 @@ func FormatCASRefWithSubdir(hash, subdir string) string {
 
 // MaterializeTree reads a tree from the CAS store and links its contents to the destination directory.
 // It tries the synth store first, then falls back to the git tree store.
-func (c *CAS) MaterializeTree(ctx context.Context, l log.Logger, hash string, dest string) error {
+func (c *CAS) MaterializeTree(
+	ctx context.Context,
+	l log.Logger,
+	hash string,
+	dest string,
+	opts ...LinkTreeOption,
+) error {
 	var treeData []byte
 
 	var treeStoreUsed *Store
@@ -139,5 +145,5 @@ func (c *CAS) MaterializeTree(ctx context.Context, l log.Logger, hash string, de
 		return fmt.Errorf("failed to parse CAS tree %s: %w", hash, err)
 	}
 
-	return LinkTree(ctx, c.blobStore, treeStoreUsed, tree, dest)
+	return LinkTree(ctx, c.blobStore, treeStoreUsed, tree, dest, opts...)
 }

internal/cas/tree.go

@@ -10,12 +10,43 @@ import (
 	"golang.org/x/sync/errgroup"
 )
 
+// LinkTreeOption configures a LinkTree call.
+type LinkTreeOption func(*linkTreeOpts)
+
+type linkTreeOpts struct {
+	forceCopy bool
+}
+
+// WithForceCopy makes LinkTree copy blobs from the CAS store into the target
+// directory instead of hardlinking them. The destination tree becomes safe to
+// mutate without affecting the shared store, at the cost of extra I/O.
+func WithForceCopy() LinkTreeOption {
+	return func(o *linkTreeOpts) { o.forceCopy = true }
+}
+
 // LinkTree writes the tree to a target directory.
 // blobStore is used to resolve blob entries, treeStore is used to resolve subtree entries.
-func LinkTree(ctx context.Context, blobStore *Store, treeStore *Store, t *git.Tree, targetDir string) error {
+func LinkTree(
+	ctx context.Context,
+	blobStore *Store,
+	treeStore *Store,
+	t *git.Tree,
+	targetDir string,
+	opts ...LinkTreeOption,
+) error {
+	var o linkTreeOpts
+	for _, opt := range opts {
+		opt(&o)
+	}
+
 	blobContent := NewContent(blobStore)
 	treeContent := NewContent(treeStore)
 
+	var linkOpts []LinkOption
+	if o.forceCopy {
+		linkOpts = append(linkOpts, WithLinkForceCopy())
+	}
+
 	dirsToCreate := make(map[string]struct{}, len(t.Entries()))
 
 	type workItem struct {
@@ -79,7 +110,7 @@ func LinkTree(ctx context.Context, blobStore *Store, treeStore *Store, t *git.Tr
 		g.Go(func() error {
 			switch work.itemType {
 			case "link":
-				err := blobContent.Link(ctx, work.entry.Hash, work.path)
+				err := blobContent.Link(ctx, work.entry.Hash, work.path, linkOpts...)
 				if err != nil {
 					return fmt.Errorf("link blob %s: %w", work.path, err)
 				}
@@ -94,7 +125,7 @@ func LinkTree(ctx context.Context, blobStore *Store, treeStore *Store, t *git.Tr
 					return fmt.Errorf("parse tree %s: %w", work.entry.Hash, err)
 				}
 
-				err = LinkTree(ctx, blobStore, treeStore, subTree, work.path)
+				err = LinkTree(ctx, blobStore, treeStore, subTree, work.path, opts...)
 				if err != nil {
 					return fmt.Errorf("link subtree %s: %w", work.path, err)
 				}

internal/getter/casgetter.go

@@ -45,7 +45,12 @@ func NewCASGetter(l log.Logger, c *cas.CAS, opts *cas.CloneOptions) *CASGetter {
 func (g *CASGetter) Get(ctx context.Context, req *getter.Request) error {
 	if req.Copy {
 		// Local directory: persist to CAS and link.
-		return g.CAS.StoreLocalDirectory(ctx, g.Logger, req.Src, req.Dst)
+		var linkOpts []cas.LinkTreeOption
+		if g.Opts != nil && g.Opts.Mutable {
+			linkOpts = append(linkOpts, cas.WithForceCopy())
+		}
+
+		return g.CAS.StoreLocalDirectory(ctx, g.Logger, req.Src, req.Dst, linkOpts...)
 	}
 
 	ref := ""

internal/getter/casprotocol.go

@@ -14,8 +14,9 @@ import (
 // CASProtocolGetter resolves cas::<algorithm>:<hash> references by
 // materializing the referenced tree from the CAS store.
 type CASProtocolGetter struct {
-	CAS    *cas.CAS
-	Logger log.Logger
+	CAS     *cas.CAS
+	Logger  log.Logger
+	Mutable bool
 }
 
 // NewCASProtocolGetter creates a new CASProtocolGetter.