path: root/doc/en/synchronizer.docbook

<sect1 id="synchronizer">
  <title>Synchronizer</title>
  <indexterm>
    <primary>Synchronizer</primary>
  </indexterm>
  
<sect2 id="synchronizer_introduction">
  <title>Introduction</title>    
  <para>This function compares two directories with all subdirectories and shows the differences between them.
  After selecting some options and the 
  <guilabel>Compare</guilabel> function you can synchronize the
  files and directories. One panel could be an &FTP;
  server. Do not forget the 
  <guilabel>Compare by content</guilabel> option if the file size
  stays equal. Choose 
  <emphasis role="bold">
    <menuchoice>
      <guimenu>Commands</guimenu>
      <guimenuitem>Synchronize Directories</guimenuitem>
    </menuchoice>
  </emphasis>or 
  <keycombo action="simul">&Ctrl;
  <keycap>Y</keycap></keycombo> to start this feature. The 
  <link linkend="konfig-color">colors</link> are
  configurable.</para>
  <note>
    <para>For local files: The synchronizer changes the date
    information to the original dates.</para>
  </note>
  <!-- OLD
<screenshot>
  <screeninfo>Synchronizer</screeninfo>
  <mediaobject>
  <imageobject><imagedata fileref="syncdir.png" format="PNG"/></imageobject>
  <imageobject><imagedata fileref="syncdir.png" format="EPS"/></imageobject>
  <textobject><phrase>Synchronizer: Synchronize files and directories.</phrase></textobject>
  <caption><para>Synchronizer: Synchronize files and directories.</para></caption>
  </mediaobject>
</screenshot>
-->
  <figure id="screenshot-syncdir" float="1">
    <title>Synchronizer</title>
    <mediaobject>
      <imageobject>
        <imagedata fileref="syncdir.png"></imagedata>
      </imageobject>
      <textobject>
        <phrase>Synchronizer</phrase>
      </textobject>
    </mediaobject>
  </figure>
  <para>
  <orderedlist>
    <title>Procedure:</title>
    <listitem>
      <para>Set the 
      <guilabel>Left directory</guilabel> and the 
      <guilabel>Right directory</guilabel> that you want to compare.</para>
    </listitem>
    <listitem>
      <para>Configure the optional 
      <guilabel>File Filter</guilabel>, 
      <guilabel>General Filters</guilabel> and 
      <guilabel>Advanced filters</guilabel>. The 
      <guilabel>General Filters</guilabel> includes a 
      <guilabel>don't search in</guilabel> option which lets you
      exclude directories from comparision.</para>
    </listitem>
    <listitem>
      <para>Set the 
      <link linkend="synccomp_checkb_options">Checkbox
      options</link>: 
      <guilabel>Recurse subdirectories</guilabel>, 
      <guilabel>Follow symlinks</guilabel>, 
      <guilabel>Compare by content</guilabel>, 
      <guilabel>Ignore Date</guilabel>, 
      <guilabel>Asymmetric</guilabel>,  
      <guilabel>Ignore Case</guilabel> and
      <guilabel>Hidden hidden files</guilabel>.
      </para>
    </listitem>
    <listitem>
      <para>Click on the 
      <guibutton>Compare</guibutton> button to compare the
      directories.</para>
    </listitem>
    <listitem>
      <para>By using
      <link linkend="synccomp_show_options">Show options</link>,
      you can include/exclude particular file types. The files that
      are not on the list will be untouched by
      synchronization.</para>
    </listitem>
    <listitem>
      <para>If needed, you can change the 
      <guilabel>Task</guilabel> operations determined by the
      Comparator with the 
      <link linkend="synccomp_right-click">right click
      menu</link>.</para>
    </listitem>
    <listitem>
      <para>When you agree with the 
      <guibutton>Compare</guibutton> results, click on the 
      <guibutton>Synchronize</guibutton> button to show the
      synchronize dialog.</para>
    </listitem>
    <listitem>
      <para>After selecting the options of the 
      <link linkend="synchronizer">Synchronizer</link>, click on
      the 
      <guibutton>Start</guibutton> button to start the
      synchronization process.</para>
    </listitem>
  </orderedlist>A detailed explanation of all the functions and
  buttons is described in the following text.</para>

</sect2>

