<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE appendix SYSTEM "../../dtd/dblite.dtd">
<appendix id="tsvn-cli" xmlns:xi="http://www.w3.org/2001/XInclude">
  <title>Command Line Interface Cross Reference</title>
  <simplesect>
    <indexterm>
      <primary>command line client</primary>
    </indexterm>
    <indexterm>
      <primary>CLI</primary>
    </indexterm>
    <para>
      Sometimes this manual refers you to the main Subversion
      documentation, which describes Subversion in terms of the
      Command Line Interface (CLI). To help you understand what
      TortoiseSVN is doing behind the scenes, we have compiled
      a list showing the equivalent CLI commands for each of
      TortoiseSVN's GUI operations.
    </para>
    <note>
      <para>
        Even though there are CLI equivalents to what TortoiseSVN
        does, remember that TortoiseSVN does <emphasis>not</emphasis>
        call the CLI but uses the Subversion library directly.
      </para>
    </note>
    <para>
      If you think you have found a bug in TortoiseSVN, we
      may ask you to try to reproduce it using the CLI, so
      that we can distinguish TortoiseSVN issues from Subversion
      issues. This reference tells you which command to try.
    </para>
  </simplesect>
  <sect1 id="tsvn-cli-basics">
    <title>Conventions and Basic Rules</title>
    <para>
      In the descriptions which follow, the URL for a repository
      location is shown simply as
      <literal>URL</literal>, and an example might be
      <systemitem class="url">https://svn.code.sf.net/p/tortoisesvn/code/trunk/</systemitem>.
      The working copy path is shown simply as
      <literal>PATH</literal>, and an example might be
      <filename>C:\TortoiseSVN\trunk</filename>.
    </para>
    <important>
      <para>
        Because TortoiseSVN is a Windows Shell Extension, it is not able
        to use the notion of a current working directory. All working
        copy paths must be given using the absolute path, not a relative
        path.
      </para>
    </important>
    <para>
      Certain items are optional, and these are often controlled by
      checkboxes or radio buttons in TortoiseSVN. These options are
      shown in [square brackets] in the command line definitions.
    </para>
  </sect1>
  <sect1 id="tsvn-cli-main">
    <title>TortoiseSVN Commands</title>
    <sect2 id="tsvn-cli-checkout">
      <title>Checkout</title>
      <screen>
svn checkout [-depth ARG] [--ignore-externals] [-r rev] URL PATH
      </screen>
      <para>
        The depth combo box items relate to the <literal>-depth</literal>
        argument.
      </para>
      <para>
        If <guilabel>Omit externals</guilabel> is checked,
        use the <literal>--ignore-externals</literal> switch.
      </para>
      <para>
        If you are checking out a specific revision, specify that
        after the URL using <literal>-r</literal> switch.
      </para>
    </sect2>
    <sect2 id="tsvn-cli-update">
      <title>Update</title>
      <screen>
svn info URL_of_WC
svn update [-r rev] PATH
      </screen>
      <para>
        Updating multiple items is currently not an atomic operation
        in Subversion. So
        TortoiseSVN first finds the HEAD revision of the repository,
        and then updates all items to that particular revision number to
        avoid creating a mixed revision working copy.
      </para>
      <para>
        If only one item is selected for updating or the selected items are
        not all from the same repository, TortoiseSVN just updates
        to HEAD.
      </para>
      <para>
        No command line options are used here.
        <guilabel>Update to revision</guilabel> also implements
        the update command, but offers more options.
      </para>
    </sect2>
    <sect2 id="tsvn-cli-updaterev">
      <title>Update to Revision</title>
      <screen>
