<?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
    TortoiseSVN, 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, unchecked it 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, unchecked it 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
            TortoiseSVN 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
            TortoiseSVN 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>
  <sect3 id="tsvn-dug-settings-logcache-repolist">
    <?dbhh topicname="HIDD_SETTINGSLOGCACHELIST"?>
    <title>Cached Repositories</title>
    <para>
      On this 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>
    <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>
  </sect3>
  <sect3 id="tsvn-dug-settings-logcache-statistics">
    <?dbhh topicname="HIDD_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 TortoiseSVN,
      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>
</sect2>