<sect2 id="synchronizer_comparator">
  <title>Comparator</title>  

  <variablelist>
    <varlistentry>
      <term>Panel elements</term>
      <listitem>
        <itemizedlist>
          <listitem>
            <para>
            <guilabel>Left Directory</guilabel>: The left side base
            directory.</para>
          </listitem>
          <listitem>
            <para>
            <guilabel>Right Directory</guilabel>: The right side
            base directory.</para>
          </listitem>
          <listitem>
            <para>
            <guilabel>File Filter</guilabel>: Filters the filenames
            at synchronizing. &eg; 
            <literal role="extension">*.png</literal> selects only
            files the names of which end with 
            <literal role="extension">.png</literal> Directories are
            listed if the directory name ends with 
            <literal role="extension">.png</literal> or if the
            directory contains files which end with 
            <literal role="extension">.png</literal> Multiple
            include/exclude example: 
            <literal role="extension">'*.cpp *.h |
            *.moc.cpp'</literal>includes 
            <literal role="extension">*.cpp *.h</literal> and
            exclude 
            <literal role="extension">*.moc.cpp</literal></para>
          </listitem>
          <listitem>
            <para>
            <guilabel>General filters</guilabel>: Search for,
            containing text</para>
          </listitem>
          <listitem>
            <para>
            <guilabel>Advanced filters</guilabel>: Size, date,
            ownership</para>
          </listitem>
        </itemizedlist>
      </listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <varlistentry>
      <term>Filename filtering criteria</term>
      <listitem>
        <itemizedlist>
          <listitem>
            <para>You can make use of wild cards. Multiple patterns
            are separated by space (means logical OR) and patterns
            are excluded from the search using the pipe symbol. If
            the pattern is ended with a slash (*pattern*/), it
            means that pattern relates to recursive search of
            directories.</para>
          </listitem>
          <listitem>
            <para>pattern - means to search those files/directories
            whose name is a pattern, recursive search goes through
            all subdirectories independently of the value of the
            pattern.</para>
          </listitem>
          <listitem>
            <para>pattern/ - means to search all files/directories,
            but recursive search goes through/excludes the
            directories whose name is a pattern.</para>
          </listitem>
          <listitem>
            <para>You can use quotation marks for names
            that contain spaces. Filter "Program Files" searches
            out those files/directories the name of which is <filename>Program
            Files</filename>.</para>
          </listitem>
          <listitem>
            <para>Examples:</para>
          </listitem>
          <listitem>
            <para>
              <literal role="extension">*.o</literal>
            </para>
          </listitem>
          <listitem>
            <para>
              <literal role="extension">*.h *.c??</literal>
            </para>
          </listitem>
          <listitem>
            <para>
              <literal role="extension">*.cpp *.h |
              *.moc.cpp</literal>
            </para>
          </listitem>
          <listitem>
            <para>
              <literal role="extension">* | CVS/ .svn/</literal>
            </para>
          </listitem>
          <listitem>
            <para>Note: the search term 'text' is equivalent to
            '*text*'.</para>
          </listitem>
        </itemizedlist>
      </listitem>
    </varlistentry>
    <varlistentry id="synccomp_checkb_options">
      <term>Checkbox options</term>
      <listitem>
        <itemizedlist>
          <listitem>
            <para>
            <guilabel>Recurse subdirectories</guilabel>: The
            Synchronizer walks through subdirectories when
            comparing.</para>
          </listitem>
          <listitem>
            <para>
            <guilabel>Follow symlinks</guilabel>: The Synchronizer
            follows the symbolic links to directories (not the
            files!).</para>
          </listitem>
          <listitem>
            <para>
            <guilabel>Compare by content</guilabel>: The files
            the sizes of which are equal will be compared by content as
            well.</para>
          </listitem>
          <listitem>
            <para>
            <guilabel>Ignore Date</guilabel>: Ignores the date
            information (useful for &FTP;, smb, archive,
            ... ) the date information is relevant *only* in the
            local file system.</para>
          </listitem>
          <listitem>
            <para>
            <guilabel>Asymmetric</guilabel>: The 
            <guilabel>Left Directory</guilabel> is the target
            directory, the 
            <guilabel>Right Directory</guilabel> is the source
            directory. This functions synchronizes the content of
            the left directory to the right directory. 
            <itemizedlist>
              <listitem>
                <para>The files that exist only on the left side
                will be deleted.</para>
              </listitem>
              <listitem>
                <para>The files that exist only on the right side
                will be copied to left.</para>
              </listitem>
              <listitem>
                <para>The files considered to be equal will be
                untouched.</para>
              </listitem>
              <listitem>
                <para>Those files considered to be different will
                be copied to left. Use this feature with
                care!</para>
              </listitem>
            </itemizedlist>This function is useful if the date
            information is unusable, or to synchronize the left
            directory to the content of a file server (like a
            download). Alternatively, it is useful to make a backup
            from the right directory to the left directory. NOTE:
            Do NOT use this option to synchronize a desktop and a
            notebook (&eg; files that exist only on the
            left side will be deleted!).</para>
          </listitem>
          <listitem>
            <para>
            <guilabel>Automatic Scrolling</guilabel>: This is for
            slow &FTP; servers, ... When the
            Synchronizer has finished comparing a file, it puts the
            file into the end of the list at once and scrolls the
            window, if necessary. It is important, if you want to
            know what the Synchronizer is doing. If the
            &FTP; server is slow, the comparison of a
            directory may take a lot of time. By turning this
            option on, you can see that the comparator is "alive",
            but slow. For fast file systems, it can reduce the
            speed of comparing slightly.</para>
          </listitem>
          <listitem>
            <para>
            <guilabel>Ignore Case</guilabel>: Case insensitive filename compare, 
            this is useful when synchronizing &Windows; filesystems.</para>
          </listitem>
          <listitem>
            <para>
            <guilabel>Ignore hidden files</guilabel>: Ignores files that start with a dot.</para>
          </listitem>
        </itemizedlist>
      </listitem>
    </varlistentry>
  </variablelist>
  <para>When everything mentioned above is done, click on the 
  <guibutton>Compare</guibutton> button to compare the directories,
  the results are displayed in the <guilabel>File List</guilabel>.</para>
  <variablelist>
    <varlistentry>
      <term>File List</term>
      <listitem>
        <para>The 
        <guilabel>File List</guilabel> has the following columns:
        "Left name | Left size | Left time | Task | Right time |
        Right size | Right name".
        Here you can check the compare results and modify the synchronisation actions if desired.
        The text color defines the default copy direction determined by the comparator.
        <itemizedlist>
              <listitem>
                <para>Green: Copy from left to right.</para>
              </listitem>
              <listitem>
                <para>Blue: Copy from right to left or delete on the right side in asymmetric mode.</para>
              </listitem>
              <listitem>
                <para>Red: Files which are different by the given criteria (no copy direction).</para>
              </listitem>
              <listitem>
                <para>Black: Files which are identical (no copy direction).</para>
              </listitem>
            </itemizedlist>
            A double click on a file calls the &krusader;s <guilabel>Compare by content</guilabel> function.
            The Tasks (&lt;=&gt;) column defines the default copy direction, which can be modified by the user if needed.
            The results window supports dragging items to other windows ( drag [left], SHIFT+drag [right] )
            and copy left/right selected items to clipboard (<keycombo action="simul">&Ctrl;<keycap>c</keycap></keycombo>).
        </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><guilabel>File List</guilabel>: Tasks (&lt;=&gt;) column</term>
      <listitem>
        <para>This column displays the task that is planned for the
        Synchronizer, this task can be modified with the 
        <link linkend="synccomp_right-click">right click menu</link>.</para>
        <itemizedlist>
          <listitem>
            <para>
            <guibutton>-&gt;</guibutton>: Copy from the
            left side to the right side. For directories: 
            <command>mkdir</command> in the right side.</para>
          </listitem>
          <listitem>
            <para>
            <guibutton>=</guibutton>: The files are the same, do not
            do anything.</para>
          </listitem>
          <listitem>
            <para>
            <guibutton>!=</guibutton>: The file is excluded, or the
            Synchronizer does not know what to do.</para>
          </listitem>
          <listitem>
            <para>
            <guibutton>&lt;-</guibutton>: copy from the
            right side to the left side. For directories: 
            <command>mkdir</command> in the left side</para>
          </listitem>
          <listitem>
            <para>
            <guibutton>DEL</guibutton>: delete files from the right
            side.</para>
          </listitem>
        </itemizedlist>
      </listitem>
    </varlistentry>
    <varlistentry id="synccomp_show_options">
      <term>Show options</term>
      <listitem>
        <para>Here you can include/exclude particular file types.
        Those files, that are not in the list, will be untouched at
        synchronization.</para>
        <itemizedlist>
          <listitem>
            <para>
            <guibutton>-&gt;</guibutton>: Enable/Disable
            the copy task from left to right.</para>
          </listitem>
          <listitem>
            <para>
            <guibutton>=</guibutton>: Enable/Disable listing the
            equal files.</para>
          </listitem>
          <listitem>
            <para>
            <guibutton>!=</guibutton>: Enable/Disable listing the
            excluded / "don't know what to do" files.</para>
          </listitem>
          <listitem>
            <para>
            <guibutton>&lt;-</guibutton>: Enable/Disable
            the copy task from right to left.</para>
          </listitem>
          <listitem>
            <para>
            <guibutton>Trash</guibutton>: Enable/Disable the file
            deleting from the left side task.</para>
          </listitem>
          <listitem>
            <para>
            <guibutton>Duplicates</guibutton>: Enable/Disable those
            files that exist on both sides.</para>
          </listitem>
          <listitem>
            <para>
            <guibutton>Singles</guibutton>: Enable/Disable those
            files that exist only on one side.</para>
          </listitem>
        </itemizedlist>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>Action buttons</term>
      <listitem>
        <itemizedlist>
          <listitem>
            <para>
            <guibutton>Compare</guibutton>: Compares the
            directories, the results are displayed on the 
            <guilabel>File List</guilabel>.</para>
          </listitem>
          <listitem>
            <para>
            <guibutton>Stop</guibutton>: Stops comparing.</para>
          </listitem>
          <listitem>
            <para>
            <guibutton>Synchronize</guibutton>: Shows the
            synchronize dialog.</para>
          </listitem>
          <listitem>
            <para>
            <guibutton>Close</guibutton>: Closes the Synchronizer
            window.</para>
          </listitem>
        </itemizedlist>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>The Status line may contain</term>
      <listitem>
        <itemizedlist>
          <listitem>
            <para>The number of scanned directories while
            comparing.</para>
          </listitem>
          <listitem>
            <para>The filename when comparing by content (for big
            files).</para>
          </listitem>
          <listitem>
            <para>The number of files on the list.</para>
          </listitem>
        </itemizedlist>
      </listitem>
    </varlistentry>
    <varlistentry id="synccomp_right-click">
      <term>Right click menu on the 
      <guilabel>File List</guilabel></term>
      <listitem>
        <para>The right click menu is split up in three
        sections:</para>
        <para>1. change the 
        <guilabel>Task</guilabel> operations determined by the
        Comparator. Select one or multiple files. The change will
        be applied on the selection and not only on the right
        clicked item. If the selected item is a directory, the
        change will be applied on its files/subdirectories as
        well.</para>
        <itemizedlist>
          <listitem>
            <para>
            <guibutton>Synchronize Directories</guibutton>: Starts
            synchronization.</para>
          </listitem>
          <listitem>
            <para>
            <guibutton>Exclude</guibutton>: Excludes a file/dir
            from synchronization ( task change to != ).</para>
          </listitem>
          <listitem>
            <para>
            <guibutton>Restore original operation</guibutton>: Task
            change to the original result of comparison.</para>
          </listitem>
          <listitem>
            <para>
            <guibutton>Reverse direction</guibutton>: Task change (
            -&gt; to &lt;-, and
            &lt;- to -&gt; ).</para>
          </listitem>
          <listitem>
            <para>
            <guibutton>Copy from right to left</guibutton>: Task
            change to &lt;-.</para>
          </listitem>
          <listitem>
            <para>
            <guibutton>Copy from left to right</guibutton>: Task
            change to -&gt;.</para>
          </listitem>
          <listitem>
            <para>
            <guibutton>Delete ( left single )</guibutton>: Task
            change to DEL.</para>
          </listitem>
        </itemizedlist>
        <para>2. change the selections</para>
        <itemizedlist>
          <listitem>
            <para>
            <guibutton>Select items</guibutton>: Opens a dialog
            which allows you to select items. This is the 
            <guimenuitem>Select Group</guimenuitem> dialog from the
            &editmenu-lnk;.</para>
          </listitem>
          <listitem>
            <para>
            <guibutton>Unselect items</guibutton>: Opens a dialog
            which allows you to deselect items. This is the 
            <guimenuitem>Unselect Group</guimenuitem> dialog from
            the &editmenu-lnk;.</para>
          </listitem>
          <listitem>
            <para>
            <guibutton>Invert selection</guibutton>: Invert the
            selection status of all items.</para>
          </listitem>
        </itemizedlist>
        <para>3. others (note that the following operations work on the
        right-clicked file and not on the selection).</para>
        <itemizedlist>
          <listitem>
            <para>
            <guibutton>View left file</guibutton>: Starts viewer on
            the left file.</para>
          </listitem>
          <listitem>
            <para>
            <guibutton>View right file</guibutton>: Starts viewer
            on the right file.</para>
          </listitem>
          <listitem>
            <para>
            <guibutton>Compare Files</guibutton>: Starts the diff
            utility (&eg; &kompare;) on the
            files.</para>
          </listitem>
        </itemizedlist>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>Other buttons</term>
      <listitem>
        <itemizedlist>
          <listitem>
            <para>
            <guibutton>Profiles</guibutton>: If you have to
            synchronize the same directories often, you can save the
            settings &eg; include files, exclude files,
            ... Press the 
            <guibutton>Profile</guibutton> button, and you will be
            able to add / load / save / remove synchronizer
            profiles.</para>
          </listitem>
          <listitem>
            <para>
            <guibutton>Swap sides</guibutton>: Swaps the 
            <guilabel>File List</guilabel>.</para>
          </listitem>
        </itemizedlist>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>Synchronize with &kget;</term>
      <listitem>
        <para>If you want to synchronize a local directory with an
        unstable ftp server, &kget; is a much better
        solution than simple file copying. After comparing you may
        right click on the result list and select 
        <guimenuitem>Synchronize with kget</guimenuitem> to execute
        the synchronization, after that the listed files will be
        downloaded with kget instead of krusader. Of course 
        <application>kget</application> needs to be installed on
        your computer; otherwise, it will not be available.</para>
      </listitem>
    </varlistentry>
  </variablelist>
 
