<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">
<sect1 id="tgit-dug-submodules">
	<?dbhh topicname="HIDD_SUBMODULE_ADD"?>
	<?dbhh topicname="HIDD_SUBMODULE_UPDATE"?>
	<title>Submodules</title>
	<para>
		When you want to embed foreign repositories into a working tree/git repository, this is called a submodule.
		Here using the
		<menuchoice>
			<guimenu>TortoiseGit</guimenu>
			<guimenuitem>Submodules Add</guimenuitem>
		</menuchoice>
		option a foreign repository can be embedded into a dedicated sub directory of the source tree.
		When selecting this option, a dialog pops up:
		<figure id="tgit-dug-submodules-dia-1">
			<title>The add submodule dialog</title>
			<graphic fileref="../images/GitSubModuleAdd.png"/>
		</figure>
		Here you can enter the location/URL of the <guilabel>Repository</guilabel> you want to embed
		into the directory <guilabel>Path</guilabel>. <guilabel>Path</guilabel> can be entered as a relative
		path within the active source tree, but can also be an absolute path (pointing to the active source tree).
		The folder should be empty or non existent.
		If you don't want to integrate the HEAD of the <guilabel>Repository</guilabel>, you can enter a different
		<guilabel>Branch</guilabel>.
		By pressing <guibutton>OK</guibutton>, the entered <guilabel>Repository</guilabel> is cloned and integrated
		into the current source tree.
	</para>
	<para>
		If a working tree contains submodules, two new context menu entries are available:
		<figure id="tgit-dug-submodules-dia-2">
			<title>Submodule context menu entries</title>
			<graphic fileref="../images/ContextMenuSubmodules.png"/>
		</figure>
	</para>
	<para>
		<guimenuitem>Submodule Update</guimenuitem>:
		<figure id="tgit-dug-submodules-update">
			<title>The update submodule dialog</title>
			<graphic fileref="../images/SubmoduleUpdate.png"/>
		</figure>
		Initialize the submodules and/or update the registered submodules, i.e. clone missing submodules and checkout the commit specified in the index of the containing repository.
	</para>
	<para>
		<guimenuitem>Submodule Sync</guimenuitem>: Synchronizes submodules' remote URL configuration setting to the value specified in <filename>.gitmodules</filename>. This is useful when submodule URLs change upstream and you need to update your local repositories accordingly.
	</para>
	<para>
		Also if a working tree contains submodules, <xref linkend="tgit-dug-checkout"/> and <xref linkend="tgit-dug-reset"/> contain a button for updating submodules:
		<figure id="tgit-dug-submodules-dia-3">
			<title>Button for updating submodules in progress dialog</title>
			<graphic fileref="../images/CheckoutSubmodules.png"/>
		</figure>
	</para>
	<para>
		You can find more information at <gitdoclink cmd="git-submodule" section="1"/>.
	</para>
</sect1>
