<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect2 SYSTEM "../../../dtd/dblite.dtd">
<sect2 id="tsvn-dug-settings-logcache">
	<?dbhh topicname="HIDD_SETTINGSLOGCACHE"?>
	<title>Log Caching</title>
	<indexterm>
		<primary>log cache</primary>
	</indexterm>
	<para>
		<figure id="tsvn-dug-settings-dia-logcache">
			<title>The Settings Dialog, Log Cache Page</title>
			<graphic fileref="../images/SettingsLogCache.png"/>
		</figure>
		This dialog allows you to configure the log caching feature of
		TortoiseGit, which retains a local copy of log messages and changed
		paths to avoid time-consuming downloads from the server. Using the
		log cache can dramatically speed up the log dialog and the revision graph.
		Another useful feature is that the log messages can still be
		accessed when offline.
	</para>
	<para>
		<variablelist>
			<varlistentry>
				<term>Enable log caching</term>
				<listitem>
					<para>
						Enables log caching whenever log data is requested.
						If checked, data will be retrieved from the cache when
						available, and any messages not in the cache will be retrieved
						from the server and added to the cache.
					</para>
					<para>
						If caching is disabled, data will always be retrieved
						directly from the server and not stored locally.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>Allow ambiguous URLs</term>
				<listitem>
					<para>
						Occasionally you may have to connect to a server which uses
						the same URL for all repositories. Older versions of
						<literal>svnbridge</literal> would do this. If you need to
						access such repositories you will have to check this option.
						If you don't, leave it unchecked to improve performance.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>Allow ambiguous UUIDs</term>
				<listitem>
					<para>
						Some hosting services give all their repositories the same
						UUID. You may even have done this yourself by copying a
						repository folder to create a new one. For all sorts of
						reasons this is a bad idea - a UUID should be
						<emphasis>unique</emphasis>. However, the log cache will
						still work in this situation if you check this box.
						If you don't need it, leave it unchecked to improve performance.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>If the repository cannot be contacted</term>
				<listitem>
					<para>
						If you are working offline, or if the repository server
						is down, the log cache can still be used to supply log
						messages already held in the cache. Of course the cache
						may not be up-to-date, so there are options to allow you
						to select whether this feature should be used.
					</para>
					<para>
						When log data is being taken from the cache without contacting
						the server, the dialog using those message will show the offline
						state in its title bar.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>Timeout before updating the HEAD revision</term>
				<listitem>
					<para>
						When you invoke the log dialog you will normally want to
						contact the server to check for any newer log messages.
						If the timeout set here is non-zero then the server will
						only be contacted when the timeout has elapsed since the
						last time contact. This can reduce server round-trips
						if you open the log dialog frequently and the server is
						slow, but the data shown may not be completely up-to-date.
						If you want to use this feature we suggest using a value
						of 300 (5 minutes) as a compromise.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>Days of inactivity until small caches get removed</term>
				<listitem>
					<para>
						If you browse around a lot of repositories you will
						accumulate a lot of log caches. If you're not actively
						using them, the cache will not grow very big, so
						TortoiseGit purges them after a set time by default.
						Use this item to control cache purging.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>Maximum size of removed inactive caches</term>
				<listitem>
					<para>
						Larger caches are more expensive to reacquire, so
						TortoiseGit only purges small caches. Fine tune the
						threshold with this value.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>Maximum number of tool failures before cache removal</term>
				<listitem>
					<para>
						Occasionally something goes wrong with the caching and
						causes a crash. If this happens the cache is normally
						deleted automatically to prevent a recurrence of the problem.
						If you use the less stable nightly build you may opt to
						keep the cache anyway.
					</para>
				</listitem>
			</varlistentry>
		</variablelist>
	</para>
	<para>
		On the next page you can see a list of the repositories that are
		cached locally, and the space used for the cache. If you select one
		of the repositories you can then use the buttons underneath.
	</para>
	<sect3 id="tsvn-dug-settings-logcache-statistics">
		<?dbhh topicname="HIDD_IDD_LOGCACHESTATISTICS"?>
		<title>Log Cache Statistics</title>
		<para>
			<figure id="tsvn-dug-settings-dia-logcache-stats">
				<title>The Settings Dialog, Log Cache Statistics</title>
				<graphic fileref="../images/SettingsLogStats.png"/>
			</figure>
			Click on the <guibutton>Details</guibutton> button to see
			detailed statistics for a particular cache. Many of the fields
			shown here are mainly of interest to the developers of TortoiseGit,
			so they are not all described in detail.
			<variablelist>
				<varlistentry>
					<term>RAM</term>
					<listitem>
						<para>
							The amount of memory required to service this cache.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Disk</term>
					<listitem>
						<para>
							The amount of disk space used for the cache. Data is
							compressed, so disk usage is generally fairly modest.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Connection</term>
					<listitem>
						<para>
							Shows whether the repository was available last time
							the cache was used.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Last update</term>
					<listitem>
						<para>
							The last time the cache content was changed.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Last head update</term>
					<listitem>
						<para>
							The last time we requested the HEAD revision from
							the server.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Authors</term>
					<listitem>
						<para>
							The number of different authors with messages recorded
							in the cache.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Paths</term>
					<listitem>
						<para>
							The number of paths listed, as you would see using
							<literal>svn log -v</literal>.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Skip ranges</term>
					<listitem>
						<para>
							The number of revision ranges which we have not fetched,
							simply because they haven't been requested. This is a
							measure of the number of holes in the cache.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Max revision</term>
					<listitem>
						<para>
							The highest revision number stored in the cache.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Revision count</term>
					<listitem>
						<para>
							The number of revisions stored in the cache.
							This is another measure of cache completeness.
						</para>
					</listitem>
				</varlistentry>
			</variablelist>
		</para>
	</sect3>
	<para>
		Click on the <guibutton>Update</guibutton> to completely refresh the
		cache and fill in any holes. For a large repository this could be
		very time consuming, but useful if you are about to go offline
		and want the best available cache.
	</para>
	<para>
		Click on the <guibutton>Export</guibutton> button to export the entire
		cache as a set of CSV files. This could be useful if you want to process
		the log data using an external program, although it is mainly useful to
		the developers.
	</para>
	<para>
		Click on <guibutton>Delete</guibutton> to remove all cached data for
		the selected repositories. This does not disable caching for the repository
		so the next time you request log data, a new cache will be created.
	</para>
</sect2>
