Support relative worktree paths (git 2.48+ worktree.useRelativePaths) - #2151
Merged
Byron merged 3 commits intoMay 16, 2026
Merged
Conversation
Copy link
Copy Markdown
Contributor
Sorry, something went wrong.
Copy link
Copy Markdown
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 .git file gitdir: entries relative to the directory containing the .git file before expanding/normalizing.
- Add a new test that exercises git worktree add --relative-paths on Git 2.48+.
- Fix a command-construction example in Git._call_process docstring.
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.
Sorry, something went wrong.
Comment thread
git/repo/base.py
Outdated
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) |
Copy link
Copy Markdown
Contributor
Author
There was a problem hiding this comment.
This fix won't work because it's doing the same thing as the original code (because expand_path calls osp.abspath). To do this properly, I'd have to create a copy of expand_path that doesn't call osp.abspath, or add a flag to the existing function.
@Byron, I was double checking how Git handles this and it turns out it doesn't do ~ and env var expansion, it only does the equivalent of osp.normpath via strbuf_realpath. I'm wondering if GitPython should match, which means my existing code will work by replacing the call to expand_path with osp.normpath. Or should I do what I mentioned above and use expand_path (without its call to osp.abspath) just in case Git decides to support expansions of the gitdir in the future?
Sorry, something went wrong.
Copy link
Copy Markdown
Member
There was a problem hiding this comment.
GitPython should always strive to do what Git does. It's just historically has not 😅.
So let's go with osp.normpath instead.
Sorry, something went wrong.
Comment thread
test/test_repo.py
Outdated
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)", | ||
| ) |
Copy link
Copy Markdown
Contributor
Author
There was a problem hiding this comment.
this is a good suggestion. It's also done at test_index_mutation so I'll open a separate PR to fix that as well.
Sorry, something went wrong.
Byron
reviewed
May 12, 2026
Byron
left a comment
Copy link
Copy Markdown
Member
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.
Sorry, something went wrong.
Byron
marked this pull request as draft
May 12, 2026 22:18
Git only normalizes relative references in `gitdir`[1], so do the same. [1]: https://github.com/git/git/blob/v2.54.0/setup.c#L1012-L1025
elovelan
force-pushed
the
relative_worktree_support
branch
from
4f86497 to
4a599e3
Compare
May 15, 2026 02:04
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 normalizing it. Absolute paths are unaffected because `os.path.join` ignores the prefix when joined with an absolute path.
elovelan
force-pushed
the
relative_worktree_support
branch
from
4a599e3 to
29c9861
Compare
May 15, 2026 02:09
elovelan
marked this pull request as ready for review
May 15, 2026 03:44
Copy link
Copy Markdown
Contributor
Author
Sorry, something went wrong.
Byron
approved these changes
May 16, 2026
Byron
left a comment
Copy link
Copy Markdown
Member
There was a problem hiding this comment.
Great work, thanks!
Sorry, something went wrong.
736-c41-2c1-e464fc974
pushed a commit
to Swiss-Armed-Forces/Loom
that referenced
this pull request
Aug 16, 2026
This MR contains the following updates: | Package | Type | Update | Change | OpenSSF | |---|---|---|---|---| | [gitpython](https://github.com/gitpython-developers/GitPython) | dev | patch | `3.1.50` → `3.1.52` | [](https://securityscorecards.dev/viewer/?uri=github.com/gitpython-developers/GitPython) | --- ### Release Notes <details> <summary>gitpython-developers/GitPython (gitpython)</summary> ### [`v3.1.52`](https://github.com/gitpython-developers/GitPython/releases/tag/3.1.52): Security [Compare Source](gitpython-developers/GitPython@3.1.51...3.1.52) <GHSA-rwj8-pgh3-r573>: Environment-variable exfiltration via os.path.expandvars() on Repo.clone\_from() URL #### What's Changed - Skip cross-drive relative config test on Windows by [@​Byron](https://github.com/Byron) in [#​2171](gitpython-developers/GitPython#2171) - fix: preserve literal clone URLs by [@​Byron](https://github.com/Byron) in [#​2172](gitpython-developers/GitPython#2172) **Full Changelog**: <gitpython-developers/GitPython@3.1.51...3.1.52> ### [`v3.1.51`](https://github.com/gitpython-developers/GitPython/releases/tag/3.1.51): - Security [Compare Source](gitpython-developers/GitPython@3.1.50...3.1.51) #### What's Changed - Add AI-disclosure and quality requirements to the contribution guidelines by [@​Byron](https://github.com/Byron) in [#​2143](gitpython-developers/GitPython#2143) - docs(cmd): clarify Git.execute() string vs list command argument by [@​mvanhorn](https://github.com/mvanhorn) in [#​2144](gitpython-developers/GitPython#2144) - Rewrite Git.execute() command parameter docstring per [#​2146](gitpython-developers/GitPython#2146) by [@​EliahKagan](https://github.com/EliahKagan) in [#​2147](gitpython-developers/GitPython#2147) - Document init script behavior with multiple master remotes by [@​EliahKagan](https://github.com/EliahKagan) in [#​2148](gitpython-developers/GitPython#2148) - Bump git/ext/gitdb from `335c0f6` to `0a019a2` by [@​dependabot](https://github.com/dependabot)\[bot] in [#​2149](gitpython-developers/GitPython#2149) - Support relative worktree paths (git 2.48+ worktree.useRelativePaths) by [@​elovelan](https://github.com/elovelan) in [#​2151](gitpython-developers/GitPython#2151) - Defer xfail condition evaluation with xfail\_if\_raises context manager by [@​elovelan](https://github.com/elovelan) in [#​2153](gitpython-developers/GitPython#2153) - Run more submodule tests on Cygwin (fix flaky xfails) by [@​EliahKagan](https://github.com/EliahKagan) in [#​2154](gitpython-developers/GitPython#2154) - Cut xtrace noise from POSIX-ownership diagnostic steps by [@​EliahKagan](https://github.com/EliahKagan) in [#​2156](gitpython-developers/GitPython#2156) - Support index diffs against the empty tree by [@​puneetdixit200](https://github.com/puneetdixit200) in [#​2155](gitpython-developers/GitPython#2155) - refactor: seperate out Progress type by [@​LoeschMaximilian](https://github.com/LoeschMaximilian) in [#​2157](gitpython-developers/GitPython#2157) - Bump <https://github.com/astral-sh/ruff-pre-commit> from v0.15.12 to 0.15.15 in the pre-commit group by [@​dependabot](https://github.com/dependabot)\[bot] in [#​2160](gitpython-developers/GitPython#2160) - Bump actions/checkout from 6 to 7 by [@​dependabot](https://github.com/dependabot)\[bot] in [#​2164](gitpython-developers/GitPython#2164) - Bump git/ext/gitdb from `0a019a2` to `4950ea9` by [@​dependabot](https://github.com/dependabot)\[bot] in [#​2165](gitpython-developers/GitPython#2165) - Bump <https://github.com/astral-sh/ruff-pre-commit> from v0.15.15 to 0.15.20 in the pre-commit group by [@​dependabot](https://github.com/dependabot)\[bot] in [#​2166](gitpython-developers/GitPython#2166) - Add Commit.is\_shallow property; document stats() limitation at shallow boundary by [@​harshitayadavv](https://github.com/harshitayadavv) in [#​2167](gitpython-developers/GitPython#2167) - Allow relative config paths with includes by [@​Byron](https://github.com/Byron) in [#​2169](gitpython-developers/GitPython#2169) - Reject abbreviated forms of unsafe git options by [@​Byron](https://github.com/Byron) in [#​2168](gitpython-developers/GitPython#2168) - guard unsafe git command options by [@​Byron](https://github.com/Byron) in [#​2163](gitpython-developers/GitPython#2163) #### New Contributors - [@​elovelan](https://github.com/elovelan) made their first contribution in [#​2151](gitpython-developers/GitPython#2151) - [@​puneetdixit200](https://github.com/puneetdixit200) made their first contribution in [#​2155](gitpython-developers/GitPython#2155) - [@​LoeschMaximilian](https://github.com/LoeschMaximilian) made their first contribution in [#​2157](gitpython-developers/GitPython#2157) - [@​harshitayadavv](https://github.com/harshitayadavv) made their first contribution in [#​2167](gitpython-developers/GitPython#2167) **Full Changelog**: <gitpython-developers/GitPython@3.1.50...3.1.51> </details> --- - [ ] <!-- rebase-check -->If you want to rebase/retry this MR, check this box --- This MR has been generated by [Mend Renovate](https://github.com/renovatebot/renovate). <!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiI0My4yNzAuMCIsInVwZGF0ZWRJblZlciI6IjQzLjI3MC4wIiwidGFyZ2V0QnJhbmNoIjoibWFpbiIsImxhYmVscyI6WyJkZXBlbmRlbmNpZXMiLCJyZW5vdmF0ZSJdfQ==--> See merge request swiss-armed-forces/cyber-command/cea/loom!679 Co-authored-by: Loom MR Pipeline Trigger <group_103951964_bot_9504bb8dead6d4e406ad817a607f24be@noreply.gitlab.com>
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
Reviewers
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.useRelativePaths config option. When enabled, git worktree add writes a relative gitdir: into the worktree's .git file — relative to the directory containing that .git file.
GitPython's Repo.__init__ previously passed the value of that gitdir: line straight through expand_path, which calls os.path.abspath against 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 gitdir against curpath (the directory containing the .git file) before expanding. Absolute paths — i.e. the pre-2.48 default — are unaffected, because os.path.join ignores 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
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).