Help us shape the future of Go! Take the 2026 Go Developer Survey

filetree

package
v0.3.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 16, 2026 License: Apache-2.0 Imports: 20 Imported by: 12

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrLinkCycleDetected = errors.New("cycle during symlink resolution")
View Source 
var ErrLinkResolutionDepth = errors.New("maximum link resolution stack depth exceeded")
View Source 
var ErrMaxTraversalDepth = errors.New("max allowable directory traversal depth reached (maybe a link cycle?)")
View Source 
var ErrRemovingRoot = errors.New("cannot remove the root path (`/`) from the FileTree")

Functions 

func IsUnresolvableLink(err error) bool

IsUnresolvableLink indicates a link that cannot be followed because the image itself is malformed, as opposed to a lookup that legitimately failed. Callers enumerating the tree should treat these paths as unresolved and keep going; callers resolving or mutating one specific path still want the error. This is exported so that callers wrapping the single-path resolution API (which still returns these errors) can make the same distinction without restating which sentinels mean "malformed image".

Types

type Builder 

type Builder struct {
	// contains filtered or unexported fields
}

Builder is a helper for building a filetree and accompanying index in a coordinated fashion.

func NewBuilder 

func NewBuilder(tree Writer, index IndexWriter) *Builder

func (*Builder) Add 

func (b *Builder) Add(metadata file.Metadata) (*file.Reference, error)

type Copier 

type Copier interface {
	Copy() (ReadWriter, error)
}

type DepthFirstPathWalker 

type DepthFirstPathWalker struct {
	// contains filtered or unexported fields
}

DepthFirstPathWalker implements stateful depth-first Tree traversal.

func NewDepthFirstPathWalker 

func NewDepthFirstPathWalker(tree *FileTree, visitor FileNodeVisitor, conditions *WalkConditions) *DepthFirstPathWalker

func (*DepthFirstPathWalker) Visited 

func (w *DepthFirstPathWalker) Visited(p file.Path) bool

func (*DepthFirstPathWalker) Walk 

func (w *DepthFirstPathWalker) Walk(from file.Path) (file.Path, *filenode.FileNode, error)

Walk traverses the tree depth-first from the given path, returning the last path considered and its node. Note: the returned path is the last path POPPED, not the last path visited, and the returned FileNode is nil (with a nil error) when that path could not be resolved because of a malformed link. Check the node for nil before dereferencing it; a nil error alone no longer implies a node.

func (*DepthFirstPathWalker) WalkAll 

func (w *DepthFirstPathWalker) WalkAll() error

type FileNodeVisitor 

type FileNodeVisitor func(file.Path, filenode.FileNode) error

type FileTree 

type FileTree struct {
	// contains filtered or unexported fields
}

FileTree represents a file/directory Tree

func New 

func New() *FileTree

New creates a new FileTree instance.

func NewFileTree deprecated 

func NewFileTree() *FileTree

NewFileTree creates a new FileTree instance.

Deprecated: use New() instead.

func (*FileTree) AddDir 

func (t *FileTree) AddDir(realPath file.Path) (*file.Reference, error)

AddDir adds a new path representing a DIRECTORY to the Tree. It also adds any ancestors of the path that are not already present in the Tree. The resulting file.Reference of the new (leaf) addition is returned. Note: NO symlink or hardlink resolution is performed on the given path --which implies that the given path MUST be a real path (have no links in constituent paths)

func (*FileTree) AddFile 

func (t *FileTree) AddFile(realPath file.Path) (*file.Reference, error)

AddFile adds a new path representing a REGULAR file to the Tree. It also adds any ancestors of the path that are not already present in the Tree. The resulting file.Reference of the new (leaf) addition is returned. Note: NO symlink or hardlink resolution is performed on the given path --which implies that the given path MUST be a real path (have no links in constituent paths) 

func (t *FileTree) AddHardLink(realPath file.Path, linkPath file.Path) (*file.Reference, error)

AddHardLink adds a new path to the Tree that represents a HARDLINK. A new file.Reference with a absolute link path captured and returned. Note: NO symlink or hardlink resolution is performed on the given path --which implies that the given path MUST be a real path (have no links in constituent paths) 

func (t *FileTree) AddSymLink(realPath file.Path, linkPath file.Path) (*file.Reference, error)