</sect2>  
<sect2 id="synchronizer_sychronisation">
  <title>Sychronisation</title>  

  <para>After pressing the 
  <guibutton>Synchronize</guibutton> button the synchronization
  dialog appears.</para>
  <variablelist>
    <varlistentry>
      <term>Check boxes</term>
      <listitem>
        <para>Here you confirm the copy and delete operations of
        the Synchronizer</para>
        <itemizedlist>
          <listitem>
            <para>
            <guilabel>Right to left</guilabel>: copy X1 files ( Y1
            bytes ) enable / disable the copy from right to
            left.</para>
          </listitem>
          <listitem>
            <para>
            <guilabel>Left to right</guilabel>: copy X2 files ( Y2
            bytes ) enable / disable the copy from left to
            right.</para>
          </listitem>
          <listitem>
            <para>
            <guilabel>Left</guilabel>: delete X3 files ( Y3 bytes )
            enable / disable the left side deleting.</para>
          </listitem>
          <listitem>
            <para>
            <guilabel>Confirm overwrites</guilabel>: By switching
            this option on, Krusader will show the 
            <guibutton>rename, skip, overwrite, skip all, overwrite
            all</guibutton> dialog box, before overwriting the
            file.</para>
          </listitem>
        </itemizedlist>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>Status labels</term>
      <listitem>
        <itemizedlist>
          <listitem>
            <para>
            <guilabel>Ready</guilabel>: A1/A2 files, B1/B2. This
            line is changed at synchronizing, showing that
            synchronizer finished with A1 files from A2 ( B1 bytes
            from B2 ).</para>
          </listitem>
          <listitem>
            <para>
            <guilabel>Progress bar</guilabel>: Shows the progress
            on the synchronization (based on bytes).</para>
          </listitem>
        </itemizedlist>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>Action buttons</term>
      <listitem>
        <itemizedlist>
          <listitem>
            <para>
            <guibutton>Start</guibutton>: Starts
            synchronization.</para>
          </listitem>
          <listitem>
            <para>
            <guibutton>Pause / Resume</guibutton>: Pauses/resumes
            the synchronization process.</para>
          </listitem>
          <listitem>
            <para>
            <guibutton>Close</guibutton>: Closes the
            synchronization dialog (and stops
            synchronization).</para>
          </listitem>
        </itemizedlist>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>Parallel synchronization</term>
      <listitem>
        <itemizedlist>
          <listitem>
            <para>One can give the number of the 'quasy'
            threads.</para>
          </listitem>
          <listitem>
            <para>Can drastically increase the speed when
            synchronized with slow FTP servers.</para>
          </listitem>
          <listitem>
            <para>Does not affect the speed of local
            synchronization.</para>
          </listitem>
          <listitem>
            <para>Remote "compare by content" and "directory
            compare" is done in parallel.</para>
          </listitem>
          <listitem>
            <para>Remote synchronization is also done in parallel,
            except the mkdir tasks (mkdir must be before
            copy).</para>
          </listitem>
        </itemizedlist>
      </listitem>
    </varlistentry>
  </variablelist>

</sect2>
</sect1>