svn info URL_of_WC
svn update [-r rev] [-depth ARG] [--ignore-externals] PATH
      </screen>
      <para>
        The depth combo box items relate to the <literal>-depth</literal>
        argument.
      </para>
      <para>
        If <guilabel>Omit externals</guilabel> is checked,
        use the <literal>--ignore-externals</literal> switch.
      </para>
    </sect2>
    <sect2 id="tsvn-cli-commit">
      <title>Commit</title>
      <para>
        In TortoiseSVN, the commit dialog uses several Subversion commands.
        The first stage is a status check which determines the items
        in your working copy which can potentially be committed. You can
        review the list, diff files against BASE and select the items you
        want to be included in the commit.
      </para>
      <screen>
svn status -v PATH
      </screen>
      <para>
        If <guilabel>Show unversioned files</guilabel> is checked,
        TortoiseSVN will also show all unversioned files and folders in
        the working copy hierarchy, taking account of the ignore rules.
        This particular feature has no direct equivalent in Subversion,
        as the <literal>svn status</literal> command does not descend into
        unversioned folders.
      </para>
      <para>
        If you check any unversioned files and folders, those items will
        first be added to your working copy.
      </para>
      <screen>
svn add PATH...
      </screen>
      <para>
        When you click on OK, the Subversion commit takes place. If you have
        left all the file selection checkboxes in their default state,
        TortoiseSVN uses a single recursive commit of the working copy.
        If you deselect some files, then a non-recursive commit
        (<literal>-N</literal>) must be used, and every path must be
        specified individually on the commit command line.
      </para>
      <screen>
svn commit -m "LogMessage" [-depth ARG] [--no-unlock] PATH...
      </screen>
      <para>
        <literal>LogMessage</literal> here represents the contents of the
        log message edit box. This can be empty.
      </para>
      <para>
        If <guilabel>Keep locks</guilabel> is checked,
        use the <literal>--no-unlock</literal> switch.
      </para>
    </sect2>
    <sect2 id="tsvn-cli-diff">
      <title>Diff</title>
      <screen>
svn diff PATH
      </screen>
      <para>
        If you use Diff from the main context menu, you are diffing
        a modified file against its BASE revision. The output from
        the CLI command above also does this and produces output
        in unified-diff format. However, this is not what TortoiseSVN
        is using. TortoiseSVN uses TortoiseMerge (or a diff program of
        your choosing) to display differences visually between
        full-text files, so there is no direct CLI equivalent.
      </para>
      <para>
        You can also diff any 2 files using TortoiseSVN, whether or
        not they are version controlled. TortoiseSVN just feeds the
        two files into the chosen diff program and lets it work out
        where the differences lie.
      </para>
    </sect2>
    <sect2 id="tsvn-cli-showlog">
      <title>Show Log</title>
      <screen>
svn log -v -r 0:N --limit 100 [--stop-on-copy] PATH
or
svn log -v -r M:N [--stop-on-copy] PATH
      </screen>
      <para>
        By default, TortoiseSVN tries to fetch 100 log messages
        using the --limit method. If the settings instruct it to
        use old APIs, then the second form is used to fetch the
        log messages for 100 repository revisions.
      </para>
      <para>
        If <guilabel>Stop on copy/rename</guilabel> is checked,
        use the <literal>--stop-on-copy</literal> switch.
      </para>
    </sect2>
    <sect2 id="tsvn-cli-checkmods">
      <title>Check for Modifications</title>
      <screen>
svn status -v PATH
or
svn status -u -v PATH
      </screen>
      <para>
        The initial status check looks only at your working copy.
        If you click on <guibutton>Check repository</guibutton>
        then the repository is also checked to see which files
        would be changed by an update, which requires the
        <literal>-u</literal> switch.
      </para>
      <para>
        If <guilabel>Show unversioned files</guilabel> is checked,
        TortoiseSVN will also show all unversioned files and folders in
        the working copy hierarchy, taking account of the ignore rules.
        This particular feature has no direct equivalent in Subversion,
        as the <literal>svn status</literal> command does not descend into
        unversioned folders.
      </para>
    </sect2>
    <sect2 id="tsvn-cli-revgraph">
      <title>Revision Graph</title>
      <para>
        The revision graph is a feature of TortoiseSVN only. There's no
        equivalent in the command line client.
      </para>
      <para>
        What TortoiseSVN does is an
        <screen>
