Documentation
¶
Overview ¶
Package worktreedir owns access to the files of the working tree itself.
It is the third of Entire's three anchors, alongside entiredir (.entire) and gitdir (the git common dir), and the loosest of them: a root here contains operations to the repository rather than to a directory Entire owns. That is still worth having, because the paths that reach these reads and writes are not Entire's own:
- Checkpoint writes read working files named by `git status` output, on the hook path, to turn them into blobs.
- Rewind writes working files named by git TREE ENTRIES out of a checkpoint, which may have been fetched from a remote. Its restore half already opened a root for exactly this reason; the reads beside it did not.
- Diff-stat and gather read working files named from status output too.
A root makes "cannot leave the repository" a property of the handle rather than of each caller remembering to validate. It is not a substitute for the tree-path validation those callers do — normalizeRepoRelativeTreePath still rejects names that are not repo-relative before they are used as git paths — it is the layer underneath it.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func HashableEntry ¶ added in v0.11.0
HashableEntry reports whether filePath may be handed to gitrepo.HashWorktreeFiles (git hash-object), given the mode Git recorded for it in a tree.
It lives here rather than beside HashWorktreeFiles because gitrepo cannot import this package: worktreedir's own test imports testutil, which imports gitrepo, so that edge is an import cycle in the test binary.
Both halves are load-bearing, and each fails in a different direction:
- A Git symlink blob stores the target path, while hash-object follows the link and hashes the target's *content*. The two never agree, so a symlink recorded in the tree must be compared some other way.
- The working tree can hold something other than what the tree recorded. A tracked regular file replaced by a symlink is `git status`'s typechange (" T"), and hash-object follows it — so a link pointing at content equal to the recorded blob hashes equal and the change reads as clean. FIFOs are worse than wrong: hash-object blocks reading them, which on a hook path costs the caller its whole budget.
ModeIrregular is masked out rather than rejected, matching the reasoning in paths.ValidateEntireDirAt: Windows maps OneDrive Files On-Demand placeholders onto it, and those are ordinary files that should still receive Git's clean-filter handling.
func Name ¶
Name converts a path inside the worktree to a name relative to its root, accepting either an absolute path or one already relative to the root.
Git hands out slash-separated repo-relative paths and Entire assembles absolute ones from them; this is the single conversion back, so callers stop joining a root path onto a git path and reading the result.
func NameFollowingLinks ¶ added in v0.10.6
NameFollowingLinks is Name for a path that may itself be, or sit below, a symlink: it resolves the link first and then answers for the target.
os.Root refuses an ABSOLUTE symlink target unconditionally, including one resolving inside the root, so a root alone cannot express "follow a link that stays in the worktree, refuse one that leaves". That distinction is what a user-owned working-tree file needs — pointing vercel.json at a monorepo's shared config is a real setup, and it is written absolute as often as relative — while Entire's own trees (.entire, an agent's hook config) refuse a link either way and must not use this.
The name returned is worktree-relative and symlink-free, so the caller's read still goes through the root: a link repointed between the resolve and the read changes which in-worktree file is read and cannot escape the worktree.
A dangling link reports os.ErrNotExist, matching what os.Stat gives for one.
Types ¶
This section is empty.
Source Files