git-submodule.html - external/gitster/git-htmldocs - Git at Google

 <!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="text/html; charset=UTF-8" />
 <meta name="generator" content="AsciiDoc 8.2.5" />
 <style type="text/css">
 /* Debug borders */
 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
 /*
  border: 1px solid red;
 */
 }

 body {
  margin: 1em 5% 1em 5%;
 }

 a {
  color: blue;
  text-decoration: underline;
 }
 a:visited {
  color: fuchsia;
 }

 em {
  font-style: italic;
 }

 strong {
  font-weight: bold;
 }

 tt {
  color: navy;
 }

 h1, h2, h3, h4, h5, h6 {
  color: #527bbd;
  font-family: sans-serif;
  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;
 }

 div.sectionbody {
  font-family: serif;
  margin-left: 0;
 }

 hr {
  border: 1px solid silver;
 }

 p {
  margin-top: 0.5em;
  margin-bottom: 0.5em;
 }

 pre {
  padding: 0;
  margin: 0;
 }

 span#author {
  color: #527bbd;
  font-family: sans-serif;
  font-weight: bold;
  font-size: 1.1em;
 }
 span#email {
 }
 span#revision {
  font-family: sans-serif;
 }

 div#footer {
  font-family: sans-serif;
  font-size: small;
  border-top: 2px solid silver;
  padding-top: 0.5em;
  margin-top: 4.0em;
 }
 div#footer-text {
  float: left;
  padding-bottom: 0.5em;
 }
 div#footer-badges {
  float: right;
  padding-bottom: 0.5em;
 }

 div#preamble,
 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
 div.admonitionblock {
  margin-right: 10%;
  margin-top: 1.5em;
  margin-bottom: 1.5em;
 }
 div.admonitionblock {
  margin-top: 2.5em;
  margin-bottom: 2.5em;
 }

 div.content { /* Block element content. */
  padding: 0;
 }

 /* Block element titles. */
 div.title, caption.title {
  font-family: sans-serif;
  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 silver;
  padding: 0.5em;
 }

 div.listingblock {
  margin-right: 0%;
 }
 div.listingblock > div.content {
  border: 1px solid silver;
  background: #f4f4f4;
  padding: 0.5em;
 }

 div.quoteblock > div.content {
  padding-left: 2.0em;
 }

 div.attribution {
  text-align: right;
 }
 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: 2px solid silver;
 }

 div.exampleblock > div.content {
  border-left: 2px solid silver;
  padding: 0.5em;
 }

 div.verseblock div.content {
  white-space: pre;
 }

 div.imageblock div.content { padding-left: 0; }
 div.imageblock img { border: 1px solid silver; }
 span.image img { border-style: none; }

 dl {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
 }
 dt {
  margin-top: 0.5em;
  margin-bottom: 0;
  font-style: italic;
 }
 dd > *:first-child {
  margin-top: 0;
 }

 ul, ol {
  list-style-position: outside;
 }
 div.olist2 ol {
  list-style-type: lower-alpha;
 }

 div.tableblock > table {
  border: 3px solid #527bbd;
 }
 thead {
  font-family: sans-serif;
  font-weight: bold;
 }
 tfoot {
  font-weight: bold;
 }

 div.hlist {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
 }
 div.hlist td {
  padding-bottom: 5px;
 }
 td.hlist1 {
  vertical-align: top;
  font-style: italic;
  padding-right: 0.8em;
 }
 td.hlist2 {
  vertical-align: top;
 }

 @media print {
  div#footer-badges { display: none; }
 }

 div#toctitle {
  color: #527bbd;
  font-family: sans-serif;
  font-size: 1.1em;
  font-weight: bold;
  margin-top: 1.0em;
  margin-bottom: 0.1em;
 }

 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;
 }
 include1::./stylesheets/xhtml11-manpage.css[]
 /* Workarounds for IE6's broken and incomplete CSS2. */

 div.sidebar-content {
  background: #ffffee;
  border: 1px solid silver;
  padding: 0.5em;
 }
 div.sidebar-title, div.image-title {
  font-family: sans-serif;
  font-weight: bold;
  margin-top: 0.0em;
  margin-bottom: 0.5em;
 }

 div.listingblock div.content {
  border: 1px solid silver;
  background: #f4f4f4;
  padding: 0.5em;
 }

 div.quoteblock-content {
  padding-left: 2.0em;
 }

 div.exampleblock-content {
  border-left: 2px solid silver;
  padding-left: 0.5em;
 }

 /* IE6 sets dynamically generated links as visited. */
 div#toc a:visited { color: blue; }
 </style>
 <title>git-submodule(1)</title>
 </head>
 <body>
 <div id="header">
 <h1>
 git-submodule(1) Manual Page
 </h1>
 <h2>NAME</h2>
 <div class="sectionbody">
 <p>git-submodule -
  Initialize, update or inspect submodules
 </p>
 </div>
 </div>
 <h2>SYNOPSIS</h2>
 <div class="sectionbody">
 <div class="verseblock">
 <div class="content"><em>git submodule</em> [--quiet] add [-b branch] [--] &lt;repository&gt; [&lt;path&gt;]
 <em>git submodule</em> [--quiet] status [--cached] [--] [&lt;path&gt;&#8230;]
 <em>git submodule</em> [--quiet] init [--] [&lt;path&gt;&#8230;]
 <em>git submodule</em> [--quiet] update [--init] [--] [&lt;path&gt;&#8230;]
 <em>git submodule</em> [--quiet] summary [--summary-limit &lt;n&gt;] [commit] [--] [&lt;path&gt;&#8230;]</div></div>
 </div>
 <h2 id="_commands">COMMANDS</h2>
 <div class="sectionbody">
 <div class="vlist"><dl>
 <dt>
 add
 </dt>
 <dd>
 <p>
  Add the given repository as a submodule at the given path
  to the changeset to be committed next. If path is a valid
  repository within the project, it is added as is. Otherwise,
  repository is cloned at the specified path. path is added to the
  changeset and registered in .gitmodules. If no path is
  specified, the path is deduced from the repository specification.
  If the repository url begins with ./ or ../, it is stored as
  given but resolved as a relative path from the main project's
  url when cloning.
 </p>
 </dd>
 <dt>
 status
 </dt>
 <dd>
 <p>
  Show the status of the submodules. This will print the SHA-1 of the
  currently checked out commit for each submodule, along with the
  submodule path and the output of <em>git-describe</em> for the
  SHA-1. Each SHA-1 will be prefixed with <tt>-</tt> if the submodule is not
  initialized and <tt>+</tt> if the currently checked out submodule commit
  does not match the SHA-1 found in the index of the containing
  repository. This command is the default command for <em>git-submodule</em>.
 </p>
 </dd>
 <dt>
 init
 </dt>
 <dd>
 <p>
  Initialize the submodules, i.e. register in .git/config each submodule
  name and url found in .gitmodules. The key used in .git/config is
  <tt>submodule.$name.url</tt>. This command does not alter existing information
  in .git/config.
 </p>
 </dd>
 <dt>
 update
 </dt>
 <dd>
 <p>
  Update the registered submodules, i.e. clone missing submodules and
  checkout the commit specified in the index of the containing repository.
  This will make the submodules HEAD be detached.
 </p>
 <div class="para"><p>If the submodule is not yet initialized, and you just want to use the
 setting as stored in .gitmodules, you can automatically initialize the
 submodule with the --init option.</p></div>
 </dd>
 <dt>
 summary
 </dt>
 <dd>
 <p>
  Show commit summary between the given commit (defaults to HEAD) and
  working tree/index. For a submodule in question, a series of commits
  in the submodule between the given super project commit and the
  index or working tree (switched by --cached) are shown.
 </p>
 </dd>
 </dl></div>
 </div>
 <h2 id="_options">OPTIONS</h2>
 <div class="sectionbody">
 <div class="vlist"><dl>
 <dt>
 -q
 </dt>
 <dt>
 --quiet
 </dt>
 <dd>
 <p>
  Only print error messages.
 </p>
 </dd>
 <dt>
 -b
 </dt>
 <dt>
 --branch
 </dt>
 <dd>
 <p>
  Branch of repository to add as submodule.
 </p>
 </dd>
 <dt>
 --cached
 </dt>
 <dd>
 <p>
  This option is only valid for status and summary commands. These
  commands typically use the commit found in the submodule HEAD, but
  with this option, the commit stored in the index is used instead.
 </p>
 </dd>
 <dt>
 -n
 </dt>
 <dt>
 --summary-limit
 </dt>
 <dd>
 <p>
  This option is only valid for the summary command.
  Limit the summary size (number of commits shown in total).
  Giving 0 will disable the summary; a negative number means unlimited
  (the default). This limit only applies to modified submodules. The
  size is always limited to 1 for added/deleted/typechanged submodules.
 </p>
 </dd>
 <dt>
 &lt;path&gt;
 </dt>
 <dd>
 <p>
  Path to submodule(s). When specified this will restrict the command
  to only operate on the submodules found at the specified paths.
 </p>
 </dd>
 </dl></div>
 </div>
 <h2 id="_files">FILES</h2>
 <div class="sectionbody">
 <div class="para"><p>When initializing submodules, a .gitmodules file in the top-level directory
 of the containing repository is used to find the url of each submodule.
 This file should be formatted in the same way as <tt>$GIT_DIR/config</tt>. The key
 to each submodule url is "submodule.$name.url". See <a href="gitmodules.html">gitmodules(5)</a>
 for details.</p></div>
 </div>
 <h2 id="_author">AUTHOR</h2>
 <div class="sectionbody">
 <div class="para"><p>Written by Lars Hjemli &lt;hjemli@gmail.com&gt;</p></div>
 </div>
 <h2 id="_git">GIT</h2>
 <div class="sectionbody">
 <div class="para"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
 </div>
 <div id="footer">
 <div id="footer-text">
 Last updated 2008-07-06 05:17:04 UTC
 </div>
 </div>
 </body>
 </html>
	<!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="text/html; charset=UTF-8" />
	<meta name="generator" content="AsciiDoc 8.2.5" />
	<style type="text/css">
	/* Debug borders */
	p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
	/*
	border: 1px solid red;
	*/
	}

	body {
	margin: 1em 5% 1em 5%;
	}

	a {
	color: blue;
	text-decoration: underline;
	}
	a:visited {
	color: fuchsia;
	}

	em {
	font-style: italic;
	}

	strong {
	font-weight: bold;
	}

	tt {
	color: navy;
	}

	h1, h2, h3, h4, h5, h6 {
	color: #527bbd;
	font-family: sans-serif;
	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;
	}

	div.sectionbody {
	font-family: serif;
	margin-left: 0;
	}

	hr {
	border: 1px solid silver;
	}

	p {
	margin-top: 0.5em;
	margin-bottom: 0.5em;
	}

	pre {
	padding: 0;
	margin: 0;
	}

	span#author {
	color: #527bbd;
	font-family: sans-serif;
	font-weight: bold;
	font-size: 1.1em;
	}
	span#email {
	}
	span#revision {
	font-family: sans-serif;
	}

	div#footer {
	font-family: sans-serif;
	font-size: small;
	border-top: 2px solid silver;
	padding-top: 0.5em;
	margin-top: 4.0em;
	}
	div#footer-text {
	float: left;
	padding-bottom: 0.5em;
	}
	div#footer-badges {
	float: right;
	padding-bottom: 0.5em;
	}

	div#preamble,
	div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
	div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
	div.admonitionblock {
	margin-right: 10%;
	margin-top: 1.5em;
	margin-bottom: 1.5em;
	}
	div.admonitionblock {
	margin-top: 2.5em;
	margin-bottom: 2.5em;
	}

	div.content { /* Block element content. */
	padding: 0;
	}

	/* Block element titles. */
	div.title, caption.title {
	font-family: sans-serif;
	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 silver;
	padding: 0.5em;
	}

	div.listingblock {
	margin-right: 0%;
	}
	div.listingblock > div.content {
	border: 1px solid silver;
	background: #f4f4f4;
	padding: 0.5em;
	}

	div.quoteblock > div.content {
	padding-left: 2.0em;
	}

	div.attribution {
	text-align: right;
	}
	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: 2px solid silver;
	}

	div.exampleblock > div.content {
	border-left: 2px solid silver;
	padding: 0.5em;
	}

	div.verseblock div.content {
	white-space: pre;
	}

	div.imageblock div.content { padding-left: 0; }
	div.imageblock img { border: 1px solid silver; }
	span.image img { border-style: none; }

	dl {
	margin-top: 0.8em;
	margin-bottom: 0.8em;
	}
	dt {
	margin-top: 0.5em;
	margin-bottom: 0;
	font-style: italic;
	}
	dd > *:first-child {
	margin-top: 0;
	}

	ul, ol {
	list-style-position: outside;
	}
	div.olist2 ol {
	list-style-type: lower-alpha;
	}

	div.tableblock > table {
	border: 3px solid #527bbd;
	}
	thead {
	font-family: sans-serif;
	font-weight: bold;
	}
	tfoot {
	font-weight: bold;
	}

	div.hlist {
	margin-top: 0.8em;
	margin-bottom: 0.8em;
	}
	div.hlist td {
	padding-bottom: 5px;
	}
	td.hlist1 {
	vertical-align: top;
	font-style: italic;
	padding-right: 0.8em;
	}
	td.hlist2 {
	vertical-align: top;
	}

	@media print {
	div#footer-badges { display: none; }
	}

	div#toctitle {
	color: #527bbd;
	font-family: sans-serif;
	font-size: 1.1em;
	font-weight: bold;
	margin-top: 1.0em;
	margin-bottom: 0.1em;
	}

	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;
	}
	include1::./stylesheets/xhtml11-manpage.css[]
	/* Workarounds for IE6's broken and incomplete CSS2. */

	div.sidebar-content {
	background: #ffffee;
	border: 1px solid silver;
	padding: 0.5em;
	}
	div.sidebar-title, div.image-title {
	font-family: sans-serif;
	font-weight: bold;
	margin-top: 0.0em;
	margin-bottom: 0.5em;
	}

	div.listingblock div.content {
	border: 1px solid silver;
	background: #f4f4f4;
	padding: 0.5em;
	}

	div.quoteblock-content {
	padding-left: 2.0em;
	}

	div.exampleblock-content {
	border-left: 2px solid silver;
	padding-left: 0.5em;
	}

	/* IE6 sets dynamically generated links as visited. */
	div#toc a:visited { color: blue; }
	</style>
	<title>git-submodule(1)</title>
	</head>
	<body>
	<div id="header">
	<h1>
	git-submodule(1) Manual Page
	</h1>
	<h2>NAME</h2>
	<div class="sectionbody">
	<p>git-submodule -
	Initialize, update or inspect submodules
	</p>
	</div>
	</div>
	<h2>SYNOPSIS</h2>
	<div class="sectionbody">
	<div class="verseblock">
	<div class="content"><em>git submodule</em> [--quiet] add [-b branch] [--] <repository> [<path>]
	<em>git submodule</em> [--quiet] status [--cached] [--] [<path>…]
	<em>git submodule</em> [--quiet] init [--] [<path>…]
	<em>git submodule</em> [--quiet] update [--init] [--] [<path>…]
	<em>git submodule</em> [--quiet] summary [--summary-limit <n>] [commit] [--] [<path>…]</div></div>
	</div>
	<h2 id="_commands">COMMANDS</h2>
	<div class="sectionbody">
	<div class="vlist"><dl>
	<dt>
	add
	</dt>
	<dd>
	<p>
	Add the given repository as a submodule at the given path
	to the changeset to be committed next. If path is a valid
	repository within the project, it is added as is. Otherwise,
	repository is cloned at the specified path. path is added to the
	changeset and registered in .gitmodules. If no path is
	specified, the path is deduced from the repository specification.
	If the repository url begins with ./ or ../, it is stored as
	given but resolved as a relative path from the main project's
	url when cloning.
	</p>
	</dd>
	<dt>
	status
	</dt>
	<dd>
	<p>
	Show the status of the submodules. This will print the SHA-1 of the
	currently checked out commit for each submodule, along with the
	submodule path and the output of <em>git-describe</em> for the
	SHA-1. Each SHA-1 will be prefixed with <tt>-</tt> if the submodule is not
	initialized and <tt>+</tt> if the currently checked out submodule commit
	does not match the SHA-1 found in the index of the containing
	repository. This command is the default command for <em>git-submodule</em>.
	</p>
	</dd>
	<dt>
	init
	</dt>
	<dd>
	<p>
	Initialize the submodules, i.e. register in .git/config each submodule
	name and url found in .gitmodules. The key used in .git/config is
	<tt>submodule.$name.url</tt>. This command does not alter existing information
	in .git/config.
	</p>
	</dd>
	<dt>
	update
	</dt>
	<dd>
	<p>
	Update the registered submodules, i.e. clone missing submodules and
	checkout the commit specified in the index of the containing repository.
	This will make the submodules HEAD be detached.
	</p>
	<div class="para"><p>If the submodule is not yet initialized, and you just want to use the
	setting as stored in .gitmodules, you can automatically initialize the
	submodule with the --init option.</p></div>
	</dd>
	<dt>
	summary
	</dt>
	<dd>
	<p>
	Show commit summary between the given commit (defaults to HEAD) and
	working tree/index. For a submodule in question, a series of commits
	in the submodule between the given super project commit and the
	index or working tree (switched by --cached) are shown.
	</p>
	</dd>
	</dl></div>
	</div>
	<h2 id="_options">OPTIONS</h2>
	<div class="sectionbody">
	<div class="vlist"><dl>
	<dt>
	-q
	</dt>
	<dt>
	--quiet
	</dt>
	<dd>
	<p>
	Only print error messages.
	</p>
	</dd>
	<dt>
	-b
	</dt>
	<dt>
	--branch
	</dt>
	<dd>
	<p>
	Branch of repository to add as submodule.
	</p>
	</dd>
	<dt>
	--cached
	</dt>
	<dd>
	<p>
	This option is only valid for status and summary commands. These
	commands typically use the commit found in the submodule HEAD, but
	with this option, the commit stored in the index is used instead.
	</p>
	</dd>
	<dt>
	-n
	</dt>
	<dt>
	--summary-limit
	</dt>
	<dd>
	<p>
	This option is only valid for the summary command.
	Limit the summary size (number of commits shown in total).
	Giving 0 will disable the summary; a negative number means unlimited
	(the default). This limit only applies to modified submodules. The
	size is always limited to 1 for added/deleted/typechanged submodules.
	</p>
	</dd>
	<dt>
	<path>
	</dt>
	<dd>
	<p>
	Path to submodule(s). When specified this will restrict the command
	to only operate on the submodules found at the specified paths.
	</p>
	</dd>
	</dl></div>
	</div>
	<h2 id="_files">FILES</h2>
	<div class="sectionbody">
	<div class="para"><p>When initializing submodules, a .gitmodules file in the top-level directory
	of the containing repository is used to find the url of each submodule.
	This file should be formatted in the same way as <tt>$GIT_DIR/config</tt>. The key
	to each submodule url is "submodule.$name.url". See <a href="gitmodules.html">gitmodules(5)</a>
	for details.</p></div>
	</div>
	<h2 id="_author">AUTHOR</h2>
	<div class="sectionbody">
	<div class="para"><p>Written by Lars Hjemli <hjemli@gmail.com></p></div>
	</div>
	<h2 id="_git">GIT</h2>
	<div class="sectionbody">
	<div class="para"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
	</div>
	<div id="footer">
	<div id="footer-text">
	Last updated 2008-07-06 05:17:04 UTC
	</div>
	</div>
	</body>
	</html>