<?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"> | |
/*<![CDATA[*/ | |
var asciidoc = { // Namespace. | |
///////////////////////////////////////////////////////////////////// | |
// Table Of Contents generator | |
///////////////////////////////////////////////////////////////////// | |
/* Author: Mihai Bazon, September 2002 | |
* http://students.infoiasi.ro/~mishoo | |
* | |
* Table Of Content generator | |
* Version: 0.4 | |
* | |
* Feel free to use this script under the terms of the GNU General Public | |
* License, as long as you do not remove or alter this notice. | |
*/ | |
/* modified by Troy D. Hanson, September 2006. License: GPL */ | |
/* modified by Stuart Rackham, 2006, 2009. License: GPL */ | |
// toclevels = 1..4. | |
toc: function (toclevels) { | |
function getText(el) { | |
var text = ""; | |
for (var i = el.firstChild; i != null; i = i.nextSibling) { | |
if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants. | |
text += i.data; | |
else if (i.firstChild != null) | |
text += getText(i); | |
} | |
return text; | |
} | |
function TocEntry(el, text, toclevel) { | |
this.element = el; | |
this.text = text; | |
this.toclevel = toclevel; | |
} | |
function tocEntries(el, toclevels) { | |
var result = new Array; | |
var re = new RegExp('[hH]([1-'+(toclevels+1)+'])'); | |
// 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> |