You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
feat: inherit sparse-checkout in new worktrees (#186)
* feat: inherit sparse-checkout in new worktrees
When creating a new worktree from one with sparse-checkout enabled,
the new worktree inherits the cone pattern automatically. Controlled
by gtr.sparse.inherit config (default on) and --sparse/--no-sparse
flags. Adds reusable helpers for sparse-checkout replication.
* fix(sparse): address CodeRabbit review feedback on sparse-checkout inheritance
- Preserve slash-separated branch paths in _worktree_path_for_ref
- Allow fallback to top-level worktree when matching worktree is not sparse
- Add Git 2.25+ guard for sparse-checkout support with full checkout fallback
- Fix non-cone mode to use init --no-cone (git defaults to cone mode)
- Improve error handling: failed sparse inheritance now falls back to full
checkout and hard-errors if that fails, instead of leaving --no-checkout
worktree empty
- Add tests for slash refs, non-cone inheritance, and sparse config precedence
* fix: harden sparse-checkout inheritance
* fix: support pre-2.20 config lookup
* fix: align sparse sources with git refs
---------
Co-authored-by: Tom Elizaga <tom.elizaga@gmail.com>
When working in a large monorepo, a base worktree often uses [sparse-checkout](https://git-scm.com/docs/git-sparse-checkout) to materialize only a slice of the tree. `gtr` carries that slice into the worktrees you branch off it, so feature worktrees stay lean instead of exploding into the full repo.
209
+
210
+
```bash
211
+
# my-app is a sparse worktree checking out only apps/my-app + packages.
212
+
# A feature branch off it inherits the same cone automatically:
213
+
git gtr new my-app-feature-xyz --from my-app
214
+
215
+
# The new worktree contains only the inherited sparse slice:
216
+
ls "$(git gtr go my-app-feature-xyz)"
217
+
git -C "$(git gtr go my-app-feature-xyz)" sparse-checkout list
218
+
219
+
# Opt out for a single command (full checkout):
220
+
git gtr new big-refactor --from my-app --no-sparse
221
+
```
222
+
223
+
**How it works:**
224
+
225
+
- On Git 2.36+, gtr inspects the worktree holding the base ref (`--from`, falling back to the current worktree). If it has valid sparse-checkout settings, gtr creates the new worktree from that source so Git copies its patterns and per-worktree config before checkout — the full tree is never written to disk.
226
+
- Git 2.17–2.35 keeps the existing full-checkout behavior. An explicit `--sparse` request prints a warning that inheritance requires Git 2.36+.
227
+
- Controlled by `gtr.sparse.inherit` (default on). Use `--sparse` / `--no-sparse` to override per command.
228
+
- Full-checkout repositories are unaffected — they always get a full checkout.
229
+
230
+
> [!NOTE]
231
+
> Sparse-checkout is per-worktree, not per-branch. Inheriting "from `my-app`" copies the live sparse settings and worktree-specific Git config of the `my-app` worktree, not anything stored on the branch itself. If the same branch is checked out more than once, gtr prefers the current matching worktree; otherwise it warns and creates a full checkout rather than choosing arbitrarily.
232
+
233
+
---
234
+
205
235
[Back to README](../README.md) | [Configuration](configuration.md) | [Troubleshooting](troubleshooting.md)
If the worktree you branch from uses [sparse-checkout](https://git-scm.com/docs/git-sparse-checkout) (e.g. a slice of a large monorepo), `gtr` can give the new worktree the same narrowed working tree instead of an expensive full checkout.
116
+
117
+
```bash
118
+
# Inherit sparse-checkout from the base worktree (default: true)
119
+
gtr.sparse.inherit=true
120
+
```
121
+
122
+
On Git 2.36+, `git gtr new` looks at the worktree holding the base ref (the `--from` target, falling back to the current worktree). If that worktree has valid sparse-checkout settings, gtr runs worktree creation from that source so Git copies its patterns and per-worktree config before checkout. The full tree is never materialized. Git 2.17–2.35 retains full-checkout behavior; explicit `--sparse` requests print a version warning.
123
+
124
+
Per-command overrides:
125
+
126
+
```bash
127
+
# Force inheritance even if gtr.sparse.inherit is off
128
+
git gtr new feature-xyz --from my-app --sparse
129
+
130
+
# Force a full checkout even if gtr.sparse.inherit is on
131
+
git gtr new feature-xyz --from my-app --no-sparse
132
+
```
133
+
134
+
> [!NOTE]
135
+
> Sparse-checkout is stored per-worktree, not per-branch. "Inherit from `my-app`" means inherit the live sparse settings and worktree-specific Git config of the `my-app` *worktree*. Ambiguous duplicate-branch worktrees fall back to a full checkout instead of choosing a source arbitrarily.
136
+
137
+
---
138
+
113
139
## Provider Settings
114
140
115
141
The `clean --merged` and `clean --closed` commands auto-detect your hosting provider from the `origin` remote URL (`github.com` → GitHub, `gitlab.com` → GitLab). For self-hosted instances, set the provider explicitly:
0 commit comments