worktree

type CreateOptions struct {
	// Name is the bay name; it becomes the directory name.
	Name string
	// Branch to check out. Defaults to Name.
	Branch string
	// From is the starting point for a branch that does not exist yet.
	// Defaults to the repository's current HEAD.
	From string
}

type Manager struct {
	// RepoRoot is the main checkout's root.
	RepoRoot string
	// Root is where devbay creates new worktrees.
	Root string

	// Log receives notes a developer needs to see. Never nil after Open.
	Log func(format string, args ...any)

	// Reclaim takes ownership of a worktree back from the containers that
	// wrote into it, and is called only when removal has already failed for
	// lack of permission.
	//
	// A container writing into the bind-mounted worktree writes as whatever
	// user it runs as, which for most images is root. On Linux that ownership
	// is the host's ownership -- there is no mapping layer -- so a build
	// artefact, a lockfile, or a test report left behind by a container is a
	// root-owned file the developer cannot delete, and `devbay rm` fails
	// having already destroyed the containers. On macOS the file sharing layer
	// maps ownership to the calling user and this never happens, which is
	// exactly why it went unnoticed until CI ran on Linux.
	//
	// A function rather than a direct call because this package deliberately
	// knows nothing about containers; the caller supplies the means.
	Reclaim func(path string) error
}

type Worktree struct {
	// Path is the absolute path of the checkout.
	Path string
	// Branch is the branch checked out there, without the refs/heads/ prefix.
	// Empty for a detached HEAD.
	Branch string
	// Head is the commit currently checked out.
	Head string
	// Main reports whether this is the repository's primary checkout rather
	// than a linked worktree. devbay never removes the main worktree.
	Main bool
	// CreatedBranch reports that this call created the branch, rather than
	// checking out one that already existed. It matters on failure: unwinding
	// has to delete a branch devbay created, or a retry silently checks out
	// the stale one instead of the caller's corrected code.
	CreatedBranch bool
	// Adopted reports that devbay found this worktree rather than creating it —
	// typically an agent's own. Adopted worktrees are not removed on teardown,
	// because devbay did not create them and something else may still be using
	// them.
	Adopted bool
}