chore(dev): scripts/wt-env para tornar worktrees usaveis em commit e push - #466
Merged
Conversation
Every commit and push from a git worktree failed on the same two traps, and each had to be rediscovered by hand. The loud one: the worktree's .venv is a poetry stub — Python 3.14 with pip and nothing else, while the project runs on 3.12. mypy, pytest and ruff are absent, so the pre-commit and pre-push hooks that shell out to them die with "'mypy' is not recognized". It surfaces at git push, after the work is finished, and the tempting answer (--no-verify) skips the very gates CI will enforce. The silent one, and the reason this is a script rather than a note: .venv/Lib/site-packages/drerio_logai.pth holds an ABSOLUTE path to the MAIN repository's src. Putting the main venv on PATH by hand fixes the missing tools but leaves imports resolving to main's code, so a suite run from inside a worktree goes green without having exercised one line of the branch under test. Nothing reports this. wt-env derives both values from git itself (--show-toplevel for the worktree, --git-common-dir for the main repo), so it needs no configuration and cannot drift when worktrees are added or removed. It prepends PYTHONPATH ahead of site-packages so the worktree's src wins over the .pth, and it is idempotent. Git hooks inherit the environment of the process that launched them, so sourcing once per shell makes commit and push work with the real gates running rather than bypassed. No CHANGELOG entry: developer tooling, no user-visible behaviour. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a small developer-experience utility to make working inside git worktrees reliable for this repo by ensuring hooks and local runs use the main repo’s real venv tools while importing the current worktree’s src/ (avoiding the “green tests against main branch code” trap).
Changes:
- Add
scripts/wt-env.shto prepend the main.venvtools toPATHand the current worktreesrc/toPYTHONPATH(idempotently). - Add
scripts/wt-env.ps1with the equivalent behavior for Windows PowerShell. - Document the “source this first in a worktree” workflow in
CLAUDE.md.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
scripts/wt-env.sh |
Bash script to set PATH/PYTHONPATH so hooks use main venv tools but import worktree code. |
scripts/wt-env.ps1 |
PowerShell version of the worktree environment bootstrap for Windows. |
CLAUDE.md |
Adds a “worktree step zero” section documenting the two traps and the fix scripts. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
O problema
Todo commit e push feito de dentro de um git worktree esbarrava nas mesmas duas armadilhas, e cada uma precisava ser redescoberta na mão.
A barulhenta. O
.venvdo worktree é um stub do poetry: Python 3.14 com pip e mais nada, enquanto o projeto roda em 3.12.mypy,pytesteruffsimplesmente não existem lá, então todo hook de pre-commit/pre-push que os invoca morre com'mypy' não é reconhecido. Aparece nogit push, depois do trabalho pronto — e a saída tentadora (--no-verify) pula exatamente os gates que o CI vai cobrar.A silenciosa — e a razão de isto ser um script, não um recado no README. O arquivo
.venv/Lib/site-packages/drerio_logai.pthguarda um caminho absoluto para osrcdo repositório principal. Colocar o venv principal noPATHna mão resolve as ferramentas ausentes, mas deixa os imports resolvendo para o código domain: uma suíte rodada de dentro do worktree fica verde sem ter exercitado uma linha do branch em teste. Nada avisa.A solução
scripts/wt-env.sh(bash) escripts/wt-env.ps1(PowerShell). Uma vez por shell:--show-toplevelpara o worktree,--git-common-dirpara o repo principal. Sem configuração, e não desatualiza quando worktrees são criados ou removidos.PYTHONPATHantes do site-packages, então osrcdo worktree vence o.pth..venv(para evitarpoetry runali).Hooks do git herdam o ambiente do processo que os lançou, então sourcear uma vez faz
git commitegit pushpassarem a funcionar com os gates rodando de verdade, não contornados.Documentado no
CLAUDE.mdcomo passo zero ao entrar num worktree.Verificação
Testado nos dois shells, num worktree real, com
PYTHONPATHlimpo antes:mypysai de ausente para.venv/Scripts/mypy;zebtrack.__file__aponta para osrcdo worktreeGet-Command mypyezebtrack.__file__Esses três PRs desta leva (#464, #465 e o próximo, da varredura i18n) foram todos empurrados com esse ambiente, com
mypy .e os testes GUI rodando nos hooks — nenhum--no-verify.Sem entrada no CHANGELOG: é ferramenta de desenvolvimento, sem comportamento visível ao usuário. Também não toca
CHANGELOG.mdde propósito, para não conflitar com o PR da varredura i18n que vem em seguida.🤖 Generated with Claude Code