svn info URL_of_WC
svn log -v URL
        </screen>
        where URL is the repository <emphasis>root</emphasis> and then
        analyzes the data returned.
      </para>
    </sect2>
    <sect2 id="tsvn-cli-repobrowser">
      <title>Repo Browser</title>
      <screen>
svn info URL_of_WC
svn list [-r rev] -v URL
      </screen>
      <para>
        You can use <literal>svn info</literal> to determine the repository
        root, which is the top level shown in the repository browser. You
        cannot navigate <literal>Up</literal> above this level.
        Also, this command returns all the locking information shown in
        the repository browser.
      </para>
      <para>
        The <literal>svn list</literal> call will list the contents of a
        directory, given a URL and revision.
      </para>
    </sect2>
    <sect2 id="tsvn-cli-editconflicts">
      <title>Edit Conflicts</title>
      <para>
        This command has no CLI equivalent. It invokes TortoiseMerge or
        an external 3-way diff/merge tool to look at the files involved
        in the conflict and sort out which lines to use.
      </para>
    </sect2>
    <sect2 id="tsvn-cli-resolved">
      <title>Resolved</title>
      <screen>
svn resolved PATH
      </screen>
    </sect2>
    <sect2 id="tsvn-cli-rename">
      <title>Rename</title>
      <screen>
svn rename CURR_PATH NEW_PATH
      </screen>
    </sect2>
    <sect2 id="tsvn-cli-delete">
      <title>Delete</title>
      <screen>
svn delete PATH
      </screen>
    </sect2>
    <sect2 id="tsvn-cli-revert">
      <title>Revert</title>
      <screen>
svn status -v PATH
      </screen>
      <para>
        The first stage is a status check which determines the items
        in your working copy which can potentially be reverted. You can
        review the list, diff files against BASE and select the items you
        want to be included in the revert.
      </para>
      <para>
        When you click on OK, the Subversion revert takes place. If you have
        left all the file selection checkboxes in their default state,
        TortoiseSVN uses a single recursive (<literal>-R</literal>)
        revert of the working copy. If you deselect some files, then
        every path must be specified individually on the revert command line.
      </para>
      <screen>
svn revert [-R] PATH...
      </screen>
    </sect2>
    <sect2 id="tsvn-cli-cleanup">
      <title>Cleanup</title>
      <screen>
svn cleanup PATH
      </screen>
    </sect2>
    <sect2 id="tsvn-cli-getlock">
      <title>Get Lock</title>
      <screen>
svn status -v PATH
      </screen>
      <para>
        The first stage is a status check which determines the files
        in your working copy which can potentially be locked. You can
        select the items you want to be locked.
      </para>
      <screen>
svn lock -m "LockMessage" [--force] PATH...
      </screen>
      <para>
        <literal>LockMessage</literal> here represents the contents of the
        lock message edit box. This can be empty.
      </para>
      <para>
        If <guilabel>Steal the locks</guilabel> is checked,
        use the <literal>--force</literal> switch.
      </para>
    </sect2>
    <sect2 id="tsvn-cli-release">
      <title>Release Lock</title>
      <screen>
svn unlock PATH
      </screen>
    </sect2>
    <sect2 id="tsvn-cli-branchtag">
      <title>Branch/Tag</title>
      <screen>
svn copy -m "LogMessage" URL URL
or
svn copy -m "LogMessage" URL@rev URL@rev
or
svn copy -m "LogMessage" PATH URL
      </screen>
      <para>
        The Branch/Tag dialog performs a copy to the repository.
        There are 3 radio button options:
        <itemizedlist>
          <listitem>HEAD revision in the repository</listitem>
          <listitem>Specific revision in repository</listitem>
          <listitem>Working copy</listitem>
        </itemizedlist>
        which correspond to the 3 command line variants above.
      </para>
      <para>
        <literal>LogMessage</literal> here represents the contents of the
        log message edit box. This can be empty.
      </para>
    </sect2>
    <sect2 id="tsvn-cli-switch">
      <title>Switch</title>
      <screen>
