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