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 Entry
- type File
- type Inventory
- type LiveContext
- 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 Entry ¶ added in v0.41.0
Entry is a live path inventory entry. Unlike File it makes no claim that bytes were captured, so an unread present path cannot be confused with an absent path.
type File ¶
File is one file in a snapshot: a repo-relative slash path, its Mode, and a private copy of its bytes.
type Inventory ¶ added in v0.41.0
type Inventory struct {
// contains filtered or unexported fields
}
Inventory is an immutable complete live path and mode inventory.
func NewInventory ¶ added in v0.41.0
NewInventory validates and sorts a complete inventory independently from selected content.
type LiveContext ¶ added in v0.41.0
type LiveContext struct {
// contains filtered or unexported fields
}
LiveContext joins complete inventory to separately selected immutable bytes.
func NewLiveContext ¶ added in v0.41.0
func NewLiveContext(inventory *Inventory, selected *Selection) (*LiveContext, error)
func WorkingContextFromEntries ¶ added in v0.41.0
func WorkingContextFromEntries(ctx context.Context, repo *git.Repo, entries []git.TreeEntry, selected []string) (*LiveContext, error)
WorkingContextFromEntries captures selected bytes against one already-read Git-owned inventory. It keeps enumeration and reading in the same operation without silently taking a second live view.
func (*LiveContext) Inventory ¶ added in v0.41.0
func (v *LiveContext) Inventory() *Inventory
Inventory returns the complete live path and mode inventory.
func (*LiveContext) Selection ¶ added in v0.41.0
func (v *LiveContext) Selection() *Selection
Selection returns the selected immutable file content.
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. It remains the historical sparse content representation; LiveContext is the distinct live inventory-plus-content representation used by ordinary context.
func NewSelection ¶ added in v0.30.0
NewSelection validates files, copies their bytes, and sorts them by 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