From 99a6ff91da03c64a3e6326ef97b9066a6b022774 Mon Sep 17 00:00:00 2001
From: Will Rouesnel <wrouesnel@wrouesnel.com>
Date: Tue, 21 Oct 2025 11:28:35 +1100
Subject: [PATCH] Add WrappedFS interface

WrappedFS implements an optional interface to allow an afero.FS to be
dereferenced to yield the underlying filesystem it is wrapping. It does not
make sense in all circumstances, but can provide for example to allow determining
if an afero filesystem is backed by an underlying OsFs.
---
 basepath.go      |  4 ++++
 cacheOnReadFs.go |  4 ++++
 readonlyfs.go    |  4 ++++
 regexpfs.go      |  4 ++++
 wrappedfs.go     | 24 ++++++++++++++++++++++++
 5 files changed, 40 insertions(+)
 create mode 100644 wrappedfs.go

diff --git a/basepath.go b/basepath.go
index 2e72793a..e31d63b5 100644
--- a/basepath.go
+++ b/basepath.go
@@ -220,3 +220,7 @@ func (b *BasePathFs) ReadlinkIfPossible(name string) (string, error) {
 	}
 	return "", &os.PathError{Op: "readlink", Path: name, Err: ErrNoReadlink}
 }
+
+func (b *BasePathFs) ParentFS() Fs {
+	return b.source
+}
diff --git a/cacheOnReadFs.go b/cacheOnReadFs.go
index 017d344f..8a974050 100644
--- a/cacheOnReadFs.go
+++ b/cacheOnReadFs.go
@@ -313,3 +313,7 @@ func (u *CacheOnReadFs) Create(name string) (File, error) {
 	}
 	return &UnionFile{Base: bfh, Layer: lfh}, nil
 }
+
+func (u *CacheOnReadFs) ParentFS() Fs {
+	return u.base
+}
diff --git a/readonlyfs.go b/readonlyfs.go
index bd8f9264..eaae67f6 100644
--- a/readonlyfs.go
+++ b/readonlyfs.go
@@ -94,3 +94,7 @@ func (r *ReadOnlyFs) MkdirAll(n string, p os.FileMode) error {
 func (r *ReadOnlyFs) Create(n string) (File, error) {
 	return nil, syscall.EPERM
 }
+
+func (r *ReadOnlyFs) ParentFS() Fs {
+	return r.source
+}
diff --git a/regexpfs.go b/regexpfs.go
index 218f3b23..c4c091ac 100644
--- a/regexpfs.go
+++ b/regexpfs.go
@@ -153,6 +153,10 @@ func (r *RegexpFs) Create(name string) (File, error) {
 	return r.source.Create(name)
 }
 
+func (r *RegexpFs) ParentFS() Fs {
+	return r.source
+}
+
 func (f *RegexpFile) Close() error {
 	return f.f.Close()
 }
diff --git a/wrappedfs.go b/wrappedfs.go
new file mode 100644
index 00000000..f99f22bc
--- /dev/null
+++ b/wrappedfs.go
@@ -0,0 +1,24 @@
+// Copyright © 2018 Steve Francia <spf@spf13.com>.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package afero
+
+// WrappedFs is an optional interface in Afero. It is only implemented by the
+// filesystems saying so.
+// Filesystems which wrap another filesystem can provide access to their parent
+// filesystem by implementing this interface.
+// If this interface returns nil, then the filesystem either has no parents or
+// is unable to provide a parent.
+type WrappedFs interface {
+	ParentFS() Fs
+}