| name | digitalmodel-worktree-test-execution-with-shared-venv |
| description | Run digitalmodel tests from isolated worktrees without uv editable-dependency failures by using the main repo's existing virtualenv and PYTHONPATH. |
| version | 1.0.0 |
| author | Hermes Agent |
| license | MIT |
digitalmodel worktree test execution with shared venv
Paths below use $WORKROOT = the directory holding your sibling repo checkouts and worktrees
(/mnt/local-analysis on Linux dev machines; adjust for your platform). digitalmodel,
assetutilities, and worktrees/ are siblings under $WORKROOT.
When to use
Use this when:
- you are working in a git worktree of
digitalmodel
uv run in that worktree fails or tries to rebuild the environment- the failure mentions editable/local dependencies like
assetutilities==0.1.0 @ editable+../assetutilities
- you need fast, deterministic test execution from a side worktree
Typical symptom:
uv run python -m pytest ... fails in the worktree because ../assetutilities resolves relative to the worktree path rather than the main repo layout- or
uv run creates a fresh .venv in the worktree and breaks because sibling editable paths are missing
Why this happens
digitalmodel depends on local editable sibling repos. In an isolated worktree, relative editable paths can stop resolving the way they do in the main checkout. The main repo already has a working environment, so reusing it is safer than rebuilding from the worktree.
Preferred fix
Run tests from the worktree using the main repo's existing virtualenv interpreter and explicit PYTHONPATH=src.
Canonical pattern:
cd $WORKROOT/worktrees/<digitalmodel-worktree>
PYTHONPATH=src $WORKROOT/digitalmodel/.venv/bin/python -m pytest <target> -q
Examples:
cd $WORKROOT/worktrees/digitalmodel-issue-26
PYTHONPATH=src $WORKROOT/digitalmodel/.venv/bin/python -m pytest tests/solvers/blender_automation/test_blender_wrapper.py -q
cd $WORKROOT/worktrees/digitalmodel-issue-26
PYTHONPATH=src $WORKROOT/digitalmodel/.venv/bin/python -m pytest tests/solvers/blender_automation/ -q
Decision rules
- First try the shared-venv command above before debugging package resolution.
- If the shared-venv command passes, prefer it over
uv run for that worktree session.
- If the shared-venv command hangs during import/collection, treat the shared environment as broken for that worktree session rather than debugging product code first.
- Only fall back to environment surgery if the shared venv is genuinely missing or broken.
Shared-venv hang fallback
Sometimes the main repo .venv exists but hangs during pytest collection or even simple imports from an isolated worktree. Quick diagnosis:
cd $WORKROOT/worktrees/<digitalmodel-worktree>
timeout 30s PYTHONPATH=src $WORKROOT/digitalmodel/.venv/bin/python -c "import digitalmodel; print('ok')"
timeout 30s PYTHONPATH=src $WORKROOT/digitalmodel/.venv/bin/python -S -c "import sys; print('site-disabled-ok')"
If normal startup hangs but -S succeeds, avoid the shared venv for the targeted slice and create a local minimal test venv in the worktree:
cd $WORKROOT/worktrees/<digitalmodel-worktree>
uv venv .venv<issue>
./.venv<issue>/bin/python -m pip install 'pytest>=7,<9' 'pydantic>=2.7,<3' 'ruamel.yaml>=0.18,<1'
PYTHONPATH=src ./.venv<issue>/bin/python -m pytest <target> -q
Keep the local venv untracked. Remove any temporary sibling symlink workarounds after use. If git status is slow or times out in the worktree, retry with git -c core.fsmonitor=false status --short --untracked-files=all before assuming the tree is unusable.
Good verification sequence
- Confirm the main repo venv exists:
test -x $WORKROOT/digitalmodel/.venv/bin/python
- Run the narrow failing slice from the worktree:
PYTHONPATH=src $WORKROOT/digitalmodel/.venv/bin/python -m pytest <target> -q
- Run the smallest nearby regression slice after the fix.
Optional fallback
If a tool absolutely insists on uv run in the worktree, a temporary symlink for the sibling dependency may unblock it, but this is not preferred:
ln -s $WORKROOT/assetutilities $WORKROOT/worktrees/assetutilities
Use this only as a stopgap. Prefer the shared-venv command because it is simpler and less stateful.
Pitfalls
- Do not assume
uv run from a worktree will reuse the main repo environment.
- Do not waste time debugging unrelated test failures until you have ruled out the editable-dependency path problem.
- Remove temporary symlink workarounds after use if you created them.
What this pattern saved
This pattern avoided a false debugging path during a digitalmodel Blender automation hardening task where uv run from the worktree failed on editable assetutilities resolution. Using the main repo .venv plus PYTHONPATH=src made the targeted and regression test slices run cleanly from the isolated worktree.
