<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect2 SYSTEM "../../../dtd/dblite.dtd">
<sect2 id="tgit-dug-settings-overlay">
	<title>Icon Overlay Settings</title>
	<?dbhh topicname="HIDD_SETTINGSOVERLAY"?>
	<para>
		<figure id="tgit-dug-settings-dia-overlay">
			<title>The Settings Dialog, Icon Overlays Page</title>
			<graphic fileref="../images/SettingsOverlay.png"/>
		</figure>
		This page allows you to choose the items for which TortoiseGit will
		display icon overlays.
	</para>
	<para>
		By default, overlay icons and context menus will appear in all open/save
		dialogs as well as in Windows Explorer. If you want them to appear
		<emphasis>only</emphasis> in Windows Explorer, check the
		<guilabel>Show overlays and context menu only in explorer</guilabel> box.
	</para>
	<para>
		Ignored items and Unversioned items are not usually given an overlay.
		If you want to show an overlay in these cases, just check the boxes.
	</para>
	<para>
		You can also choose to mark folders as
		modified if they contain unversioned items. This could be useful for
		reminding you that you have created new files which are not yet versioned.
		This option is only available when you use the <emphasis>default</emphasis>
		status cache option (see below).
	</para>
	<para>
		Since it takes quite a while to fetch the status of a working tree,
		TortoiseGit uses a cache to store the status so the explorer
		doesn't get hogged too much when showing the overlays.
		You can choose which type of cache TortoiseGit should use according
		to your system and working tree size here:
		<variablelist>
			<varlistentry>
				<term>Default</term>
				<listitem>
					<para>
						Caches all status information in a separate process
						(<filename>TGitCache.exe</filename>). That process
						watches all drives for changes and fetches the status
						again if files inside a working tree get modified.
						The process runs with the least possible priority so
						other programs don't get hogged because of it. That
						also means that the status information is not
						<emphasis>real time</emphasis> but it can take a few
						seconds for the overlays to change.
					</para>
					<para>
						Advantage: the overlays show the status recursively,
						i.e. if a file deep inside a working tree is modified,
						all folders up to the working tree root will also
						show the modified overlay. And since the process can
						send notifications to the shell, the overlays on the left
						tree view usually change too.
					</para>
					<para>
						Disadvantage: the process runs constantly, even if you're not
						working on your projects. It also uses around 10-50 MB of RAM
						depending on number and size of your working trees. From version 1.7.0 to 1.7.12
						TGitCache did not check the contents of the files,
						it just checked the last modification time against the time stored
						in the git index file.
						Starting from 1.7.13 TGitCache now also checks the contents of the files by default.
						If you want to restore the old behavior, you can disable checking the contents
						via the Settings dialog -> Advanced and set <literal>TGitCacheCheckContentMaxSize</literal> to "0".
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>Shell Extended</term>
				<listitem>
					<para>
						Caching is done directly inside the shell extension
						DLL.
						Each time you navigate to another folder, the status
						information is fetched again (recursively).
					</para>
					<para>
						Advantage: can show the status in <emphasis>real time</emphasis>.
					</para>
					<para>
						Disadvantage: only one folder is cached and for big working trees,
						it can take much more time to show a folder in explorer than
						with the default cache or with shell mode. The Shell variant only shows
						differences of the filesystem to the git index (does not include revision
						specific information, e.g. if you remove a file from the index the file will
						show up as unversioned, but with TGitCache the file will show up as deleted
						until you commit this change).
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>Shell</term>
				<listitem>
					<para>
						Caching is done directly inside the shell extension
						DLL, but only for the currently visible folder.
						Each time you navigate to another folder, the status
						information is fetched again.
					</para>
					<para>
						Advantage: needs only very little memory (around 1 MB of RAM)
						and can show the status in <emphasis>real time</emphasis>.
					</para>
					<para>
						Disadvantage: Since only one folder is cached, the overlays
						don't show the status recursively. For big working trees,
						it can take more time to show a folder in explorer than
						with the default cache. The Shell variant only shows
						differences of the filesystem to the git index (does not include revision
						specific information, e.g. if you remove a file from the index the file will
						show up as unversioned, but with TGitCache the file will show up as deleted
						until you commit this change).
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>None</term>
				<listitem>
					<para>
						With this setting, the TortoiseGit does not fetch the status
						at all in Explorer. Because of that, files don't get an overlay
						and folders only get a 'normal' overlay if they're versioned.
						No other overlays are shown, and no extra columns are available
						either.
					</para>
					<para>
						Advantage: uses absolutely no additional memory and does
						not slow down the Explorer at all while browsing.
					</para>
					<para>
						Disadvantage: Status information of files and folders is not
						shown in Explorer. To see if your working trees are modified,
						you have to use the <quote>Check for modifications</quote> dialog.
					</para>
				</listitem>
			</varlistentry>
		</variablelist>
	</para>
	<para>
		By default, overlay icons and context menus will appear in all open/save
		dialogs as well as in Windows Explorer. If you want them to appear
		<emphasis>only</emphasis> in Windows Explorer, check the
		<guilabel>Show overlays and context menu only in explorer</guilabel> box.
	</para>
	<para>
		You can force the status cache to <emphasis>None</emphasis> for elevated
		processes by checking the
		<guilabel>Disable status cache for elevated processes</guilabel> box.
		This is useful if you want to prevent another <filename>TGitCache.exe</filename>
		process getting created with elevated privileges.
	</para>
	<para>
		You can also choose to mark folders as
		modified if they contain unversioned items. This could be useful for
		reminding you that you have created new files which are not yet versioned.
		This option is only available when you use the <emphasis>default</emphasis>
		status cache option (see below).
	</para>
	<para>
		The next group allows you to select which classes of storage should
		show overlays. By default, only hard drives are selected.
		You can even disable all icon overlays, but where's the fun in that?
	</para>
	<para>
		Network drives can be very slow, so by default
		icons are not shown for working trees located on network shares.
	</para>
	<para>
		USB Flash drives appear to be a special case in that the drive type
		is identified by the device itself. Some appear as fixed drives,
		and some as removable drives.
	</para>
	<para>
		The <guilabel>Exclude Paths</guilabel> are used to tell TortoiseGit
		those paths for which it should <emphasis>not</emphasis> show icon
		overlays and status columns.
		This is useful if you have some very big working trees containing
		only libraries which you won't change at all and therefore don't
		need the overlays, or if you only want TortoiseGit to look in
		specific folders.
	</para>
	<para>
		Any path you specify here is assumed to apply recursively, so none of the
		child folders will show overlays either. If you want to exclude
		<emphasis>only</emphasis> the named folder, append <literal>?</literal>
		after the path.
	</para>
	<para>
		The same applies to the <guilabel>Include Paths</guilabel>. Except that
		for those paths the overlays are shown even if the overlays are disabled
		for that specific drive type, or by an exclude path specified above.
	</para>
	<para>
		Users sometimes ask how these three settings interact. For any given path
		check the include and exclude lists, seeking upwards through the directory
		structure until a match is found. When the first match is found, obey that
		include or exclude rule. If there is a conflict, a single directory spec
		takes precedence over a recursive spec, then inclusion takes precedence over
		exclusion.
	</para>
	<para>
		An example will help here:
		<screen>
