Support relative worktree paths (git 2.48+ worktree.useRelativePaths)#2151
Draft
elovelan wants to merge 2 commits into
Draft
Support relative worktree paths (git 2.48+ worktree.useRelativePaths)#2151elovelan wants to merge 2 commits into
elovelan wants to merge 2 commits into
Conversation
Git 2.48 introduced the `worktree.useRelativePaths` config option, which causes `git worktree add` to write a relative `gitdir` into the worktree's `.git` file. Resolve the relative `gitdir` against the worktree directory before before expanding it. Absolute paths are unaffected because `os.path.join` ignores the prefix when joined with an absolute path.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates GitPython’s worktree discovery to correctly resolve relative gitdir: paths written into worktree .git files when Git 2.48+ is configured with worktree.useRelativePaths.
Changes:
- Resolve worktree
.gitfilegitdir:entries relative to the directory containing the.gitfile before expanding/normalizing. - Add a new test that exercises
git worktree add --relative-pathson Git 2.48+. - Fix a command-construction example in
Git._call_processdocstring.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
git/repo/base.py |
Resolves worktree gitdir: paths relative to the worktree directory to support Git 2.48+ relative paths. |
test/test_repo.py |
Adds coverage for relative worktree gitdir: behavior via git worktree add --relative-paths. |
git/cmd.py |
Corrects a docstring example of how kwargs map to CLI flags. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+298
to
+299
| # worktrees can use relative paths as of Git 2.48, so we join to curpath | ||
| git_dir = expand_path(osp.join(curpath, sm_gitpath), expand_vars) |
Comment on lines
+1131
to
+1134
| @skipIf( | ||
| Git().version_info[:3] < (2, 48, 0), | ||
| reason="relative worktree feature unsupported (needs git 2.48.0 or later)", | ||
| ) |
Byron
reviewed
May 12, 2026
Member
Byron
left a comment
Byron
left a comment
There was a problem hiding this comment.
Thanks a lot, looks good to me!
Could you take a look at the co-pilot suggestions though?
Once resolved, this PR can be merged.
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.
Summary
Git 2.48 introduced the
worktree.useRelativePathsconfig option. When enabled,git worktree addwrites a relativegitdir:into the worktree's.gitfile — relative to the directory containing that.gitfile.GitPython's
Repo.__init__previously passed the value of thatgitdir:line straight throughexpand_path, which callsos.path.abspathagainst the process's current working directory rather than against the worktree. Using the library when the cwd was not the worktree root therefore failed.This change resolves the relative
gitdiragainstcurpath(the directory containing the.gitfile) before expanding. Absolute paths — i.e. the pre-2.48 default — are unaffected, becauseos.path.joinignores its first argument when the second is absolute.This change also includes a minor doc fix that I came across when trying to better understand how git is called.
Test plan
TestRepo.test_git_work_tree_dotgit_relative, which delegates totest_git_work_tree_dotgitbut runsgit worktree add --relative-paths. I verified that the test failed before implementation and now passes.test_git_work_tree_dotgitstill passes, confirming absolute-path worktrees are unaffected.AI disclosure
Per
CONTRIBUTING.md: this PR description and the commit message were drafted by Claude Code on behalf of @elovelan; though the final versions were manually reworded for clarity. All code was written without AI (didn't start that way but I didn't like its test implementation, and the actual implementation was trivial).