Documentation
¶
Index ¶
- func BranchExists(dir, branch string) bool
- func CopyTree(src, dst string) error
- func EnsureWorktreeDeps(mainRepoPath, worktreePath, worktreeDomain string, secured bool, out io.Writer)
- func EnsureWorktreeEnv(mainRepoPath, worktreePath, worktreeDomain string, secured bool)
- func InstallDependencies(projectPath string, out io.Writer) error
- func IsMainRepo(sitePath string) bool
- func LockInstall(worktreePath string, timeout time.Duration) (func(), error)
- func MainBranch(sitePath string) string
- func NeedsInstall(projectPath string) bool
- func Output(dir string, args ...string) (string, error)
- func Run(dir string, log io.Writer, args ...string) error
- func RunCaptureStderr(dir string, args ...string) (string, error)
- func RunNpmScript(projectPath, script string, out io.Writer) error
- func RunTTY(dir string, args ...string) error
- func SanitizeBranch(branch string) string
- func TryLockInstall(worktreePath string) (func(), bool, error)
- type Worktree
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BranchExists ¶ added in v1.21.0
BranchExists reports whether refs/heads/<branch> resolves inside the repo at dir. Returns false when branch is empty, when dir is not a repo, or when the ref cannot be resolved.
func CopyTree ¶ added in v1.16.0
CopyTree copies src to dst recursively. It first tries a reflink-aware fast path via cp, which is near-instant on btrfs, XFS with reflink=1, and APFS. Falls back to a plain recursive Go copy elsewhere. dst must not already exist.
func EnsureWorktreeDeps ¶
func EnsureWorktreeDeps(mainRepoPath, worktreePath, worktreeDomain string, secured bool, out io.Writer)
EnsureWorktreeDeps sets up a worktree checkout with the dependencies it needs:
- vendor/ and node_modules/ are seeded from the main repo via a reflink copy (near-instant on btrfs, xfs-reflink, APFS; plain copy on ext4), then reconciled against the worktree's own lockfiles via composer install / npm ci.
- .env is copied from the main repo with APP_URL rewritten to http(s)://<worktreeDomain>
Copying (rather than symlinking) is required because PHP resolves __DIR__ through symlinks, which would make Composer's ClassLoader initialise against the main repo directory and silently load stale classes from there.
out receives composer/npm install output; pass nil for the default stdout/stderr (which is what the watcher daemon's launchd unit captures to lerd-watcher.log).
func EnsureWorktreeEnv ¶ added in v1.19.0
EnsureWorktreeEnv copies .env from the main repo when missing (gitignored, so `git worktree add` never carries it across) and rewrites APP_URL to the worktree domain. When the main repo's .lerd.yaml defines env_overrides, those values are resolved and layered on top — only keys declared in env_overrides are touched, so partial overrides (e.g. SESSION_DOMAIN only) don't suppress the default APP_URL rewrite. Idempotent and cheap; safe to call on every request.
func InstallDependencies ¶ added in v1.16.0
InstallDependencies runs composer install and the JS package manager matching whatever lockfile the project ships so vendor/ and node_modules/ match that checkout's own lockfiles. composer goes through the lerd shim (which routes into the project's PHP-FPM container); JS tooling goes through whichever of pnpm/yarn/bun/npm is on PATH, preferring the npm shim from BinDir when the project uses npm so the fnm Node version is picked up.
Each install is skipped when the relevant install marker (vendor/composer/installed.json for composer, the package manager's own marker under node_modules for JS) is at-or-newer than the lockfile — nothing has drifted, so re-running install would just burn cycles on post-autoload-dump scripts (Laravel package:discover, Filament asset publish, etc.) for no observable change.
Errors are aggregated and returned; callers should log them rather than treat them as fatal since the worktree is still usable with the copied trees from main. out receives both stdout and stderr from composer and the JS package manager; pass nil to fall back to the watcher daemon's own stdout/stderr (which the original launchd unit captures into lerd-watcher.log).
func IsMainRepo ¶
IsMainRepo returns true if sitePath/.git is a directory (not a file). A file means the repo itself is a worktree, not the main checkout.
func LockInstall ¶ added in v1.21.0
LockInstall acquires an exclusive cross-process lock guarding the composer/npm install for worktreePath, blocking until either the lock is held or timeout elapses. Returns release() which drops both the in-process and OS locks; safe to defer.
func MainBranch ¶
MainBranch returns the current branch of the main repo checkout at sitePath, or an empty string if it cannot be determined.
func NeedsInstall ¶ added in v1.21.0
NeedsInstall reports whether projectPath has a composer or JS install that hasn't completed. Used by the watcher's periodic rescan to recover from a UI install that crashed between `git worktree add` and the seed.
func Output ¶ added in v1.21.0
Output runs `git <args>` in dir and returns its stdout as a string. If dir is empty, the command inherits the caller's working directory. Stderr is discarded; callers that need it should reach for RunCaptureStderr.
func Run ¶ added in v1.21.0
Run runs `git <args>` in dir, sending stdout and stderr to log (a single writer; matches the modal-log pattern used by the worktree flows). When log is nil, output is discarded. Empty dir means inherit cwd. The returned error wraps the exec failure with the first non-flag arg so callers can surface "git worktree: exit status 1" rather than the full arg list.
func RunCaptureStderr ¶ added in v1.21.0
RunCaptureStderr runs `git <args>` in dir, mirroring stdout to os.Stdout and stderr to both os.Stderr and an internal buffer. The captured stderr is returned alongside any exec error so callers can detect specific git error messages (e.g. the "use --force" hint) without dropping the live stream the user is watching.
func RunNpmScript ¶ added in v1.19.0
RunNpmScript executes `<package-manager> run <script>` in projectPath, using the lerd npm shim for npm projects so fnm's current Node version wins and falling back to PATH for pnpm/yarn/bun. Exported for callers like `lerd worktree add` that opt into a build step interactively. out receives both stdout and stderr from the build; pass os.Stdout for CLI use or an SSE writer to surface vite/webpack failures in the dashboard modal.
func RunTTY ¶ added in v1.21.0
RunTTY runs `git <args>` in dir with stdout and stderr wired straight to os.Stdout and os.Stderr so the user's shell redirections (`2>/dev/null`, pipes, etc) still work. Empty dir means inherit cwd.
func SanitizeBranch ¶
SanitizeBranch converts a branch name to a subdomain-safe slug.
func TryLockInstall ¶ added in v1.21.0
TryLockInstall is the non-blocking variant of LockInstall: returns (release, true) when the lock was acquired immediately, or (nil, false) when another caller holds it. err is non-nil only on filesystem failures; "already locked" is reported via the boolean.
Types ¶
type Worktree ¶
type Worktree struct {
Name string // subdirectory name under .git/worktrees/
Branch string // sanitized branch (subdomain-safe)
Path string // absolute path to checkout dir
Domain string // "<sanitized-branch>.<siteDomain>"
}
Worktree represents a git worktree checkout for a registered site.
func DetectWorktrees ¶
DetectWorktrees returns the list of active worktrees for the given site.
Source Files