<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">
<sect1 id="tgit-dug-general">
	<title>Getting Started</title>
	<sect2 id="tgit-dug-general-icons">
		<title>Icon Overlays</title>
		<para>
			<figure id="tgit-dug-general-dia-icons">
				<title>Explorer showing icon overlays</title>
				<graphic fileref="../images/Overlays.png"/>
			</figure>
			One of the most visible features of TortoiseGit is the icon
			overlays which appear on files in your working tree. These
			show you at a glance which of your files have been modified.
			Refer to <xref linkend="tgit-dug-wcstatus-1"/> to find out
			what the different overlays represent.
		</para>
	</sect2>
	<sect2 id="tgit-dug-general-menu">
		<title>Context Menus</title>
		<indexterm>
			<primary>context menu</primary>
		</indexterm>
		<indexterm>
			<primary>right-click</primary>
		</indexterm>
		<para>
			<figure id="tgit-dug-context-dir-control">
				<title>Context menu for a directory under version control</title>
				<graphic fileref="../images/ContextMenuDirControl.png"/>
			</figure>
			All TortoiseGit commands are invoked from the context menu of the windows
			explorer. Most are directly visible, when you <action>right click</action>
			on a file or folder. The commands that are available depend on whether the
			file or folder or its parent folder is under version control or not.
			You can also see the TortoiseGit menu as part of the Explorer file menu.
		</para>
		<tip>
			<para>
				Some commands which are very rarely used are only available in the
				extended context menu. To bring up the extended context menu, hold
				down the <keycap>Shift</keycap> key when you <action>right-click</action>.
			</para>
		</tip>
		<para>
			In some cases you may see several TortoiseGit entries. This is not a bug!
			<figure id="tgit-dug-explorer-file-menu">
				<title>Explorer file menu for a shortcut in a versioned folder</title>
				<graphic fileref="../images/ExplorerFileMenuFileShortcut.png"/>
			</figure>
			This example is for an unversioned shortcut within a versioned folder, and
			in the Explorer file menu there are <emphasis>two</emphasis> entries
			for TortoiseGit. One for the shortcut itself
			and the second for the object the shortcut is pointing to.
			To help you distinguish between them, the icons have an indicator in the
			lower right corner to show whether the menu entry is for a file,
			a folder, a shortcut or for multiple selected items.
		</para>
	</sect2>
	<sect2 id="tgit-dug-general-drag">
		<title>Drag and Drop</title>
		<indexterm>
			<primary>drag handler</primary>
		</indexterm>
		<indexterm>
			<primary>drag-n-drop</primary>
		</indexterm>
		<indexterm>
			<primary>right drag</primary>
		</indexterm>
		<para>
			<figure id="tgit-dug-right-drag">
				<title>Right drag menu for a directory under version control</title>
				<graphic fileref="../images/RightDragMenu.png"/>
			</figure>
			Other commands are available as drag handlers, when you <action>right drag</action>
			files or folders to a new location inside working trees or when you
			<action>right drag</action> a non-versioned file or folder into a directory
			which is under version control.
		</para>
	</sect2>
	<sect2 id="tgit-dug-general-shortcuts">
		<title>Common Shortcuts</title>
		<para>
			Some common operations have well-known Windows shortcuts, but do
			not appear on buttons or in menus. If you can't work out how
			to do something obvious, like refreshing a view, check here.
			<variablelist>
				<varlistentry>
					<term>F1</term>
					<listitem>
						<para>
							Help, of course.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>F5</term>
					<listitem>
						<para>
							Refresh the current view. This is perhaps the single
							most useful one-key command. For example ...
							In Explorer this will refresh the icon overlays on your working tree.
							In the commit dialog it will re-scan the working tree
							to see what may need to be committed.
							In the Revision Log dialog it will contact the repository
							again to check for more recent changes.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Ctrl-A</term>
					<listitem>
						<para>
							Select all. This can be used if you get an error message
							and want to copy and paste into an email. Use Ctrl-A
							to select the error message and then ...
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Ctrl-C</term>
					<listitem>
						<para>
							... Copy the selected text.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Ctrl-F</term>
					<listitem>
						<para>
							Search
						</para>
					</listitem>
				</varlistentry>
			</variablelist>
		</para>
	</sect2>
	<sect2 id="tgit-dug-general-auth">
		<title>Authentication</title>
		<?dbhh topicname="HIDD_FIRSTSTARTWIZARD_AUTHENTICATION"?>
		<indexterm>
			<primary>authentication</primary>
		</indexterm>
		<sect3 id="tgit-dug-general-auth-ssh">
			<title>SSH (URLs look like git@example.com)</title>
			<para>
				TortoiseGitPlink is recommended as SSH client because it better integrates with Windows.
				By default TortoiseGitPlink does not store passwords, you can use the PuTTY authentication agent
				for caching the password (done automatically if a PuTTY key is configured for a remote).
				For advanced tips &amp; tricks see <xref linkend="tgit-ssh-howto"/>. Note, however, that TortoiseGitPlink
				does not respect <filename>~/.ssh/config</filename> which is OpenSSH specific (see PuTTY tips &amp; tricks
				or configure OpenSSH as SSH client, see next paragraph). If you also want to use
				TortoiseGitPlink on Git Bash, create an environment variable called <literal>GIT_SSH</literal>
				with the path to the PuTTY plink.exe or preferably to TortoiseGitPlink.exe. This can be done by
				re-executing the Git for Windows installer (there you can choose which SSH client to use), on the
				command line by executing <literal>set GIT_SSH=PATH_TO_PLINK.EXE"</literal>
				(<filename>C:\Program Files\TortoiseGit\bin\TortoiseGitPlink.exe</filename> on default installations)
				or configure the environment variables
				<ulink url="https://www.computerhope.com/issues/ch000549.htm">
					<citetitle>permanently</citetitle>
				</ulink>.
			</para>
			<para>
				It is also possible to use OpenSSH (shipped with Git for Windows, Cygwin, and MSYS2). Just open TortoiseGit
				settings and open the <guilabel>Network</guilabel> page and enter <filename>ssh.exe</filename> as SSH client,
				see <xref linkend="tgit-dug-settings-network"/> and
				<ulink url="https://stackoverflow.com/a/32115724/3906760">
					<citetitle>this answer on StackOverflow</citetitle>
				</ulink>. When OpenSSH is used, you can also make use of <filename>~/.ssh/config</filename> (cf.
				<ulink url="https://stackoverflow.com/q/30320458/3906760">
					<citetitle>this answer on StackOverflow</citetitle>
				</ulink>).
			</para>
		</sect3>
		<sect3 id="tgit-dug-general-auth-https">
			<title>HTTP/HTTPS (URLs start with https:// or http://)</title>
			<para>
				By default Git does not save/cache credentials. However, you can configure a
				<ulink url="https://stackoverflow.com/q/14000173/3906760">
					<citetitle>credential helper</citetitle>
				</ulink>
				(recommended, also see <gitdoclink cmd="gitcredentials" section="7"/>) or manually use
				<ulink url="https://stackoverflow.com/revisions/6031266/6">
					<citetitle><filename>%HOME%/_netrc</filename></citetitle>
				</ulink>.
			</para>
			<para>
				If you have set up a credential store and you want to clear some stored credentials see
				<ulink url="https://stackoverflow.com/a/31782500/3906760">
					<citetitle>this answer on StackOverflow</citetitle>
				</ulink>.
			</para>
		</sect3>
	</sect2>
	<sect2 id="tgit-dug-general-window-max">
		<title>Maximizing Windows</title>
		<indexterm>
			<primary>maximize</primary>
		</indexterm>
		<para>
			Many of TortoiseGit's dialogs have a lot of information to display,
			but it is often useful to maximize only the height, or only the width,
			rather than maximizing to fill the screen. As a convenience, there are
			shortcuts for this on the <guilabel>Maximize</guilabel> button.
			Use the <action>middle mouse</action> button to maximize vertically,
			and <action>right mouse</action> to maximize horizontally.
		</para>
	</sect2>
</sect1>
