Documentation
¶
Overview ¶
Package snapshot captures immutable file trees from Git or an ordinary filesystem directory. A Tree owns a private copy of every file's bytes, so a consumer can read the captured content and mode without mutating the snapshot or the caller's original data. Git-backed snapshots cover the working tree, stage-0 index, an arbitrary commit, and a first-parent before/after range; the filesystem form supports repo-state checks before Git is available. Each is the complete selected file set; consumers apply their own eligibility filters.
Index ¶
- Variables
- type File
- type Mode
- type Selection
- type Tree
- func CommitTree(ctx context.Context, repo *git.Repo, rev string) (*Tree, error)
- func CommitTrees(ctx context.Context, repo *git.Repo, revs []string) ([]*Tree, error)
- func FilesystemTree(ctx context.Context, root string) (*Tree, error)
- func IndexTree(ctx context.Context, repo *git.Repo) (*Tree, error)
- func NewTree(files []File) (*Tree, error)
- func WorkingTree(ctx context.Context, repo *git.Repo) (*Tree, error)
Constants ¶
This section is empty.
Variables ¶
var ( // ErrUnsupportedMode reports a File whose Mode is not representable. ErrUnsupportedMode = errors.New("snapshot: unsupported file mode") // ErrUnsafePath reports a File whose path is empty, absolute, or escapes // the tree root through traversal or a non-canonical form. ErrUnsafePath = errors.New("snapshot: unsafe path") // ErrDuplicatePath reports two Files sharing one path. ErrDuplicatePath = errors.New("snapshot: duplicate path") )
Construction faults. NewTree and NewSelection return one of these when a File would make the snapshot ambiguous or unsafe to address by path.
Functions ¶
This section is empty.
Types ¶
type File ¶
File is one file in a snapshot: a repo-relative slash path, its Mode, and a private copy of its bytes.
type Mode ¶
type Mode uint8
Mode is the file mode a snapshot preserves. Symlink bytes are inert targets.
type Selection ¶ added in v0.30.0
type Selection struct {
// contains filtered or unexported fields
}
Selection is an immutable, path-sorted explicit set of files. Build one with NewSelection; its Lookup and List methods hand out byte copies so callers cannot reach the captured content.
func NewSelection ¶ added in v0.30.0
NewSelection validates files, copies each one's bytes, and returns a path-sorted Selection. It rejects an unsupported mode, an unsafe path, or a duplicate path so every selected file is addressable by exactly one canonical relative path.
func NewSelectionFromBlobs ¶ added in v0.30.0
NewSelectionFromBlobs converts Git blobs into an immutable Selection. It preserves Git's regular, executable, and symlink modes and rejects any mode outside that closed set; Selection performs the clone, sort, and path validation.
type Tree ¶
type Tree struct {
// contains filtered or unexported fields
}
Tree is an immutable, path-sorted set of files. Build one with NewTree; its Lookup and List methods hand out byte copies so callers cannot reach the captured content.
func CommitTree ¶
CommitTree captures the committed tree that rev resolves to as an immutable Tree. It reads only committed content, never the working tree, so a commit or HEAD universe is reproducible regardless of local edits. Ordinary and executable, and symlink files are included with their mode preserved; symlink bytes are inert targets and gitlinks are skipped.
func CommitTrees ¶ added in v0.30.0
CommitTrees captures revisions in caller order.
func FilesystemTree ¶ added in v0.30.0
FilesystemTree captures an ordinary directory without requiring Git. It is the fallback working universe for repository-state checks before adoption by Git. Git metadata and nested checkout roots are never part of that universe.
func IndexTree ¶
IndexTree captures the repository's stage-0 index as an immutable Tree. Ordinary, executable, and symlink files are included with mode preserved; symlink bytes are inert targets and gitlinks are skipped; an unmerged or unreadable index is rejected. Path selection and ordering come from the handle's IndexBlobs, whose tolerant open resolves a linked worktree's index like any other command.
func NewTree ¶
NewTree validates files, copies each one's bytes, and returns a path-sorted Tree. It rejects an unsupported mode, an unsafe path, or a duplicate path so every file is addressable by exactly one canonical relative path.
func WorkingTree ¶
WorkingTree captures the repository's working universe as an immutable Tree: every tracked-and-present or nonignored-untracked file, with executable and symlink modes preserved. Symlinks are not followed; their target is retained as inert bytes. Deleted, ignored, and nested-repository paths are excluded by the handle's WorkingPaths. It is the complete selected filesystem universe; generated, contextIgnore, and other eligibility filters are applied by downstream consumers, not here.
Source Files