Native git wt
Contract
Git performs repository operations; Nu owns commands, records, completion, pickers, directory changes, and orchestration. The old module is a prototype, not a compatibility contract. No operation migrates an existing repository layout.
Supported layouts:
- Ordinary clones and linked worktrees, including arbitrary registered paths.
- Bare repositories with their worktrees under a shared root.
Existing worktrees are located through Git, never guessed from branch names.
New ordinary-clone worktrees live under sibling <repo>.worktrees/.
New bare-layout worktrees live beside the bare Git directory.
Path mapping must reject traversal, Windows reserved names, case collisions,
and occupied destinations without deleting or overwriting anything.
Submodules initialize when creating worktrees, unless --no-submodules is set.
Commands
git wt: same structured table asgit wt list.git wt list --fast: records without expensive per-worktree status checks.git wt switch [branch-or-path]: switch to a worktree; create its worktree for an existing local or unambiguous remote branch when necessary.git wt switch --create <branch> --base <ref>: create a new branch/worktree.git wt switch: interactive fuzzy picker; error in noninteractive mode.git wt switch pr:<number> --remote <name>: explicitly fetch a PR head; both GitHub and Forgejo userefs/pull/<number>/head.git wt prs --remote <name>: explicit network lookup, structured PR table.git wt switch <selector> --execute [command arg ...]: launch argv after switching and successful setup; no shell-string evaluation.git wt remove [branch-or-path] --keep-branch: remove a clean worktree.git wt merge [target] --message <text> --keep: merge current source, optionally retaining source worktree/branch.git wt hook <event>: explicitly run the configured event.
Commands running hooks accept --no-hooks and --approve-hooks.
The latter explicitly approves the current project-hook content.
It is not implied by any general confirmation option.
--no-hooks skips configuration and approval processing entirely, including
malformed configuration, so it also provides an explicit recovery route.
Return records or tables, not formatted text disguised as data.
Progress and approval prompts go to stderr.
Launched interactive programs inherit the terminal; their own output is not
captured or converted into Nu records.
Branch/path/target/event completions are local, contextual, and read-only.
Completions must never fetch, run hooks, or perform writes.
Aliases such as g = git must continue to work.
Examples
# Native tables stay pipeable.
git wt list | where dirty
# Create, switch, then start an interactive agent.
git wt switch --create feature/auth --base trunk --execute [pi]
# Explicit network lookup and PR checkout.
git wt prs --remote origin
git wt switch pr:17 --remote origin
# Integrate committed work, or retain an unmerged branch while removing its tree.
git wt merge trunk --message 'Add authentication'
git wt remove feature/auth --keep-branch
The prototype's clone, migrate, add, new, and go commands are retired.
Use normal Git to clone repositories; use switch for worktree lifecycle.
Safety
Worktree removal refuses dirty, locked, primary, nested-worktree, and unsafe
path cases; it never recursively deletes an arbitrary destination.
Without --keep-branch, branch deletion additionally requires proof that the
branch is integrated into the default branch.
Removing the current worktree changes to a surviving worktree first.
On Windows, Nu retains an OS handle to its startup directory even after cd.
If that directory is inside the removal target, removal is refused before
changing repository history; start Nu outside it and switch in, or use
merge --keep.
An unmerged branch can retain its commits through --keep-branch.
Clean state means Git's tracked and non-ignored untracked state.
Ignored files and build output follow normal Git worktree-removal behavior;
keep irreplaceable local data outside disposable worktrees.
Merge defaults to current source and the detected default branch as target.
Default detection honors existing wt.main-branch, then local remote HEAD,
then the primary branch; no hardcoded main requirement.
Source and target must be distinct, clean registered worktrees.
Detached, locked, unsafe, and in-progress Git operations are refused.
Merge pipeline:
- Validate source, target, paths, refs, clean state, and hook approvals.
- Preserve a recovery ref before rewriting committed source history.
- Squash committed source changes when necessary.
- Rebase onto target; conflicts stop with source available to resolve/abort.
- Run blocking
pre-mergehooks in source. - Recheck target tip/clean state, then fast-forward target only. Revalidate target identity and resulting tip before permitting cleanup. A concurrent change is reported with source retained, never force-reset.
- Unless
--keep, runpre-remove, revalidate both worktrees, remove source, delete integrated branch, and change to target.
No implicit commit of dirty work; no automatic fetch, push, force-push, or conflict resolution during merge. Failures never silently discard changes or remove a conflicted worktree. A failed hook or launch keeps a newly created worktree and explains its path. A successful integration followed by failed cleanup is reported as partial success, not as a rolled-back merge.
Hooks
Personal configuration: $nu.default-config-dir/wt.nuon.
Project configuration: <worktree>/.config/nu-wt.nuon.
Both files are inert NUON data, never sourced as code.
Only these events are supported initially:
post-create, pre-merge, pre-remove.
Hooks run sequentially in the operation worktree; failure stops the sequence.
Personal hooks precede project hooks.
No background-hook scheduler or shell templating is included.
Example:
{
hooks: {
post-create: [[just setup]]
pre-merge: [[just check]]
pre-remove: []
}
}
Each command is a nonempty list of strings, passed as literal argv.
Context is available through WT_REPO, WT_WORKTREE, WT_BRANCH,
WT_TARGET, and WT_TARGET_PATH environment variables.
Project hooks require approval tied to repository identity, event, and exact
command content; changed commands require renewed approval.
Approve every project command for an event before executing any event hook.
Noninteractive unapproved hooks fail without executing commands.
Declining approval stops the operation without deleting created data.
Approvals contain hashes, not executable code.
Approval records default to $nu.data-dir/wt-approvals.nuon and are ignored
by Git.
Overrides for isolated operation and tests:
NU_WT_CONFIG, NU_WT_APPROVALS.
No real user config or approval files are created during development tests.
Implementation boundaries
modules/git.nu owns repository lifecycle, completion, merge, and launch.
modules/wt-config.nu owns hook configuration, trust, and execution.
modules/wt-forge.nu owns explicit PR listing via gh or fj.
Shared context record:
{
root: "/repository-root"
common_dir: "/absolute/git-common-directory"
path: "/operation-worktree"
branch: "feature"
target: null
target_path: null
}
Module calls:
wt-config preflight <event> <context> --approve --skip: validate configs and approvals without running commands.wt-config execute <event> <context> --approve --skip: preflight, then execute hooks; return nothing on success, error on failure.wt-forge prs <context> --remote <name>: return records with number, title, remote, provider, and ref; error clearly on unavailable/auth-failing CLI.
GitHub uses machine-readable gh JSON.
Installed Forgejo CLI lacks JSON output; its minimal-mode adapter must be
strict, isolated, fixture-tested, and reject unrecognized nonempty output.
No token-file access, credential extraction, network calls in tests, or
silent provider fallback.
Verification
Cross-platform Python standard-library tests invoke isolated Nu processes.
All mutable fixtures live under OS-temp pi-nu-wt-tests/.
They cover both layouts, literal/quoted paths, local/remote selection, actual
Nu directory changes, status records, completion spans, dirty/locked/primary
removal refusal, merge graph/results, conflict and hook failure recovery,
approval invalidation, safe argv launching, and mocked provider results.
No real repository is cloned, reset, merged, migrated, or deleted by tests.
Run the fixture suite and the Python Git-call-site guard with:
python -B nushell/tests/test_git_wt.py -v
python -B nushell/tests/git-scope-guard.py
The fixture tests also simulate provider errors and refuse silent fallback. Live forge authentication/network behavior is not exercised by this suite.