AddSymLink adds a new path to the Tree that represents a SYMLINK. A new file.Reference with a absolute or relative link path captured and returned. Note: NO symlink or hardlink resolution is performed on the given path --which implies that the given path MUST be a real path (have no links in constituent paths)

func (*FileTree) AllFiles 

func (t *FileTree) AllFiles(types ...file.Type) []file.Reference

AllFiles returns all files within the FileTree (defaults to regular files only, but you can provide one or more allow types).

func (*FileTree) AllRealPaths 

func (t *FileTree) AllRealPaths() []file.Path

func (*FileTree) Copy 

func (t *FileTree) Copy() (ReadWriter, error)

Copy returns a Copy of the current FileTree.

func (*FileTree) Equal 

func (t *FileTree) Equal(other *FileTree) bool

Equal indicates if the two trees have the same paths or not.

func (*FileTree) File 

func (t *FileTree) File(path file.Path, options ...LinkResolutionOption) (bool, *file.Resolution, error)

File fetches a file.Reference for the given path. Returns nil if the path does not exist in the FileTree.

func (*FileTree) FilesByGlob 

func (t *FileTree) FilesByGlob(query string, options ...LinkResolutionOption) ([]file.Resolution, error)

FilesByGlob fetches zero to many file.References for the given glob pattern (considers symlinks).

func (*FileTree) HasPath 

func (t *FileTree) HasPath(path file.Path, options ...LinkResolutionOption) bool

HasPath indicates is the given path is in the file Tree (with optional link resolution options).

func (*FileTree) ListPaths 

func (t *FileTree) ListPaths(dir file.Path) ([]file.Path, error)

func (*FileTree) Merge 

func (t *FileTree) Merge(upper Reader) error

Merge takes the given Tree and combines it with the current Tree, preferring files in the other Tree if there are path conflicts. This is the basis function for squashing (where the current Tree is the bottom Tree and the given Tree is the top Tree).

func (*FileTree) PathDiff 

func (t *FileTree) PathDiff(other *FileTree) (extra, missing []file.Path)

PathDiff shows the path differences between two trees (useful for testing)

func (*FileTree) RemoveChildPaths 

func (t *FileTree) RemoveChildPaths(path file.Path) error

RemoveChildPaths deletes all children of the given path (not including the given path). Note: if the given path basename is a symlink, then the symlink is followed before resolving children. If the path does not exist, this is a nop.

func (*FileTree) RemovePath 

func (t *FileTree) RemovePath(path file.Path) error

RemovePath deletes the file.Reference from the FileTree by the given path. If the basename of the given path is a symlink then the symlink is removed (not the destination of the symlink). If the path does not exist, this is a nop.

func (*FileTree) TreeReader 

func (t *FileTree) TreeReader() tree.Reader

TreeReader returns a tree.Reader useful for Tree traversal.

func (*FileTree) Walk 

func (t *FileTree) Walk(fn func(path file.Path, f filenode.FileNode) error, conditions *WalkConditions) error

Walk takes a visitor function and invokes it for all paths within the FileTree in depth-first ordering.

type Index 

type Index interface {
	IndexReader
	IndexWriter
}

func NewIndex 

func NewIndex() Index

NewIndex returns an empty Index.

type IndexEntry 

type IndexEntry struct {
	file.Reference
	file.Metadata
}

IndexEntry represents all stored metadata for a single file reference.

type IndexReader 

type IndexReader interface {
	Exists(f file.Reference) bool
	Get(f file.Reference) (IndexEntry, error)
	GetByMIMEType(mTypes ...string) ([]IndexEntry, error)
	GetByFileType(fTypes ...file.Type) ([]IndexEntry, error)
	GetByExtension(extensions ...string) ([]IndexEntry, error)
	GetByBasename(basenames ...string) ([]IndexEntry, error)
	GetByBasenameGlob(globs ...string) ([]IndexEntry, error)
}

type IndexWriter 

type IndexWriter interface {
	Add(f file.Reference, m file.Metadata)
}

type LinkResolutionOption 

type LinkResolutionOption int

LinkResolutionOption is a single link resolution rule. 

const (

	// FollowBasenameLinks deals with link resolution for the basename of a given path (not ancestors).
	FollowBasenameLinks LinkResolutionOption

	// DoNotFollowDeadBasenameLinks deals with a special case in link resolution: when a basename resolution results in
	// a dead link. This option ensures that the last link file that resolved is returned (which exists) instead of
	// the non-existing path. This is useful when the caller wants to do custom link resolution (e.g. for container
	// images: the link is dead in this layer squash, but does it resolve in a higher layer?).
	DoNotFollowDeadBasenameLinks
)

