<?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 Git
			documentation, which describes Git in terms of the
			Command Line Interface (CLI). To help you understand what
			TortoiseGit is doing behind the scenes, we have compiled
			a list showing the equivalent CLI commands for each of
			TortoiseGit's GUI operations.
		</para>
		<note>
			<para>
			Even though there are CLI equivalents to what TortoiseGit
			does, remember that TortoiseGit does <emphasis>not</emphasis>
			call the CLI but uses the Git library directly.
			</para>
		</note>
		<para>
			If you think you have found a bug in TortoiseGit, we
			may ask you to try to reproduce it using the CLI, so
			that we can distinguish TortoiseGit issues from Git
			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">http://TortoiseGit.tigris.org/svn/TortoiseGit/trunk</systemitem>.
			The working copy path is shown simply as
			<literal>PATH</literal>, and an example might be
			<filename>C:\TortoiseGit\trunk</filename>.
		</para>
		<important>
			<para>
			Because TortoiseGit 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 TortoiseGit. These options are
			shown in [square brackets] in the command line definitions.
		</para>
	</sect1>
	<sect1 id="tsvn-cli-main">
		<title>TortoiseGit Commands</title>
		<sect2 id="tsvn-cli-checkout">
			<title>Checkout</title>
<screen>
svn checkout [-N] [--ignore-externals] [-r rev] URL PATH
</screen>
			<para>
				If <guilabel>Only checkout the top folder</guilabel> is checked,
				use the <literal>-N</literal> switch.
			</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 Git. So
				TortoiseGit 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, TortoiseGit 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] [-N] [--ignore-externals] PATH
</screen>
			<para>
				If <guilabel>Only update the top folder</guilabel> is checked,
				use the <literal>-N</literal> switch.
			</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 TortoiseGit, the commit dialog uses several Git 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,
				TortoiseGit 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 Git,
				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 Git commit takes place. If you have
				left all the file selection checkboxes in their default state,
				TortoiseGit 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" [-N] [--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 TortoiseGit
				is using. TortoiseGit 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 TortoiseGit, whether or
				not they are version controlled. TortoiseGit 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, TortoiseGit 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,
				TortoiseGit 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 Git,
				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 TortoiseGit only. There's no
				equivalent in the command line client.
			</para>
			<para>
				What TortoiseGit 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 Git revert takes place. If you have
				left all the file selection checkboxes in their default state,
				TortoiseGit 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 Git library, so there's no matching command
				line equivalent.
			</para>
			<para>
				What TortoiseGit 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, TortoiseGit 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>
				TortoiseGit 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 Git.
			</para>
		</sect2>
	</sect1>
</appendix>
<!--
local variables: 
sgml-parent-document: ("book.xml" "appendix")
end:
-->
