Add optional shallow submodule checkouts

[abhinavgautam01]

Closes #11

Summary

• add a backward-compatible EnsureWithOptions API with opt-in recursive submodule support
• initialize and update submodules recursively at depth 1 after both initial clones and subsequent fetches
• keep submodule operations best-effort so unavailable or unsupported submodules do not fail the parent checkout
• continue propagating context cancellation
• add Cache.RecurseSubmodules so cached checkouts can include shallow submodule contents
• document the new API and cache option

Testing

• go build -v ./...
• go vet ./...
• go test -v -race ./...
• go test -v -race ./... in the gogit module
• combined-workspace race tests for gogit
• golangci-lint v2.13.1 for both modules (0 issues)
• gofmt and git diff --check

Includes integration coverage for opt-in behavior, shallow initialization, submodule updates, cache copies, best-effort failures and context cancellation.

[Copilot]

Pull request overview

This PR adds an opt-in path to shallow-initialize and update Git submodules (recursively, depth 1) as part of the existing “clone-or-fetch + reset” workflow, without changing default behavior for existing callers. It introduces a new options-based API surface and extends the cache feature so cached checkouts can include best-effort submodule contents.

Changes:

• Add EnsureWithOptions + EnsureOptions (backward-compatible with existing Ensure), with opt-in RecurseSubmodules.
• Perform best-effort git submodule update --init --recursive --depth 1 after both initial clone and later fetch/reset updates (while still propagating context cancellation).
• Add Cache.RecurseSubmodules and tests/docs to support copying shallow submodule contents into cached destinations.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
README.md	Documents EnsureWithOptions submodule opt-in behavior and the new cache flag.
ensure.go	Adds options-based API and implements best-effort recursive shallow submodule updates.
ensure_test.go	Adds integration + unit tests for opt-in submodule behavior, best-effort failures, and cancellation.
doc.go	Updates package docs to mention optional shallow submodules.
cache.go	Adds Cache.RecurseSubmodules and wires it into cache preparation via EnsureWithOptions.
cache_test.go	Adds coverage for cache copies including submodule contents.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.