type PathReader 

type PathReader interface {
	// File resolves a single path. A malformed link is returned as an error.
	File(path file.Path, options ...LinkResolutionOption) (bool, *file.Resolution, error)
	// FilesByGlob enumerates matching paths. Matches with a malformed link are omitted rather than erroring.
	FilesByGlob(query string, options ...LinkResolutionOption) ([]file.Resolution, error)
	AllRealPaths() []file.Path
	// ListPaths enumerates a directory. A malformed link yields an empty listing rather than an error.
	ListPaths(dir file.Path) ([]file.Path, error)
	HasPath(path file.Path, options ...LinkResolutionOption) bool
}

PathReader note: the methods here split on whether they resolve one path or enumerate many. File resolves one path and reports a malformed link (see IsUnresolvableLink) as an error, since the caller asked about exactly that path. The enumerating methods skip such paths instead, because one bad link in an image must not cost the caller every other result. A nil result from those therefore means "absent or unresolvable", not just "absent".

type ReadWriter 

type ReadWriter interface {
	Reader
	Writer
}

type Reader 

type Reader interface {
	AllFiles(types ...file.Type) []file.Reference
	TreeReader() tree.Reader
	PathReader
	Walker
	Copier
}

type Searcher 

type Searcher interface {
	// SearchByPath returns nil with a nil error when the path is absent OR its link cannot be resolved.
	SearchByPath(path string, options ...LinkResolutionOption) (*file.Resolution, error)
	SearchByGlob(patterns string, options ...LinkResolutionOption) ([]file.Resolution, error)
	SearchByMIMEType(mimeTypes ...string) ([]file.Resolution, error)
}

Searcher is a facade for searching a file tree with optional indexing support. All three methods skip paths whose links are malformed (see IsUnresolvableLink) rather than failing the search, so a nil or absent result means "absent or unresolvable".

func NewSearchContext 

func NewSearchContext(tree Reader, index IndexReader) Searcher

type UnionFileTree 

type UnionFileTree struct {
	// contains filtered or unexported fields
}

UnionFileTree stacks file trees as OCI changesets, lowest pushed first. Trees pushed here are interpreted as layer diffs rather than as plain filesystems: whiteout entries (".wh.*", and the opaque directory marker ".wh..wh..opq") are changeset metadata that Squash consumes and never emits. Use FileTree.Copy directly for a faithful copy with no changeset interpretation.

func NewUnionFileTree 

func NewUnionFileTree() *UnionFileTree

func (*UnionFileTree) PushTree 

func (u *UnionFileTree) PushTree(t ReadWriter)

func (*UnionFileTree) Squash 

func (u *UnionFileTree) Squash() (ReadWriter, error)

Squash applies each pushed tree onto the one below it and returns the result. The result never contains whiteout entries, including any carried by the lowest tree, which means a Squash of a single tree is not the same as a Copy of that tree.

type WalkConditions 

type WalkConditions struct {
	// Return true when the walker should stop traversing (before visiting current Node)
	ShouldTerminate func(file.Path, filenode.FileNode) bool

	// Whether we should visit the current Node. Note: this will continue down the same traversal
	// path, only "skipping" over a single Node (but still potentially visiting children later)
	// Return true to visit the current Node.
	ShouldVisit func(file.Path, filenode.FileNode) bool

	// Whether we should consider children of this Node to be included in the traversal path.
	// Return true to traverse children of this Node.
	ShouldContinueBranch func(file.Path, filenode.FileNode) bool

	LinkOptions []LinkResolutionOption
}

type Walker 

type Walker interface {
	Walk(fn func(path file.Path, f filenode.FileNode) error, conditions *WalkConditions) error
}

type Writer 

type Writer interface {
	AddFile(realPath file.Path) (*file.Reference, error)
	AddSymLink(realPath file.Path, linkPath file.Path) (*file.Reference, error)
	AddHardLink(realPath file.Path, linkPath file.Path) (*file.Reference, error)
	AddDir(realPath file.Path) (*file.Reference, error)
	RemovePath(path file.Path) error
	Merge(upper Reader) error
}

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.