<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE appendix SYSTEM "../../dtd/dblite.dtd">
<appendix id="tgit-app-internals" xmlns:xi="http://www.w3.org/2001/XInclude">
	<title>Implementation Details</title>
	<simplesect>
		<para>
			This appendix contains a more detailed discussion of the
			implementation of some of TortoiseGit's features.
		</para>
	</simplesect>
	<sect1 id="tgit-app-internals-overlays">
		<title>Icon Overlays</title>
		<indexterm>
			<primary>overlay priority</primary>
		</indexterm>
		<indexterm>
			<primary>overlays</primary>
		</indexterm>
		<para>
			Every file has a Git status value as reported
			by the Git library. In the command line client, these
			are represented by single letter codes, but in TortoiseGit they
			are shown graphically using the icon overlays. Because the number
			of overlays is very limited, each overlay may represent one of
			several status values.
		</para>
		<para>
			<graphic fileref="images/ConflictIcon.png"/>
			The <emphasis>Conflicted</emphasis> overlay is used to
			represent the <literal>conflicted</literal> state, where
			a merge resulted in conflicts between the
			changes of the current and changes from another branch.
		</para>
		<para>
			<graphic fileref="images/ModifiedIcon.png"/>
			The <emphasis>Modified</emphasis> overlay represents the
			<literal>modified</literal> state, where you have made
			local modifications to your working tree.
		</para>
		<para>
			<graphic fileref="images/DeletedIcon.png"/>
			The <emphasis>Deleted</emphasis> overlay represents the
			<literal>deleted</literal> state, where an item is scheduled for
			deletion, or the <literal>missing</literal> state, where an
			item is not present but still in the Git index. Naturally an item which is missing cannot have
			an overlay itself, but the parent folder can be marked if one of its
			child items is missing.
		</para>
		<para>
			<graphic fileref="images/AddedIcon.png"/>
			The <emphasis>Added</emphasis> overlay is simply used to
			represent the <literal>added</literal> status when an item
			has been added to version control.
		</para>
		<para>
			<graphic fileref="images/InGitIcon.png"/>
			The <emphasis>In Git</emphasis> overlay is used to
			represent an item which is in the <literal>normal</literal>
			state.
			<!--, or a versioned item whose state is not yet known.
			Because TortoiseGit uses a background caching process to
			gather status, it may take a few seconds before the overlay
			updates.-->
		</para>
		<para>
			<graphic fileref="images/ReadOnlyIcon.png"/>
			The <emphasis>assume-valid</emphasis> (<emphasis>Needs Lock</emphasis> in TortoiseSVN) overlay is used to
			indicate if a file has the <literal>assume-valid</literal>
			flag set.
		</para>
		<para>
			<graphic fileref="images/LockedIcon.png"/>
			The <emphasis>skip-worktree</emphasis> (<emphasis>Locked</emphasis> in TortoiseSVN) overlay is used when to
			indicate if a file has the <literal>skip-worktree</literal>
			flag set.
		</para>
		<para>
			<graphic fileref="images/IgnoredIcon.png"/>
			The <emphasis>Ignored</emphasis> overlay is used to
			represent an item which is in the <literal>ignored</literal>
			state, either due to a global ignore pattern, or due to a
			<filename>.gitignore</filename> file in one of the parent folders.
			This overlay is optional.
		</para>
		<para>
			<graphic fileref="images/UnversionedIcon.png"/>
			The <emphasis>Unversioned</emphasis> overlay is used to
			represent an item which is in the <literal>unversioned</literal>
			state. This is an item in a versioned folder, but which is not
			under version control itself.
			This overlay is optional.
		</para>
		<para>
			If an item has Git status <literal>none</literal> (the item
			is not within a working tree) then no overlay is shown.
			If you have chosen to disable the <emphasis>Ignored</emphasis>
			and <emphasis>Unversioned</emphasis> overlays then no overlay
			will be shown for those files either.
		</para>
		<para>
			An item can only have one Git status value. For example
			a file could be locally modified and it could be marked for
			deletion at the same time. Git returns a single status
			value - in this case <literal>deleted</literal>.
			Those priorities are defined within Git and TortoiseGit itself.
		</para>
		<para>
			When TortoiseGit displays the status recursively (the default
			setting), each folder displays an overlay reflecting its own
			status and the status of all its children. In order to display
			a single <emphasis>summary</emphasis> overlay, we use the
			priority order shown above to determine which overlay to use,
			with the <emphasis>Conflicted</emphasis> overlay taking highest
			priority.
		</para>
		<para>
			In fact, you may find that not all of these icons are used on your
			system. This is because the number of overlays allowed by Windows
			is limited to 15. Windows uses 4 of those, and the remaining 11
			can be used by other applications. If there are not enough overlay
			slots available, TortoiseGit tries to be a
			<emphasis>Good Citizen (TM)</emphasis> and limits its use of overlays to
			give other apps a chance.
		</para>
		<para>
			If you have problems with overlays, please see the online
			<ulink url="https://tortoisegit.org/support/faq/#ovlnotshowing"><citetitle>FAQ</citetitle></ulink>.
		</para>
		<para>
			Since there are Tortoise clients available for other version control
			systems, the TortoiseSVN developers created a shared component which is responsible for
			showing the overlay icons. The technical details are not important
			here, all you need to know is that this shared component allows
			all Tortoise clients to use the same overlays and therefore the
			limit of 11 available slots isn't used up by installing more than one
			Tortoise client. Of course there's one small drawback: all Tortoise
			clients use the same overlay icons, so you can't figure out by
			the overlay icons what version control system a working copy is
			using.
		</para>
		<itemizedlist>
			<listitem>
				<para>
					<emphasis>Normal</emphasis>,
					<emphasis>Modified</emphasis> and
					<emphasis>Conflicted</emphasis>
					are always loaded and visible.
				</para>
			</listitem>
			<listitem>
				<para>
					<emphasis>Deleted</emphasis>
					is loaded if possible, but falls back to
					<emphasis>Modified</emphasis> if there are not enough slots.
				</para>
			</listitem>
			<listitem>
				<para>
					<emphasis>assume-valid</emphasis>
					is loaded if possible, but falls back to
					<emphasis>Normal</emphasis> if there are not enough slots.
				</para>
			</listitem>
			<listitem>
				<para>
					<emphasis>skip-worktree</emphasis>
					is loaded if possible, but falls back to
					<emphasis>Normal</emphasis> if there are not enough slots.
				</para>
			</listitem>
			<listitem>
				<para>
					<emphasis>Added</emphasis>
					is loaded if possible, but falls back to
					<emphasis>Modified</emphasis> if there are not enough slots.
				</para>
			</listitem>
		</itemizedlist>
	</sect1>
</appendix>