Exclude:
C:
C:\develop\?
C:\develop\tgit\obj
C:\develop\tgit\bin

Include:
C:\develop
		</screen>
		These settings disable icon overlays for the C: drive, except for
		<literal>c:\develop</literal>. All projects below that directory will
		show overlays, except the <literal>c:\develop</literal> folder itself,
		which is specifically ignored. The high-churn binary folders are also
		excluded.
	</para>
	<para>
		TGitCache.exe also uses these paths to restrict its scanning. If you
		want it to look only in particular folders, disable all drive types
		and include only the folders you specifically want to be scanned.
	</para>
	<tip>
		<title>Exclude <literal>SUBST</literal> Drives</title>
		<indexterm>
			<primary>SUBST drives</primary>
		</indexterm>
		<para>
			It is often convenient to use a <literal>SUBST</literal> drive
			to access your working trees, e.g. using the command
<screen>
subst T: C:\TortoiseGit\doc
</screen>
			However this can cause the overlays not to update, as
			<literal>TGitCache</literal> will only receive one notification when
			a file changes, and that is normally for the original path. This means
			that your overlays on the <literal>subst</literal> path may never
			be updated.
		</para>
		<para>
			An easy way to work around this is to exclude the original path
			from showing overlays, so that the overlays show up on the
			<literal>subst</literal> path instead.
		</para>
	</tip>
	<para>
		Sometimes you will exclude areas that contain working trees,
		which saves TGitCache from scanning and monitoring for changes,
		but you still want a visual indication that a folder contains a working tree.
		The <guilabel>Show excluded folders as 'normal'</guilabel> checkbox
		allows you to do this. With this option, working tree folders in any
		excluded area (drive type not checked, or specifically excluded)
		will show up as normal and up-to-date, with a green check
		mark. This reminds you that you are looking at a working tree, even
		though the folder overlays may not be correct. Files do not get an
		overlay at all. Note that the context menus still work, even though
		the overlays are not shown.
	</para>
	<para>
		As a special exception to this, drives <literal>A:</literal>
		and <literal>B:</literal> are never considered for the
		<guilabel>Show excluded folders as 'normal'</guilabel> option.
		This is because Windows is forced to look on the drive, which can
		result in a delay of several seconds when starting Explorer, even
		if your PC does have a floppy drive.
	</para>
	<sect3 id="tgit-dug-settings-icon-set">
		<title>Icon Set Selection</title>
		<?dbhh topicname="HIDD_SETOVERLAYICONS"?>
		<para>
			<figure id="tgit-dug-settings-dia-icons">
				<title>The Settings Dialog, Icon Set Page</title>
				<graphic fileref="../images/SettingsOverlayChooser.png"/>
			</figure>
			You can change the overlay icon set to the one you like best. Especially you can disable overlays which you do not need like assume-valid and skip-worktree, however other Tortoise* tools use these two for different purposes.
			Note that if you change overlay set, you may have to restart
			your computer for the changes to take effect.
		</para>
	</sect3>
	<sect3 id="tgit-dug-settings-overlay-handlers">
		<title>Enabled Overlay Handlers</title>
		<?dbhh topicname="HIDD_SETTINGSOVERLAYHANDLERS"?>
		<para>
			<figure id="tgit-dug-settings-dia-overlay-handlers">
				<title>The Settings Dialog, Icon Handlers Page</title>
				<graphic fileref="../images/SettingsOverlayHandlers.png"/>
			</figure>
			Because the number of overlays available is severely restricted,
			you can choose to disable some handlers to ensure that the ones
			you want will be loaded. Because TortoiseGit uses the common
			TortoiseOverlays component which is shared with other Tortoise
			clients (e.g. TortoiseSVN, TortoiseCVS, TortoiseHg) this setting will affect
			those clients too.
		</para>
		<para>
			For a description of how icon overlays correspond to Git
			status and other technical details, read
			<xref linkend="tgit-app-internals-overlays"/>.
		</para>
		<para>
			Windows explorer can just handle a fixed number different overlay providers (15) and TortoiseGit is using 6 of these
			(these 6 are handled by TortoiseOverlays and, thus, shared with TortoiseSVN and TortoiseCVS). If the TortoiseGit icons
			are not correctly displayed this is likely caused by other programs which provide overlays (like DropBox, Owncloud, BoxSync
			and various others) and register with a higher priority. Use the <guilabel>Start registry editor</guilabel> button for opening
			the registry editor at the key where the overlay handlers are registered. Just delete or rename the ones you don't need OR
			prepend the <literal>Tortoise</literal> ones with a double quote or space characters so that those come first in the list.
			For more information please see <ulink url="https://tortoisegit.org/support/faq/#ovlnotshowing">TortoiseGit FAQ</ulink>.
		</para>
	</sect3>
</sect2>
