Repository navigation
fix: validate checkout and submodule clone arguments - #2347
Merged
Merged
Conversation
<!-- agent --> Triaging `GHSA-j3hg-fv33-37rw` revealed that `Head.checkout()` did not validate its documented boolean `force` parameter before assembling the Git command. Dynamically typed callers could therefore supply values outside the flag's contract and alter checkout argument parsing. Reject non-boolean values with `TypeError` before any Git call, including when unsafe options are explicitly allowed. Preserve `True` and `False` behavior instead of coercing strings into permission to discard local changes. Document the exception and compatibility change. The regression failed before the fix for an option-shaped string reaching the command runner. It covers positional and keyword calls, both unsafe option settings and short-option formatting modes, strings, bytes, sequences, integers, and `None`. No private advisory reproduction is included. Git reference: local source at `6de20f6092dcf9bdb1c8efe03db4b70c82b423dd`, `Documentation/git-checkout.adoc` and `builtin/checkout.c` specify `--force` as a no-argument switch (`OPT__FORCE` / `PARSE_OPT_NOARG`). Tests used Git `2.54.0 (Apple Git-157)` and GixPython `0.3.0`. Assisted-by: GPT 6.1 Sol Co-authored-by: GPT 6.1 Sol <codex@openai.com>
Byron
marked this pull request as ready for review
November 15, 2026 12:06
Contributor
There was a problem hiding this comment.
🟢 Approval recommended
No active review issues are reported for the checkout and submodule input-validation changes.
No open issues 🎉
What changed in this PR
This PR strengthens input validation in GitPython’s checkout and submodule APIs, rejecting invalid flag and depth values before Git execution.
Changes:
- Require booleans for checkout
forceand submoduleno_checkout. - Centralize submodule depth validation to require a positive, non-boolean integer.
- Add regression coverage and record the security advisory in the changelog.
| File | Description |
|---|---|
test/test_submodule.py |
Tests invalid checkout flags and clone depths across submodule entry points. |
test/test_refs.py |
Tests invalid checkout force values, including positional calls and unsafe opt-in. |
git/refs/head.py |
Validates force before checkout processing. |
git/objects/submodule/base.py |
Validates no_checkout and depth before repository operations; updates parameter documentation. |
doc/source/changes.rst |
Adds the security advisory link. |
Review effort: Balanced
<!-- agent --> An audit of higher-level Git calls prompted by `GHSA-j3hg-fv33-37rw` found that `Submodule.add()` passed its documented boolean `no_checkout` parameter directly to clone's short `-n` option. Non-boolean strings or sequences could introduce additional Git arguments. The manual clone path also accepted boolean `depth` values as integers, allowing `True` to become a bare `--depth` instead of a numeric option value. Require boolean `no_checkout` before repository or filesystem operations. Move the existing positive, non-boolean integer depth validation before path selection and reuse it for both direct submodule add and manual cloning. `Repo.create_submodule()` receives the same protection through its existing delegation. Keep valid booleans and positive depths intact; invalid values are rejected instead of coerced into behavior flags. The regression tests failed before the fix and now verify rejection before any Git process for both entry points, positional and keyword flags, unsafe opt-in, strings, bytes, sequences, and invalid numeric depths. The source audit identified no additional named boolean parameter forwarded raw into a short no-argument flag in refs, repo, remote, diff, index, or the remaining object/submodule operations. Arbitrary Git keyword options remain the explicit command-option interface. Git baseline: local source at `6de20f6092dcf9bdb1c8efe03db4b70c82b423dd` registers clone's `--no-checkout` as `OPT_BOOL` / `PARSE_OPT_NOARG`, while `--depth` requires a numeric value of at least one (`builtin/clone.c`, `transport.c`, and `Documentation/git-clone.adoc`). Assisted-by: GPT 6.1 Sol Co-authored-by: GPT 6.1 Sol <codex@openai.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
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.
Tasks
This section is for Byron only. Models continuing this PR must not add, remove, check, uncheck, rename, or reorder checkboxes here.
Everything below this line was generated by
Codex (model version unavailable).Created by Codex on behalf of Byron. Byron will review before this is ready to merge.
This work came from triaging a private input-validation advisory affecting GitPython applications that pass dynamically typed values into checkout flags. Auditing the other higher-level Git calls found another flag forwarded without checking its type.
Head.checkout(force=...)andSubmodule.add(no_checkout=...)now require booleans before any Git call. Non-boolean values raiseTypeError, including positional calls and calls with unsafe options enabled.Repo.create_submodule()receives the same protection through its existing delegation. ValidTrueandFalsebehavior is preserved.Submodule clone depth also requires a positive, non-boolean integer on both add paths. This prevents
depth=Truefrom becoming a bare Git option and replaces duplicated, inconsistent checks with one input check before repository operations.Advisory summary
GHSA-j3hg-fv33-37rw: medium severity; package
GitPythonin the pip ecosystem; reported affected range<= 3.2.1. No patched version or CVE is assigned yet. The advisory is private, so this description and regression cases omit its private reproduction and impact details.Validation
The new regression tests failed before the fixes and now reject invalid values before Git process execution. They cover strings, bytes, sequences, integers, and
None, positional and keyword calls, unsafe opt-in, both submodule entry points, and invalid depths on both clone paths.git diff --checkpassed.6de20f6092dcf9bdb1c8efe03db4b70c82b423dd. Tests used Git2.54.0 (Apple Git-157)and GixPython0.3.0.