svn info URL_of_WC
svn switch [-r rev] URL PATH
      </screen>
    </sect2>
    <sect2 id="tsvn-cli-merge">
      <title>Merge</title>
      <screen>
svn merge [--dry-run] --force From_URL@revN To_URL@revM PATH
      </screen>
      <para>
        The <guibutton>Test Merge</guibutton> performs the same merge
        with the <literal>--dry-run</literal> switch.
      </para>
      <screen>
svn diff From_URL@revN To_URL@revM
      </screen>
      <para>
        The <guibutton>Unified diff</guibutton> shows the diff
        operation which will be used to do the merge.
      </para>
    </sect2>
    <sect2 id="tsvn-cli-export">
      <title>Export</title>
      <screen>
svn export [-r rev] [--ignore-externals] URL Export_PATH
      </screen>
      <para>
        This form is used when accessed from an unversioned folder,
        and the folder is used as the destination.
      </para>
      <para>
        Exporting a working copy to a different location is done without
        using the Subversion library, so there's no matching command
        line equivalent.
      </para>
      <para>
        What TortoiseSVN does is to copy all files to the new location
        while showing you the progress of the operation. Unversioned
        files/folders can optionally be exported too.
      </para>
      <para>
        In both cases,
        if <guilabel>Omit externals</guilabel> is checked,
        use the <literal>--ignore-externals</literal> switch.
      </para>
    </sect2>
    <sect2 id="tsvn-cli-relocate">
      <title>Relocate</title>
      <screen>
svn switch --relocate From_URL To_URL
      </screen>
    </sect2>
    <sect2 id="tsvn-cli-createrepos">
      <title>Create Repository Here</title>
      <screen>
svnadmin create --fs-type fsfs PATH
      </screen>
    </sect2>
    <sect2 id="tsvn-cli-add">
      <title>Add</title>
      <screen>
svn add PATH...
      </screen>
      <para>
        If you selected a folder, TortoiseSVN first scans it
        recursively for items which can be added.
      </para>
    </sect2>
    <sect2 id="tsvn-cli-import">
      <title>Import</title>
      <screen>
svn import -m LogMessage PATH URL
      </screen>
      <para>
        <literal>LogMessage</literal> here represents the contents of the
        log message edit box. This can be empty.
      </para>
    </sect2>
    <sect2 id="tsvn-cli-blame">
      <title>Blame</title>
      <screen>
svn blame -r N:M -v PATH
svn log -r N:M PATH
      </screen>
      <para>
        If you use TortoiseBlame to view the blame info, the file
        log is also required to show log messages in a tooltip.
        If you view blame as a text file, this information is not
        required.
      </para>
    </sect2>
    <sect2 id="tsvn-cli-addignore">
      <title>Add to Ignore List</title>
      <screen>
svn propget svn:ignore PATH > tempfile
{edit new ignore item into tempfile}
svn propset svn:ignore -F tempfile PATH
      </screen>
      <para>
        Because the <literal>svn:ignore</literal> property is often
        a multi-line value, it is shown here as being changed via
        a text file rather than directly on the command line.
      </para>
    </sect2>
    <sect2 id="tsvn-cli-createpatch">
      <title>Create Patch</title>
      <screen>
svn diff PATH > patch-file
      </screen>
      <para>
        TortoiseSVN creates a patch file in unified diff format
        by comparing the working copy with its BASE version.
      </para>
    </sect2>
    <sect2 id="tsvn-cli-applypatch">
      <title>Apply Patch</title>
      <para>
        Applying patches is a tricky business unless the patch
        and working copy are at the same revision. Luckily for
        you, you can use TortoiseMerge, which has no direct
        equivalent in Subversion.
      </para>
    </sect2>
  </sect1>
</appendix>
<!--
local variables:
sgml-parent-document: ("book.xml" "appendix")
end:
-->
