Google Git
Sign in
chromium / external / gitster / git-htmldocs / acfb98de3d9e0df8963c76d7503dd30738beb75b / . / git-sparse-checkout.html
blob: 56f600cc5df54b7a799cb13cd4b8d41abd996dd1 [file] [log] [blame]
Junio C Hamano944ce252018-05-30 22:25:26[diff] [blame]1<?xml version="1.0" encoding="UTF-8"?>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
3 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
4<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
5<head>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]6<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
Junio C Hamanoa85030a2022-07-27 16:48:21[diff] [blame]7<meta name="generator" content="AsciiDoc 10.2.0" />
Junio C Hamano2f5a9892019-12-25 21:12:55[diff] [blame]8<title>git-sparse-checkout(1)</title>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]9<style type="text/css">
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]10/* Shared CSS for AsciiDoc xhtml11 and html5 backends */
11
12/* Default font. */
13body {
14 font-family: Georgia,serif;
15}
16
17/* Title font. */
18h1, h2, h3, h4, h5, h6,
19div.title, caption.title,
20thead, p.table.header,
21#toctitle,
22#author, #revnumber, #revdate, #revremark,
23#footer {
24 font-family: Arial,Helvetica,sans-serif;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]25}
26
27body {
28 margin: 1em 5% 1em 5%;
29}
30
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]31a {
32 color: blue;
33 text-decoration: underline;
34}
35a:visited {
36 color: fuchsia;
37}
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]38
39em {
40 font-style: italic;
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]41 color: navy;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]42}
43
44strong {
45 font-weight: bold;
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]46 color: #083194;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]47}
48
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]49h1, h2, h3, h4, h5, h6 {
50 color: #527bbd;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]51 margin-top: 1.2em;
52 margin-bottom: 0.5em;
53 line-height: 1.3;
54}
55
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]56h1, h2, h3 {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]57 border-bottom: 2px solid silver;
58}
59h2 {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]60 padding-top: 0.5em;
61}
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]62h3 {
63 float: left;
64}
65h3 + * {
66 clear: left;
67}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]68h5 {
69 font-size: 1.0em;
70}
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]71
72div.sectionbody {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]73 margin-left: 0;
74}
75
76hr {
77 border: 1px solid silver;
78}
79
80p {
81 margin-top: 0.5em;
82 margin-bottom: 0.5em;
83}
84
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]85ul, ol, li > p {
86 margin-top: 0;
87}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]88ul > li { color: #aaa; }
89ul > li > * { color: black; }
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]90
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]91.monospaced, code, pre {
92 font-family: "Courier New", Courier, monospace;
93 font-size: inherit;
94 color: navy;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]95 padding: 0;
96 margin: 0;
97}
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]98pre {
99 white-space: pre-wrap;
100}
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]101
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]102#author {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]103 color: #527bbd;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]104 font-weight: bold;
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]105 font-size: 1.1em;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]106}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]107#email {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]108}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]109#revnumber, #revdate, #revremark {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]110}
111
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]112#footer {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]113 font-size: small;
114 border-top: 2px solid silver;
115 padding-top: 0.5em;
116 margin-top: 4.0em;
117}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]118#footer-text {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]119 float: left;
120 padding-bottom: 0.5em;
121}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]122#footer-badges {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]123 float: right;
124 padding-bottom: 0.5em;
125}
126
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]127#preamble {
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]128 margin-top: 1.5em;
129 margin-bottom: 1.5em;
130}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]131div.imageblock, div.exampleblock, div.verseblock,
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]132div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
133div.admonitionblock {
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]134 margin-top: 1.0em;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]135 margin-bottom: 1.5em;
136}
137div.admonitionblock {
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]138 margin-top: 2.0em;
139 margin-bottom: 2.0em;
140 margin-right: 10%;
141 color: #606060;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]142}
143
144div.content { /* Block element content. */
145 padding: 0;
146}
147
148/* Block element titles. */
149div.title, caption.title {
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]150 color: #527bbd;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]151 font-weight: bold;
152 text-align: left;
153 margin-top: 1.0em;
154 margin-bottom: 0.5em;
155}
156div.title + * {
157 margin-top: 0;
158}
159
160td div.title:first-child {
161 margin-top: 0.0em;
162}
163div.content div.title:first-child {
164 margin-top: 0.0em;
165}
166div.content + div.title {
167 margin-top: 0.0em;
168}
169
170div.sidebarblock > div.content {
171 background: #ffffee;
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]172 border: 1px solid #dddddd;
173 border-left: 4px solid #f0f0f0;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]174 padding: 0.5em;
175}
176
177div.listingblock > div.content {
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]178 border: 1px solid #dddddd;
179 border-left: 5px solid #f0f0f0;
180 background: #f8f8f8;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]181 padding: 0.5em;
182}
183
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]184div.quoteblock, div.verseblock {
185 padding-left: 1.0em;
186 margin-left: 1.0em;
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]187 margin-right: 10%;
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]188 border-left: 5px solid #f0f0f0;
189 color: #888;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]190}
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]191
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]192div.quoteblock > div.attribution {
193 padding-top: 0.5em;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]194 text-align: right;
195}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]196
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]197div.verseblock > pre.content {
198 font-family: inherit;
199 font-size: inherit;
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]200}
201div.verseblock > div.attribution {
202 padding-top: 0.75em;
203 text-align: left;
204}
205/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]206div.verseblock + div.attribution {
207 text-align: left;
208}
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]209
210div.admonitionblock .icon {
211 vertical-align: top;
212 font-size: 1.1em;
213 font-weight: bold;
214 text-decoration: underline;
215 color: #527bbd;
216 padding-right: 0.5em;
217}
218div.admonitionblock td.content {
219 padding-left: 0.5em;
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]220 border-left: 3px solid #dddddd;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]221}
222
223div.exampleblock > div.content {
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]224 border-left: 3px solid #dddddd;
225 padding-left: 0.5em;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]226}
227
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]228div.imageblock div.content { padding-left: 0; }
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]229span.image img { border-style: none; vertical-align: text-bottom; }
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]230a.image:visited { color: white; }
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]231
232dl {
233 margin-top: 0.8em;
234 margin-bottom: 0.8em;
235}
236dt {
237 margin-top: 0.5em;
238 margin-bottom: 0;
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]239 font-style: normal;
240 color: navy;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]241}
242dd > *:first-child {
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]243 margin-top: 0.1em;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]244}
245
246ul, ol {
247 list-style-position: outside;
248}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]249ol.arabic {
250 list-style-type: decimal;
251}
252ol.loweralpha {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]253 list-style-type: lower-alpha;
254}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]255ol.upperalpha {
256 list-style-type: upper-alpha;
257}
258ol.lowerroman {
259 list-style-type: lower-roman;
260}
261ol.upperroman {
262 list-style-type: upper-roman;
263}
264
265div.compact ul, div.compact ol,
266div.compact p, div.compact p,
267div.compact div, div.compact div {
268 margin-top: 0.1em;
269 margin-bottom: 0.1em;
270}
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]271
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]272tfoot {
273 font-weight: bold;
274}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]275td > div.verse {
276 white-space: pre;
277}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]278
279div.hdlist {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]280 margin-top: 0.8em;
281 margin-bottom: 0.8em;
282}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]283div.hdlist tr {
284 padding-bottom: 15px;
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]285}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]286dt.hdlist1.strong, td.hdlist1.strong {
287 font-weight: bold;
288}
289td.hdlist1 {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]290 vertical-align: top;
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]291 font-style: normal;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]292 padding-right: 0.8em;
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]293 color: navy;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]294}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]295td.hdlist2 {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]296 vertical-align: top;
297}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]298div.hdlist.compact tr {
299 margin: 0;
300 padding-bottom: 0;
301}
302
303.comment {
304 background: yellow;
305}
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]306
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]307.footnote, .footnoteref {
308 font-size: 0.8em;
309}
310
311span.footnote, span.footnoteref {
312 vertical-align: super;
313}
314
315#footnotes {
316 margin: 20px 0 20px 0;
317 padding: 7px 0 0 0;
318}
319
320#footnotes div.footnote {
321 margin: 0 0 5px 0;
322}
323
324#footnotes hr {
325 border: none;
326 border-top: 1px solid silver;
327 height: 1px;
328 text-align: left;
329 margin-left: 0;
330 width: 20%;
331 min-width: 100px;
332}
333
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]334div.colist td {
335 padding-right: 0.5em;
336 padding-bottom: 0.3em;
337 vertical-align: top;
338}
339div.colist td img {
340 margin-top: 0.3em;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]341}
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]342
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]343@media print {
344 #footer-badges { display: none; }
345}
346
347#toc {
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]348 margin-bottom: 2.5em;
349}
350
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]351#toctitle {
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]352 color: #527bbd;
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]353 font-size: 1.1em;
354 font-weight: bold;
355 margin-top: 1.0em;
356 margin-bottom: 0.1em;
357}
358
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]359div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]360 margin-top: 0;
361 margin-bottom: 0;
362}
363div.toclevel2 {
364 margin-left: 2em;
365 font-size: 0.9em;
366}
367div.toclevel3 {
368 margin-left: 4em;
369 font-size: 0.9em;
370}
371div.toclevel4 {
372 margin-left: 6em;
373 font-size: 0.9em;
374}
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]375
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]376span.aqua { color: aqua; }
377span.black { color: black; }
378span.blue { color: blue; }
379span.fuchsia { color: fuchsia; }
380span.gray { color: gray; }
381span.green { color: green; }
382span.lime { color: lime; }
383span.maroon { color: maroon; }
384span.navy { color: navy; }
385span.olive { color: olive; }
386span.purple { color: purple; }
387span.red { color: red; }
388span.silver { color: silver; }
389span.teal { color: teal; }
390span.white { color: white; }
391span.yellow { color: yellow; }
392
393span.aqua-background { background: aqua; }
394span.black-background { background: black; }
395span.blue-background { background: blue; }
396span.fuchsia-background { background: fuchsia; }
397span.gray-background { background: gray; }
398span.green-background { background: green; }
399span.lime-background { background: lime; }
400span.maroon-background { background: maroon; }
401span.navy-background { background: navy; }
402span.olive-background { background: olive; }
403span.purple-background { background: purple; }
404span.red-background { background: red; }
405span.silver-background { background: silver; }
406span.teal-background { background: teal; }
407span.white-background { background: white; }
408span.yellow-background { background: yellow; }
409
410span.big { font-size: 2em; }
411span.small { font-size: 0.6em; }
412
413span.underline { text-decoration: underline; }
414span.overline { text-decoration: overline; }
415span.line-through { text-decoration: line-through; }
416
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]417div.unbreakable { page-break-inside: avoid; }
418
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]419
420/*
421 * xhtml11 specific
422 *
423 * */
424
425div.tableblock {
426 margin-top: 1.0em;
427 margin-bottom: 1.5em;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]428}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]429div.tableblock > table {
430 border: 3px solid #527bbd;
431}
432thead, p.table.header {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]433 font-weight: bold;
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]434 color: #527bbd;
435}
436p.table {
437 margin-top: 0;
438}
Junio C Hamano725b0da2020-01-22 22:02:40[diff] [blame]439/* Because the table frame attribute is overridden by CSS in most browsers. */
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]440div.tableblock > table[frame="void"] {
441 border-style: none;
442}
443div.tableblock > table[frame="hsides"] {
444 border-left-style: none;
445 border-right-style: none;
446}
447div.tableblock > table[frame="vsides"] {
448 border-top-style: none;
449 border-bottom-style: none;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]450}
451
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]452
453/*
454 * html5 specific
455 *
456 * */
457
458table.tableblock {
459 margin-top: 1.0em;
460 margin-bottom: 1.5em;
461}
462thead, p.tableblock.header {
463 font-weight: bold;
464 color: #527bbd;
465}
466p.tableblock {
467 margin-top: 0;
468}
469table.tableblock {
470 border-width: 3px;
471 border-spacing: 0px;
472 border-style: solid;
473 border-color: #527bbd;
474 border-collapse: collapse;
475}
476th.tableblock, td.tableblock {
477 border-width: 1px;
478 padding: 4px;
479 border-style: solid;
480 border-color: #527bbd;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]481}
482
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]483table.tableblock.frame-topbot {
484 border-left-style: hidden;
485 border-right-style: hidden;
486}
487table.tableblock.frame-sides {
488 border-top-style: hidden;
489 border-bottom-style: hidden;
490}
491table.tableblock.frame-none {
492 border-style: hidden;
493}
494
495th.tableblock.halign-left, td.tableblock.halign-left {
496 text-align: left;
497}
498th.tableblock.halign-center, td.tableblock.halign-center {
499 text-align: center;
500}
501th.tableblock.halign-right, td.tableblock.halign-right {
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]502 text-align: right;
503}
504
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]505th.tableblock.valign-top, td.tableblock.valign-top {
506 vertical-align: top;
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]507}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]508th.tableblock.valign-middle, td.tableblock.valign-middle {
509 vertical-align: middle;
510}
511th.tableblock.valign-bottom, td.tableblock.valign-bottom {
512 vertical-align: bottom;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]513}
514
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]515
516/*
517 * manpage specific
518 *
519 * */
520
521body.manpage h1 {
522 padding-top: 0.5em;
523 padding-bottom: 0.5em;
524 border-top: 2px solid silver;
525 border-bottom: 2px solid silver;
526}
527body.manpage h2 {
528 border-style: none;
529}
530body.manpage div.sectionbody {
531 margin-left: 3em;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]532}
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]533
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]534@media print {
535 body.manpage div#toc { display: none; }
536}
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]537
538
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]539</style>
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]540<script type="text/javascript">
541/*<![CDATA[*/
Junio C Hamano2b153182021-12-15 21:00:31[diff] [blame]542var asciidoc = { // Namespace.
543
544/////////////////////////////////////////////////////////////////////
545// Table Of Contents generator
546/////////////////////////////////////////////////////////////////////
547
548/* Author: Mihai Bazon, September 2002
549 * http://students.infoiasi.ro/~mishoo
550 *
551 * Table Of Content generator
552 * Version: 0.4
553 *
554 * Feel free to use this script under the terms of the GNU General Public
555 * License, as long as you do not remove or alter this notice.
556 */
557
558 /* modified by Troy D. Hanson, September 2006. License: GPL */
559 /* modified by Stuart Rackham, 2006, 2009. License: GPL */
560
561// toclevels = 1..4.
562toc: function (toclevels) {
563
564 function getText(el) {
565 var text = "";
566 for (var i = el.firstChild; i != null; i = i.nextSibling) {
567 if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
568 text += i.data;
569 else if (i.firstChild != null)
570 text += getText(i);
571 }
572 return text;
573 }
574
575 function TocEntry(el, text, toclevel) {
576 this.element = el;
577 this.text = text;
578 this.toclevel = toclevel;
579 }
580
581 function tocEntries(el, toclevels) {
582 var result = new Array;
583 var re = new RegExp('[hH]([1-'+(toclevels+1)+'])');
584 // Function that scans the DOM tree for header elements (the DOM2
585 // nodeIterator API would be a better technique but not supported by all
586 // browsers).
587 var iterate = function (el) {
588 for (var i = el.firstChild; i != null; i = i.nextSibling) {
589 if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
590 var mo = re.exec(i.tagName);
591 if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
592 result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
593 }
594 iterate(i);
595 }
596 }
597 }
598 iterate(el);
599 return result;
600 }
601
602 var toc = document.getElementById("toc");
603 if (!toc) {
604 return;
605 }
606
607 // Delete existing TOC entries in case we're reloading the TOC.
608 var tocEntriesToRemove = [];
609 var i;
610 for (i = 0; i < toc.childNodes.length; i++) {
611 var entry = toc.childNodes[i];
612 if (entry.nodeName.toLowerCase() == 'div'
613 && entry.getAttribute("class")
614 && entry.getAttribute("class").match(/^toclevel/))
615 tocEntriesToRemove.push(entry);
616 }
617 for (i = 0; i < tocEntriesToRemove.length; i++) {
618 toc.removeChild(tocEntriesToRemove[i]);
619 }
620
621 // Rebuild TOC entries.
622 var entries = tocEntries(document.getElementById("content"), toclevels);
623 for (var i = 0; i < entries.length; ++i) {
624 var entry = entries[i];
625 if (entry.element.id == "")
626 entry.element.id = "_toc_" + i;
627 var a = document.createElement("a");
628 a.href = "#" + entry.element.id;
629 a.appendChild(document.createTextNode(entry.text));
630 var div = document.createElement("div");
631 div.appendChild(a);
632 div.className = "toclevel" + entry.toclevel;
633 toc.appendChild(div);
634 }
635 if (entries.length == 0)
636 toc.parentNode.removeChild(toc);
637},
638
639
640/////////////////////////////////////////////////////////////////////
641// Footnotes generator
642/////////////////////////////////////////////////////////////////////
643
644/* Based on footnote generation code from:
645 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
646 */
647
648footnotes: function () {
649 // Delete existing footnote entries in case we're reloading the footnodes.
650 var i;
651 var noteholder = document.getElementById("footnotes");
652 if (!noteholder) {
653 return;
654 }
655 var entriesToRemove = [];
656 for (i = 0; i < noteholder.childNodes.length; i++) {
657 var entry = noteholder.childNodes[i];
658 if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote")
659 entriesToRemove.push(entry);
660 }
661 for (i = 0; i < entriesToRemove.length; i++) {
662 noteholder.removeChild(entriesToRemove[i]);
663 }
664
665 // Rebuild footnote entries.
666 var cont = document.getElementById("content");
667 var spans = cont.getElementsByTagName("span");
668 var refs = {};
669 var n = 0;
670 for (i=0; i<spans.length; i++) {
671 if (spans[i].className == "footnote") {
672 n++;
673 var note = spans[i].getAttribute("data-note");
674 if (!note) {
675 // Use [\s\S] in place of . so multi-line matches work.
676 // Because JavaScript has no s (dotall) regex flag.
677 note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
678 spans[i].innerHTML =
679 "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
680 "' title='View footnote' class='footnote'>" + n + "</a>]";
681 spans[i].setAttribute("data-note", note);
682 }
683 noteholder.innerHTML +=
684 "<div class='footnote' id='_footnote_" + n + "'>" +
685 "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
686 n + "</a>. " + note + "</div>";
687 var id =spans[i].getAttribute("id");
688 if (id != null) refs["#"+id] = n;
689 }
690 }
691 if (n == 0)
692 noteholder.parentNode.removeChild(noteholder);
693 else {
694 // Process footnoterefs.
695 for (i=0; i<spans.length; i++) {
696 if (spans[i].className == "footnoteref") {
697 var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
698 href = href.match(/#.*/)[0]; // Because IE return full URL.
699 n = refs[href];
700 spans[i].innerHTML =
701 "[<a href='#_footnote_" + n +
702 "' title='View footnote' class='footnote'>" + n + "</a>]";
703 }
704 }
705 }
706},
707
708install: function(toclevels) {
709 var timerId;
710
711 function reinstall() {
712 asciidoc.footnotes();
713 if (toclevels) {
714 asciidoc.toc(toclevels);
715 }
716 }
717
718 function reinstallAndRemoveTimer() {
719 clearInterval(timerId);
720 reinstall();
721 }
722
723 timerId = setInterval(reinstall, 500);
724 if (document.addEventListener)
725 document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
726 else
727 window.onload = reinstallAndRemoveTimer;
728}
729
730}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]731asciidoc.install();
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]732/*]]>*/
733</script>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]734</head>
Junio C Hamano2f5a9892019-12-25 21:12:55[diff] [blame]735<body class="manpage">
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]736<div id="header">
Junio C Hamano2f5a9892019-12-25 21:12:55[diff] [blame]737<h1>
738git-sparse-checkout(1) Manual Page
739</h1>
740<h2>NAME</h2>
741<div class="sectionbody">
742<p>git-sparse-checkout -
Junio C Hamano7c37da72022-03-09 22:19:31[diff] [blame]743 Reduce your working tree to a subset of tracked files
Junio C Hamano2f5a9892019-12-25 21:12:55[diff] [blame]744</p>
745</div>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]746</div>
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]747<div id="content">
Junio C Hamano2f5a9892019-12-25 21:12:55[diff] [blame]748<div class="sect1">
749<h2 id="_synopsis">SYNOPSIS</h2>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]750<div class="sectionbody">
Junio C Hamano2f5a9892019-12-25 21:12:55[diff] [blame]751<div class="verseblock">
Junio C Hamano3a9663e2023-04-11 20:54:14[diff] [blame]752<pre class="content"><em>git sparse-checkout</em> (init | list | set | add | reapply | disable | check-rules) [&lt;options&gt;]</pre>
Junio C Hamano2f5a9892019-12-25 21:12:55[diff] [blame]753<div class="attribution">
754</div></div>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]755</div>
756</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]757<div class="sect1">
Junio C Hamano2f5a9892019-12-25 21:12:55[diff] [blame]758<h2 id="_description">DESCRIPTION</h2>
759<div class="sectionbody">
Junio C Hamanoc926f622022-06-03 22:26:23[diff] [blame]760<div class="paragraph"><p>This command is used to create sparse checkouts, which change the
761working tree from having all tracked files present to only having a
762subset of those files. It can also switch which subset of files are
763present, or undo and go back to having all tracked files present in
764the working copy.</p></div>
Junio C Hamano7c37da72022-03-09 22:19:31[diff] [blame]765<div class="paragraph"><p>The subset of files is chosen by providing a list of directories in
Junio C Hamanoc926f622022-06-03 22:26:23[diff] [blame]766cone mode (the default), or by providing a list of patterns in
767non-cone mode.</p></div>
Junio C Hamano7c37da72022-03-09 22:19:31[diff] [blame]768<div class="paragraph"><p>When in a sparse-checkout, other Git commands behave a bit differently.
769For example, switching branches will not update paths outside the
770sparse-checkout directories/patterns, and <code>git commit -a</code> will not record
771paths outside the sparse-checkout directories/patterns as deleted.</p></div>
Junio C Hamano2f5a9892019-12-25 21:12:55[diff] [blame]772<div class="paragraph"><p>THIS COMMAND IS EXPERIMENTAL. ITS BEHAVIOR, AND THE BEHAVIOR OF OTHER
773COMMANDS IN THE PRESENCE OF SPARSE-CHECKOUTS, WILL LIKELY CHANGE IN
774THE FUTURE.</p></div>
775</div>
776</div>
777<div class="sect1">
778<h2 id="_commands">COMMANDS</h2>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]779<div class="sectionbody">
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]780<div class="dlist"><dl>
781<dt class="hdlist1">
Junio C Hamano2f5a9892019-12-25 21:12:55[diff] [blame]782<em>list</em>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]783</dt>
784<dd>
785<p>
Junio C Hamano7c37da72022-03-09 22:19:31[diff] [blame]786 Describe the directories or patterns in the sparse-checkout file.
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]787</p>
788</dd>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]789<dt class="hdlist1">
Junio C Hamano05fe8d12022-01-04 00:50:38[diff] [blame]790<em>set</em>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]791</dt>
792<dd>
793<p>
Junio C Hamano5f907e92022-02-26 00:21:27[diff] [blame]794 Enable the necessary sparse-checkout config settings
795 (<code>core.sparseCheckout</code>, <code>core.sparseCheckoutCone</code>, and
796 <code>index.sparse</code>) if they are not already set to the desired values,
Junio C Hamanoc926f622022-06-03 22:26:23[diff] [blame]797 populate the sparse-checkout file from the list of arguments
798 following the <em>set</em> subcommand, and update the working directory to
799 match.
Junio C Hamanocbe0eb22017-02-27 23:37:49[diff] [blame]800</p>
Junio C Hamano5f907e92022-02-26 00:21:27[diff] [blame]801<div class="paragraph"><p>To ensure that adjusting the sparse-checkout settings within a worktree
802does not alter the sparse-checkout settings in other worktrees, the <em>set</em>
803subcommand will upgrade your repository config to use worktree-specific
804config if not already present. The sparsity defined by the arguments to
805the <em>set</em> subcommand are stored in the worktree-specific sparse-checkout
806file. See <a href="git-worktree.html">git-worktree(1)</a> and the documentation of
807<code>extensions.worktreeConfig</code> in <a href="git-config.html">git-config(1)</a> for more details.</p></div>
Junio C Hamano7c37da72022-03-09 22:19:31[diff] [blame]808<div class="paragraph"><p>When the <code>--stdin</code> option is provided, the directories or patterns are
809read from standard in as a newline-delimited list instead of from the
810arguments.</p></div>
Junio C Hamanoc926f622022-06-03 22:26:23[diff] [blame]811<div class="paragraph"><p>By default, the input list is considered a list of directories, matching
812the output of <code>git ls-tree -d --name-only</code>. This includes interpreting
813pathnames that begin with a double quote (") as C-style quoted strings.
814Note that all files under the specified directories (at any depth) will
815be included in the sparse checkout, as well as files that are siblings
816of either the given directory or any of its ancestors (see <em>CONE PATTERN
817SET</em> below for more details). In the past, this was not the default,
818and <code>--cone</code> needed to be specified or <code>core.sparseCheckoutCone</code> needed
819to be enabled.</p></div>
820<div class="paragraph"><p>When <code>--no-cone</code> is passed, the input list is considered a list of
821patterns. This mode has a number of drawbacks, including not working
822with some options like <code>--sparse-index</code>. As explained in the
823"Non-cone Problems" section below, we do not recommend using it.</p></div>
Junio C Hamano05fe8d12022-01-04 00:50:38[diff] [blame]824<div class="paragraph"><p>Use the <code>--[no-]sparse-index</code> option to use a sparse index (the
825default is to not use it). A sparse index reduces the size of the
826index to be more closely aligned with your sparse-checkout
827definition. This can have significant performance advantages for
828commands such as <code>git status</code> or <code>git add</code>. This feature is still
829experimental. Some commands might be slower with a sparse index until
830they are properly integrated with the feature.</p></div>
Junio C Hamano4078a552021-04-30 06:08:10[diff] [blame]831<div class="paragraph"><p><strong>WARNING:</strong> Using a sparse index requires modifying the index in a way
832that is not completely understood by external tools. If you have trouble
833with this compatibility, then run <code>git sparse-checkout init --no-sparse-index</code>
834to rewrite your index to not be sparse. Older versions of Git will not
835understand the sparse directory entries index extension and may fail to
836interact with your repository until it is disabled.</p></div>
Junio C Hamanocbe0eb22017-02-27 23:37:49[diff] [blame]837</dd>
838<dt class="hdlist1">
Junio C Hamanob082a532020-03-05 21:52:25[diff] [blame]839<em>add</em>
840</dt>
841<dd>
842<p>
Junio C Hamano7c37da72022-03-09 22:19:31[diff] [blame]843 Update the sparse-checkout file to include additional directories
844 (in cone mode) or patterns (in non-cone mode). By default, these
845 directories or patterns are read from the command-line arguments,
846 but they can be read from stdin using the <code>--stdin</code> option.
Junio C Hamanob082a532020-03-05 21:52:25[diff] [blame]847</p>
848</dd>
849<dt class="hdlist1">
Junio C Hamano0beab6c2020-05-26 18:32:25[diff] [blame]850<em>reapply</em>
Junio C Hamano67cc2b72020-04-30 00:03:20[diff] [blame]851</dt>
852<dd>
853<p>
854 Reapply the sparsity pattern rules to paths in the working tree.
855 Commands like merge or rebase can materialize paths to do their
856 work (e.g. in order to show you a conflict), and other
857 sparse-checkout commands might fail to sparsify an individual file
858 (e.g. because it has unstaged changes or conflicts). In such
859 cases, it can make sense to run <code>git sparse-checkout reapply</code> later
860 after cleaning up affected paths (e.g. resolving conflicts, undoing
861 or committing changes, etc.).
862</p>
Junio C Hamano05fe8d12022-01-04 00:50:38[diff] [blame]863<div class="paragraph"><p>The <code>reapply</code> command can also take <code>--[no-]cone</code> and <code>--[no-]sparse-index</code>
864flags, with the same meaning as the flags from the <code>set</code> command, in order
865to change which sparsity mode you are using without needing to also respecify
866all sparsity paths.</p></div>
Junio C Hamano67cc2b72020-04-30 00:03:20[diff] [blame]867</dd>
868<dt class="hdlist1">
Junio C Hamano2f5a9892019-12-25 21:12:55[diff] [blame]869<em>disable</em>
870</dt>
871<dd>
872<p>
873 Disable the <code>core.sparseCheckout</code> config setting, and restore the
Junio C Hamano05fe8d12022-01-04 00:50:38[diff] [blame]874 working directory to include all files.
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]875</p>
876</dd>
Junio C Hamano05fe8d12022-01-04 00:50:38[diff] [blame]877<dt class="hdlist1">
878<em>init</em>
879</dt>
880<dd>
881<p>
882 Deprecated command that behaves like <code>set</code> with no specified paths.
883 May be removed in the future.
884</p>
885<div class="paragraph"><p>Historically, <code>set</code> did not handle all the necessary config settings,
886which meant that both <code>init</code> and <code>set</code> had to be called. Invoking
887both meant the <code>init</code> step would first remove nearly all tracked files
888(and in cone mode, ignored files too), then the <code>set</code> step would add
889many of the tracked files (but not ignored files) back. In addition
890to the lost files, the performance and UI of this combination was
891poor.</p></div>
892<div class="paragraph"><p>Also, historically, <code>init</code> would not actually initialize the
893sparse-checkout file if it already existed. This meant it was
894possible to return to a sparse-checkout without remembering which
895paths to pass to a subsequent <em>set</em> or <em>add</em> command. However,
896<code>--cone</code> and <code>--sparse-index</code> options would not be remembered across
897the disable command, so the easy restore of calling a plain <code>init</code>
898decreased in utility.</p></div>
899</dd>
Junio C Hamano3a9663e2023-04-11 20:54:14[diff] [blame]900<dt class="hdlist1">
901<em>check-rules</em>
902</dt>
903<dd>
904<p>
905 Check whether sparsity rules match one or more paths.
906</p>
907<div class="paragraph"><p>By default <code>check-rules</code> reads a list of paths from stdin and outputs only
908the ones that match the current sparsity rules. The input is expected to consist
909of one path per line, matching the output of <code>git ls-tree --name-only</code> including
910that pathnames that begin with a double quote (") are interpreted as C-style
911quoted strings.</p></div>
912<div class="paragraph"><p>When called with the <code>--rules-file &lt;file&gt;</code> flag the input files are matched
913against the sparse checkout rules found in <code>&lt;file&gt;</code> instead of the current ones.
914The rules in the files are expected to be in the same form as accepted by <code>git
915sparse-checkout set --stdin</code> (in particular, they must be newline-delimited).</p></div>
916<div class="paragraph"><p>By default, the rules passed to the <code>--rules-file</code> option are interpreted as
917cone mode directories. To pass non-cone mode patterns with <code>--rules-file</code>,
918combine the option with the <code>--no-cone</code> option.</p></div>
919<div class="paragraph"><p>When called with the <code>-z</code> flag, the format of the paths input on stdin as well
920as the output paths are \0 terminated and not quoted. Note that this does not
921apply to the format of the rules passed with the <code>--rules-file</code> option.</p></div>
922</dd>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]923</dl></div>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]924</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]925</div>
926<div class="sect1">
Junio C Hamanoc926f622022-06-03 22:26:23[diff] [blame]927<h2 id="_examples">EXAMPLES</h2>
928<div class="sectionbody">
929<div class="dlist"><dl>
930<dt class="hdlist1">
931<code>git sparse-checkout set MY/DIR1 SUB/DIR2</code>
932</dt>
933<dd>
934<p>
935 Change to a sparse checkout with all files (at any depth) under
936 MY/DIR1/ and SUB/DIR2/ present in the working copy (plus all
937 files immediately under MY/ and SUB/ and the toplevel
938 directory). If already in a sparse checkout, change which files
939 are present in the working copy to this new selection. Note
940 that this command will also delete all ignored files in any
941 directory that no longer has either tracked or
942 non-ignored-untracked files present.
943</p>
944</dd>
945<dt class="hdlist1">
946<code>git sparse-checkout disable</code>
947</dt>
948<dd>
949<p>
950 Repopulate the working directory with all files, disabling sparse
951 checkouts.
952</p>
953</dd>
954<dt class="hdlist1">
955<code>git sparse-checkout add SOME/DIR/ECTORY</code>
956</dt>
957<dd>
958<p>
959 Add all files under SOME/DIR/ECTORY/ (at any depth) to the
960 sparse checkout, as well as all files immediately under
961 SOME/DIR/ and immediately under SOME/. Must already be in a
962 sparse checkout before using this command.
963</p>
964</dd>
965<dt class="hdlist1">
966<code>git sparse-checkout reapply</code>
967</dt>
968<dd>
969<p>
970 It is possible for commands to update the working tree in a
971 way that does not respect the selected sparsity directories.
972 This can come from tools external to Git writing files, or
973 even affect Git commands because of either special cases (such
974 as hitting conflicts when merging/rebasing), or because some
975 commands didn&#8217;t fully support sparse checkouts (e.g. the old
976 <code>recursive</code> merge backend had only limited support). This
977 command reapplies the existing sparse directory specifications
978 to make the working directory match.
979</p>
980</dd>
981</dl></div>
982</div>
983</div>
984<div class="sect1">
985<h2 id="_internals_8201_8212_8201_sparse_checkout">INTERNALS&#8201;&#8212;&#8201;SPARSE CHECKOUT</h2>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]986<div class="sectionbody">
Junio C Hamano7c37da72022-03-09 22:19:31[diff] [blame]987<div class="paragraph"><p>"Sparse checkout" allows populating the working directory sparsely. It
988uses the skip-worktree bit (see <a href="git-update-index.html">git-update-index(1)</a>) to tell Git
989whether a file in the working directory is worth looking at. If the
990skip-worktree bit is set, and the file is not present in the working tree,
991then its absence is ignored. Git will avoid populating the contents of
992those files, which makes a sparse checkout helpful when working in a
993repository with many files, but only a few are important to the current
994user.</p></div>
Junio C Hamano2f5a9892019-12-25 21:12:55[diff] [blame]995<div class="paragraph"><p>The <code>$GIT_DIR/info/sparse-checkout</code> file is used to define the
996skip-worktree reference bitmap. When Git updates the working
997directory, it updates the skip-worktree bits in the index based
998on this file. The files matching the patterns in the file will
999appear in the working directory, and the rest will not.</p></div>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]1000</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1001</div>
1002<div class="sect1">
Junio C Hamanoc926f622022-06-03 22:26:23[diff] [blame]1003<h2 id="_internals_8201_8212_8201_non_cone_problems">INTERNALS&#8201;&#8212;&#8201;NON-CONE PROBLEMS</h2>
Junio C Hamanof7279012011-08-18 06:13:13[diff] [blame]1004<div class="sectionbody">
Junio C Hamanoc926f622022-06-03 22:26:23[diff] [blame]1005<div class="paragraph"><p>The <code>$GIT_DIR/info/sparse-checkout</code> file populated by the <code>set</code> and
1006<code>add</code> subcommands is defined to be a bunch of patterns (one per line)
1007using the same syntax as <code>.gitignore</code> files. In cone mode, these
1008patterns are restricted to matching directories (and users only ever
1009need supply or see directory names), while in non-cone mode any
1010gitignore-style pattern is permitted. Using the full gitignore-style
1011patterns in non-cone mode has a number of shortcomings:</p></div>
1012<div class="ulist"><ul>
1013<li>
1014<p>
1015Fundamentally, it makes various worktree-updating processes (pull,
1016 merge, rebase, switch, reset, checkout, etc.) require O(N*M) pattern
1017 matches, where N is the number of patterns and M is the number of
1018 paths in the index. This scales poorly.
1019</p>
1020</li>
1021<li>
1022<p>
1023Avoiding the scaling issue has to be done via limiting the number
1024 of patterns via specifying leading directory name or glob.
1025</p>
1026</li>
1027<li>
1028<p>
1029Passing globs on the command line is error-prone as users may
1030 forget to quote the glob, causing the shell to expand it into all
1031 matching files and pass them all individually along to
1032 sparse-checkout set/add. While this could also be a problem with
1033 e.g. "git grep&#8201;&#8212;&#8201;*.c", mistakes with grep/log/status appear in
1034 the immediate output. With sparse-checkout, the mistake gets
1035 recorded at the time the sparse-checkout command is run and might
1036 not be problematic until the user later switches branches or rebases
1037 or merges, thus putting a delay between the user&#8217;s error and when
1038 they have a chance to catch/notice it.
1039</p>
1040</li>
1041<li>
1042<p>
1043Related to the previous item, sparse-checkout has an <em>add</em>
1044 subcommand but no <em>remove</em> subcommand. Even if a <em>remove</em>
1045 subcommand were added, undoing an accidental unquoted glob runs
1046 the risk of "removing too much", as it may remove entries that had
1047 been included before the accidental add.
1048</p>
1049</li>
1050<li>
1051<p>
1052Non-cone mode uses gitignore-style patterns to select what to
1053 <strong>include</strong> (with the exception of negated patterns), while
1054 .gitignore files use gitignore-style patterns to select what to
1055 <strong>exclude</strong> (with the exception of negated patterns). The
1056 documentation on gitignore-style patterns usually does not talk in
1057 terms of matching or non-matching, but on what the user wants to
1058 "exclude". This can cause confusion for users trying to learn how
1059 to specify sparse-checkout patterns to get their desired behavior.
1060</p>
1061</li>
1062<li>
1063<p>
1064Every other git subcommand that wants to provide "special path
1065 pattern matching" of some sort uses pathspecs, but non-cone mode
1066 for sparse-checkout uses gitignore patterns, which feels
1067 inconsistent.
1068</p>
1069</li>
1070<li>
1071<p>
1072It has edge cases where the "right" behavior is unclear. Two examples:
1073</p>
1074<div class="literalblock">
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]1075<div class="content">
Junio C Hamanoc926f622022-06-03 22:26:23[diff] [blame]1076<pre><code>First, two users are in a subdirectory, and the first runs
1077 git sparse-checkout set '/toplevel-dir/*.c'
1078while the second runs
1079 git sparse-checkout set relative-dir
1080Should those arguments be transliterated into
1081 current/subdirectory/toplevel-dir/*.c
1082and
1083 current/subdirectory/relative-dir
1084before inserting into the sparse-checkout file? The user who typed
1085the first command is probably aware that arguments to set/add are
1086supposed to be patterns in non-cone mode, and probably would not be
1087happy with such a transliteration. However, many gitignore-style
1088patterns are just paths, which might be what the user who typed the
1089second command was thinking, and they'd be upset if their argument
1090wasn't transliterated.</code></pre>
Junio C Hamanocbe0eb22017-02-27 23:37:49[diff] [blame]1091</div></div>
Junio C Hamanoc926f622022-06-03 22:26:23[diff] [blame]1092<div class="literalblock">
1093<div class="content">
1094<pre><code>Second, what should bash-completion complete on for set/add commands
1095for non-cone users? If it suggests paths, is it exacerbating the
1096problem above? Also, if it suggests paths, what if the user has a
1097file or directory that begins with either a '!' or '#' or has a '*',
1098'\', '?', '[', or ']' in its name? And if it suggests paths, will
Junio C Hamano9469c132023-06-23 20:26:29[diff] [blame]1099it complete "/pro" to "/proc" (in the root filesystem) rather than to
Junio C Hamanoc926f622022-06-03 22:26:23[diff] [blame]1100"/progress.txt" in the current directory? (Note that users are
1101likely to want to start paths with a leading '/' in non-cone mode,
1102for the same reason that .gitignore files often have one.)
1103Completing on files or directories might give nasty surprises in
1104all these cases.</code></pre>
1105</div></div>
1106</li>
1107<li>
1108<p>
1109The excessive flexibility made other extensions essentially
1110 impractical. <code>--sparse-index</code> is likely impossible in non-cone
1111 mode; even if it is somehow feasible, it would have been far more
1112 work to implement and may have been too slow in practice. Some
1113 ideas for adding coupling between partial clones and sparse
1114 checkouts are only practical with a more restricted set of paths
1115 as well.
1116</p>
1117</li>
1118</ul></div>
1119<div class="paragraph"><p>For all these reasons, non-cone mode is deprecated. Please switch to
1120using cone mode.</p></div>
Junio C Hamanof7279012011-08-18 06:13:13[diff] [blame]1121</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1122</div>
1123<div class="sect1">
Junio C Hamanoc926f622022-06-03 22:26:23[diff] [blame]1124<h2 id="_internals_8201_8212_8201_cone_mode_handling">INTERNALS&#8201;&#8212;&#8201;CONE MODE HANDLING</h2>
1125<div class="sectionbody">
1126<div class="paragraph"><p>The "cone mode", which is the default, lets you specify only what
1127directories to include. For any directory specified, all paths below
1128that directory will be included, and any paths immediately under
1129leading directories (including the toplevel directory) will also be
1130included. Thus, if you specified the directory
1131 Documentation/technical/
1132then your sparse checkout would contain:</p></div>
1133<div class="ulist"><ul>
1134<li>
1135<p>
1136all files in the toplevel-directory
1137</p>
1138</li>
1139<li>
1140<p>
1141all files immediately under Documentation/
1142</p>
1143</li>
1144<li>
1145<p>
1146all files at any depth under Documentation/technical/
1147</p>
1148</li>
1149</ul></div>
1150<div class="paragraph"><p>Also, in cone mode, even if no directories are specified, then the
1151files in the toplevel directory will be included.</p></div>
1152<div class="paragraph"><p>When changing the sparse-checkout patterns in cone mode, Git will inspect each
1153tracked directory that is not within the sparse-checkout cone to see if it
1154contains any untracked files. If all of those files are ignored due to the
1155<code>.gitignore</code> patterns, then the directory will be deleted. If any of the
1156untracked files within that directory is not ignored, then no deletions will
1157occur within that directory and a warning message will appear. If these files
1158are important, then reset your sparse-checkout definition so they are included,
1159use <code>git add</code> and <code>git commit</code> to store them, then remove any remaining files
1160manually to ensure Git can behave optimally.</p></div>
1161<div class="paragraph"><p>See also the "Internals&#8201;&#8212;&#8201;Cone Pattern Set" section to learn how the
1162directories are transformed under the hood into a subset of the
1163Full Pattern Set of sparse-checkout.</p></div>
1164</div>
1165</div>
1166<div class="sect1">
1167<h2 id="_internals_8201_8212_8201_full_pattern_set">INTERNALS&#8201;&#8212;&#8201;FULL PATTERN SET</h2>
Junio C Hamanof7279012011-08-18 06:13:13[diff] [blame]1168<div class="sectionbody">
Junio C Hamano2f5a9892019-12-25 21:12:55[diff] [blame]1169<div class="paragraph"><p>The full pattern set allows for arbitrary pattern matches and complicated
1170inclusion/exclusion rules. These can result in O(N*M) pattern matches when
1171updating the index, where N is the number of patterns and M is the number
1172of paths in the index. To combat this performance issue, a more restricted
Junio C Hamanofc6646b2020-02-14 23:35:16[diff] [blame]1173pattern set is allowed when <code>core.sparseCheckoutCone</code> is enabled.</p></div>
Junio C Hamanoc926f622022-06-03 22:26:23[diff] [blame]1174<div class="paragraph"><p>The sparse-checkout file uses the same syntax as <code>.gitignore</code> files;
1175see <a href="gitignore.html">gitignore(5)</a> for details. Here, though, the patterns are
1176usually being used to select which files to include rather than which
1177files to exclude. (However, it can get a bit confusing since
1178gitignore-style patterns have negations defined by patterns which
1179begin with a <em>!</em>, so you can also select files to <em>not</em> include.)</p></div>
1180<div class="paragraph"><p>For example, to select everything, and then to remove the file
1181<code>unwanted</code> (so that every file will appear in your working tree except
1182the file named <code>unwanted</code>):</p></div>
1183<div class="literalblock">
1184<div class="content">
1185<pre><code>git sparse-checkout set --no-cone '/*' '!unwanted'</code></pre>
1186</div></div>
1187<div class="paragraph"><p>These patterns are just placed into the
1188<code>$GIT_DIR/info/sparse-checkout</code> as-is, so the contents of that file
1189at this point would be</p></div>
1190<div class="listingblock">
1191<div class="content">
1192<pre><code>/*
1193!unwanted</code></pre>
1194</div></div>
1195<div class="paragraph"><p>See also the "Sparse Checkout" section of <a href="git-read-tree.html">git-read-tree(1)</a> to
1196learn more about the gitignore-style patterns used in sparse
1197checkouts.</p></div>
1198</div>
1199</div>
1200<div class="sect1">
1201<h2 id="_internals_8201_8212_8201_cone_pattern_set">INTERNALS&#8201;&#8212;&#8201;CONE PATTERN SET</h2>
1202<div class="sectionbody">
1203<div class="paragraph"><p>In cone mode, only directories are accepted, but they are translated into
1204the same gitignore-style patterns used in the full pattern set. We refer
1205to the particular patterns used in those mode as being of one of two types:</p></div>
Junio C Hamano2f5a9892019-12-25 21:12:55[diff] [blame]1206<div class="olist arabic"><ol class="arabic">
Junio C Hamanof7279012011-08-18 06:13:13[diff] [blame]1207<li>
1208<p>
Junio C Hamano2f5a9892019-12-25 21:12:55[diff] [blame]1209<strong>Recursive:</strong> All paths inside a directory are included.
Junio C Hamanof7279012011-08-18 06:13:13[diff] [blame]1210</p>
1211</li>
1212<li>
1213<p>
Junio C Hamano2f5a9892019-12-25 21:12:55[diff] [blame]1214<strong>Parent:</strong> All files immediately inside a directory are included.
Junio C Hamanof7279012011-08-18 06:13:13[diff] [blame]1215</p>
1216</li>
Junio C Hamano2f5a9892019-12-25 21:12:55[diff] [blame]1217</ol></div>
Junio C Hamanoc926f622022-06-03 22:26:23[diff] [blame]1218<div class="paragraph"><p>Since cone mode always includes files at the toplevel, when running
1219<code>git sparse-checkout set</code> with no directories specified, the toplevel
1220directory is added as a parent pattern. At this point, the
1221sparse-checkout file contains the following patterns:</p></div>
Junio C Hamano2f5a9892019-12-25 21:12:55[diff] [blame]1222<div class="listingblock">
1223<div class="content">
1224<pre><code>/*
1225!/*/</code></pre>
1226</div></div>
Junio C Hamanoc926f622022-06-03 22:26:23[diff] [blame]1227<div class="paragraph"><p>This says "include everything immediately under the toplevel
1228directory, but nothing at any level below that."</p></div>
1229<div class="paragraph"><p>When in cone mode, the <code>git sparse-checkout set</code> subcommand takes a
1230list of directories. The command <code>git sparse-checkout set A/B/C</code> sets
1231the directory <code>A/B/C</code> as a recursive pattern, the directories <code>A</code> and
1232<code>A/B</code> are added as parent patterns. The resulting sparse-checkout file
1233is now</p></div>
Junio C Hamano2f5a9892019-12-25 21:12:55[diff] [blame]1234<div class="listingblock">
1235<div class="content">
1236<pre><code>/*
1237!/*/
1238/A/
1239!/A/*/
1240/A/B/
1241!/A/B/*/
1242/A/B/C/</code></pre>
1243</div></div>
1244<div class="paragraph"><p>Here, order matters, so the negative patterns are overridden by the positive
1245patterns that appear lower in the file.</p></div>
Junio C Hamanoc926f622022-06-03 22:26:23[diff] [blame]1246<div class="paragraph"><p>Unless <code>core.sparseCheckoutCone</code> is explicitly set to <code>false</code>, Git will
1247parse the sparse-checkout file expecting patterns of these types. Git will
1248warn if the patterns do not match. If the patterns do match the expected
1249format, then Git will use faster hash-based algorithms to compute inclusion
1250in the sparse-checkout. If they do not match, git will behave as though
1251<code>core.sparseCheckoutCone</code> was false, regardless of its setting.</p></div>
1252<div class="paragraph"><p>In the cone mode case, despite the fact that full patterns are written
1253to the $GIT_DIR/info/sparse-checkout file, the <code>git sparse-checkout
1254list</code> subcommand will list the directories that define the recursive
1255patterns. For the example sparse-checkout file above, the output is as
1256follows:</p></div>
Junio C Hamano68793842020-01-06 23:07:09[diff] [blame]1257<div class="listingblock">
1258<div class="content">
1259<pre><code>$ git sparse-checkout list
1260A/B/C</code></pre>
1261</div></div>
Junio C Hamano2f5a9892019-12-25 21:12:55[diff] [blame]1262<div class="paragraph"><p>If <code>core.ignoreCase=true</code>, then the pattern-matching algorithm will use a
1263case-insensitive check. This corrects for case mismatched filenames in the
1264<em>git sparse-checkout set</em> command to reflect the expected cone in the working
1265directory.</p></div>
1266</div>
1267</div>
1268<div class="sect1">
Junio C Hamanoc926f622022-06-03 22:26:23[diff] [blame]1269<h2 id="_internals_8201_8212_8201_submodules">INTERNALS&#8201;&#8212;&#8201;SUBMODULES</h2>
Junio C Hamano68793842020-01-06 23:07:09[diff] [blame]1270<div class="sectionbody">
Junio C Hamano03e5f352020-06-22 23:59:49[diff] [blame]1271<div class="paragraph"><p>If your repository contains one or more submodules, then submodules
1272are populated based on interactions with the <code>git submodule</code> command.
1273Specifically, <code>git submodule init -- &lt;path&gt;</code> will ensure the submodule
1274at <code>&lt;path&gt;</code> is present, while <code>git submodule deinit [-f] -- &lt;path&gt;</code>
1275will remove the files for the submodule at <code>&lt;path&gt;</code> (including any
1276untracked files, uncommitted changes, and unpushed history). Similar
1277to how sparse-checkout removes files from the working tree but still
1278leaves entries in the index, deinitialized submodules are removed from
1279the working directory but still have an entry in the index.</p></div>
1280<div class="paragraph"><p>Since submodules may have unpushed changes or untracked files,
1281removing them could result in data loss. Thus, changing sparse
1282inclusion/exclusion rules will not cause an already checked out
1283submodule to be removed from the working copy. Said another way, just
1284as <code>checkout</code> will not cause submodules to be automatically removed or
1285initialized even when switching between branches that remove or add
1286submodules, using <code>sparse-checkout</code> to reduce or expand the scope of
1287"interesting" files will not cause submodules to be automatically
1288deinitialized or initialized either.</p></div>
1289<div class="paragraph"><p>Further, the above facts mean that there are multiple reasons that
1290"tracked" files might not be present in the working copy: sparsity
1291pattern application from sparse-checkout, and submodule initialization
1292state. Thus, commands like <code>git grep</code> that work on tracked files in
1293the working copy may return results that are limited by either or both
1294of these restrictions.</p></div>
Junio C Hamano68793842020-01-06 23:07:09[diff] [blame]1295</div>
1296</div>
1297<div class="sect1">
Junio C Hamano2f5a9892019-12-25 21:12:55[diff] [blame]1298<h2 id="_see_also">SEE ALSO</h2>
1299<div class="sectionbody">
1300<div class="paragraph"><p><a href="git-read-tree.html">git-read-tree(1)</a>
1301<a href="gitignore.html">gitignore(5)</a></p></div>
1302</div>
1303</div>
1304<div class="sect1">
1305<h2 id="_git">GIT</h2>
1306<div class="sectionbody">
1307<div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]1308</div>
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]1309</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1310</div>
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]1311<div id="footnotes"><hr /></div>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]1312<div id="footer">
1313<div id="footer-text">
Junio C Hamano2ef0ba32018-01-26 23:13:53[diff] [blame]1314Last updated
Junio C Hamano9469c132023-06-23 20:26:29[diff] [blame]1315 2023-06-23 13:24:09 PDT
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]1316</div>
1317</div>
1318</body>
1319</html>