<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE appendix SYSTEM "../../dtd/dblite.dtd">
<appendix id="tgit-admins" xmlns:xi="http://www.w3.org/2001/XInclude">
	<title>Useful Tips For Administrators</title>
	<simplesect>
		<para>
			This appendix contains solutions to problems/questions you might
			have when you are responsible for deploying TortoiseGit to multiple
			client computers.
		</para>
	</simplesect>
	<sect1 id="tgit-admins-grouppolicies">
		<title>Deploy TortoiseGit via group policies</title>
		<indexterm>
			<primary>group policies</primary>
		</indexterm>
		<indexterm>
			<primary>GPO</primary>
		</indexterm>
		<indexterm>
			<primary>msi</primary>
		</indexterm>
		<indexterm>
			<primary>domain controller</primary>
		</indexterm>
		<indexterm>
			<primary>deploy</primary>
		</indexterm>
		<para>
			The TortoiseGit installer comes as an MSI file, which means you
			should have no problems adding that MSI file to the group policies
			of your domain controller.
		</para>
		<para>
			A good walk-through on how to do that can be found from Microsoft:
			<ulink url="https://learn.microsoft.com/en-us/troubleshoot/windows-server/group-policy/use-group-policy-to-install-software">
				<citetitle>https://learn.microsoft.com/en-us/troubleshoot/windows-server/group-policy/use-group-policy-to-install-software</citetitle>
			</ulink>.
		</para>
		<para>
			Versions 0.3.0 and later of TortoiseGit must be installed under
			<emphasis>Computer Configuration</emphasis> and not under
			<emphasis>User Configuration</emphasis>. This is because those versions
			need the new CRT and MFC DLLs, which can only be deployed <emphasis>per
			computer</emphasis> and not <emphasis>per user</emphasis>.
			If you really must install TortoiseGit on a per user basis, then you must
			first install the MFC and CRT package version 11 from Microsoft on each
			computer you want to install TortoiseGit as per user.
		</para>
		<para>
			You can provide a default setting for the SSH client in
			<filename>HKLM\TortoiseGit\SSH</filename>.
		</para>
		<para>
			TortoiseGit automatically finds <filename>git.exe</filename> if a normal msysGit/Git for Windows installation is on the computer
			or <filename>git.exe</filename> is on the <literal>PATH</literal> (and is runnable in a normal <filename>cmd.exe</filename> session - you might need to also put the <filename>[MSYSGIT INSTALLDIR]\mingw\bin</filename> on the <literal>PATH</literal> if you use the msysGit development package).
		</para>
		<para>
			For completely disabling automatic update checking see <literal>VersionCheck</literal> in <xref linkend="tgit-dug-settings-registry"/>.
		</para>
	</sect1>
	<sect1 id="tgit-admins-upgradecheck">
		<title>Redirect the upgrade check</title>
		<?dbhh topicname="HIDD_CHECKFORUPDATES"?>
		<indexterm>
			<primary>upgrade check</primary>
		</indexterm>
		<indexterm>
			<primary>check new version</primary>
		</indexterm>
		<indexterm>
			<primary>version</primary>
		</indexterm>
		<para>
			TortoiseGit checks if there's a new version available every week (or daily in a preview release).
			If there is a newer version available, a dialog shows up informing
			the user about that and allows to download/install a new version.
		</para>
		<figure id="tgit-admins-dia1">
			<title>The upgrade dialog</title>
			<graphic fileref="images/upgradecheck.png"/>
		</figure>
		<para>
			If you're responsible for a lot of users in your domain, you might want
			your users to use only versions you have approved and not have them install
			always the latest version (or to save bandwidth or want to add some further notes for installation). You probably don't want that upgrade dialog
			to show up so your users don't go and upgrade immediately (to disable update checking at all (e.g. because you use group policies to deploy TortoiseGit, see <xref linkend="tgit-admins-grouppolicies"/> and/or <literal>VersionCheck</literal> in <xref linkend="tgit-dug-settings-registry"/>).
		</para>
		<para>
			TortoiseGit allow you to redirect that upgrade
			check to your intranet server. You can set the registry key
			<filename>HKCU\Software\TortoiseGit\UpdateCheckURL</filename> OR <filename>HKLM\Software\TortoiseGit\UpdateCheckURL</filename> (string value, <filename>HKCU</filename> overrides <filename>HKLM</filename>)
			to an URL pointing to a text file in your intranet (default is <ulink url="https://versioncheck.tortoisegit.org/version.txt" condition="pot">https://versioncheck.tortoisegit.org/version.txt</ulink>).
			When the default <filename>version.txt</filename> file is used, it is checked by verifying a digital signature (<ulink url="https://versioncheck.tortoisegit.org/version.txt.rsa.asc" condition="pot">https://versioncheck.tortoisegit.org/version.txt.rsa.asc</ulink>) that it has not been altered (since TortoiseGit 1.8.5).
			The check for the digital signature of the <filename>version.txt</filename> file is omitted if the location is overridden in registry.
			That text file must have the following format:
<screen>
[TortoiseGit]
version=X.X.X.X
infotext=A new version of TortoiseGit is available for you to download!
infotexturl=http://192.168.2.1/downloads/TortoiseGit/info.htm
changelogurl=http://192.168.2.1/downloads/TortoiseGit/TortoiseGit-1.4.1.6000-changelog.txt
baseurl=http://192.168.2.1/downloads/TortoiseGit/
langs="1029;cs"
langs="1031;de"
</screen>
			The <literal>version</literal> line in that file is the version string. You must make sure that
			it matches the exact version string of the TortoiseGit installation package.
			The <literal>infotext</literal> line is a custom text, shown in the upgrade dialog. You can write
			there whatever you want (can also be left empty). Just note that the space in the upgrade dialog is
			limited. Too long messages will get truncated!
			The <literal>infotexturl</literal> line is the URL which is opened when
			when the user clicks on the (custom) message label in the upgrade dialog.
			The URL is opened with the default web browser, so if you specify a web page,
			that page is opened and shown to the user.
			The <literal>changelogurl</literal> line contains the URL to the changelog or release notes which are displayed in the upgrade dialog (if empty it defaults to <ulink url="https://versioncheck.tortoisegit.org/changelog.txt" condition="pot">https://versioncheck.tortoisegit.org/changelog.txt</ulink>, you can use <literal>%1!u!</literal>, <literal>%2!u!</literal> and <literal>%3!u!</literal> for MAJOR, MINOR and MICRO version numbers of the running TortoiseGit version; <literal>%4!s!</literal> for Windows platform, <literal>%5!s!</literal> for Windows version, and <literal>%6!s!</literal> for service pack version),
			The <literal>baseurl</literal> line is used to override the base path to the installation packages (if empty it defaults to <literal>https://updater.download.tortoisegit.org/tgit/X.X.X.X/</literal>).
			The filenames are generated as follows: <literal>TortoiseGit-(version)-(32|64)bit.msi</literal> for the main installer (if not overridden by <literal>mainfilename=TortoiseGit-%1!s!-%2!s!bit.msi</literal>)
			and <literal>TortoiseGit-LanguagePack-(version)-(32|64)bit-(cs|de|...).msi</literal> for the language packs (if not overridden by <literal>languagepackfilename=TortoiseGit-LanguagePack-%1!s!-%2!s!bit-%3!s!.msi</literal>; <literal>%4!d!</literal> is the four digit country code).
			Using <literal>langs</literal> lines, one can advertise language packs (Syntax of one line: Four digit country code;ISO Country code).
			Using a <literal>issuesurl</literal> line, it is possible to control the URL to which the issues are linked to (default is <literal>https://tortoisegit.org/issue/%BUGID%</literal>; can also be empty to disable linking). There are also two boolean options <literal>directdownload</literal> and <literal>changelog</literal> to hide the change log and to disable direct downloads (both default to true).
		</para>
		<para>
			Clicking on <guibutton>Download</guibutton> downloads the selected files as well as their digital signature files (<filename>filename.asc</filename>) to <filename><ulink url="https://docs.microsoft.com/windows/win32/shell/knownfolderid">FOLDERID_Downloads</ulink></filename>.
			After downloading the digital signature is verified - the file is only kept if the file is digitally signed and could be verified correctly.
		</para>
		<para>
			If you want to distribute your own modified TortoiseGit packages in your network, you have to put your own GPG key into TortoiseGit and sign the <filename>.msi</filename>-files with this key or deactivate the signature verification completely.
		</para>
	</sect1>
	<sect1 id="tgit-admins-disablemenus">
		<title>Disable context menu entries</title>
		<indexterm>
			<primary>context menu entries</primary>
		</indexterm>
		<indexterm>
			<primary>disable functions</primary>
		</indexterm>
		<indexterm>
			<primary>group policies</primary>
		</indexterm>
		<para>
			TortoiseGit allows you to disable (actually, hide)
			context menu entries. Since this is a feature which should not be used lightly
			but only if there is a compelling reason, there is no GUI for this and it has
			to be done directly in the registry.
			This can be used to disable certain commands for users who should not use them.
			But please note that only the context menu entries in the <emphasis>explorer</emphasis>
			are hidden, and the commands are still available through other means, e.g. the
			command line or even other dialogs in TortoiseGit itself!
		</para>
		<para>
			The registry keys which hold the information on which context menus to show are
			<filename>HKEY_CURRENT_USER\Software\TortoiseGit\ContextMenuEntriesMaskLow</filename>
			and <filename>HKEY_CURRENT_USER\Software\TortoiseGit\ContextMenuEntriesMaskHigh</filename>.
		</para>
		<para>
			Each of these registry entries is a <literal>DWORD</literal> value, with each
			bit corresponding to a specific menu entry. A set bit means the corresponding
			menu entry is deactivated.
		</para>
		<para>
			<table id="tgit-admins-disablemenus-1-table">
				<title>Menu entries and their values</title>
				<tgroup cols="2">
					<colspec colnum="1" colwidth="2*"/>
					<colspec colnum="2" colwidth="6*"/>
					<thead>
						<row>
							<entry>Value</entry>
							<entry>Menu entry</entry>
						</row>
					</thead>
					<tbody>
						<row>
							<entry condition="pot">0x0000000000000002</entry>
							<entry>Sync</entry>
						</row>
						<row>
							<entry condition="pot">0x0000000000000004</entry>
							<entry>Commit</entry>
						</row>
						<row>
							<entry condition="pot">0x0000000000000008</entry>
							<entry>Add</entry>
						</row>
						<row>
							<entry condition="pot">0x0000000000000010</entry>
							<entry>Revert</entry>
						</row>
						<row>
							<entry condition="pot">0x0000000000000020</entry>
							<entry>Cleanup</entry>
						</row>
						<row>
							<entry condition="pot">0x0000000000000040</entry>
							<entry>Resolve</entry>
						</row>
						<row>
							<entry condition="pot">0x0000000000000080</entry>
							<entry>Switch/Checkout</entry>
						</row>
						<row>
							<entry condition="pot">0x0000000000000100</entry>
							<entry condition="pot">Sendmail</entry>
						</row>
						<row>
							<entry condition="pot">0x0000000000000200</entry>
							<entry>Export</entry>
						</row>
						<row>
							<entry condition="pot">0x0000000000000400</entry>
							<entry>Create Repository here</entry>
						</row>
						<row>
							<entry condition="pot">0x0000000000000800</entry>
							<entry>Branch/Tag</entry>
						</row>
						<row>
							<entry condition="pot">0x0000000000001000</entry>
							<entry>Merge</entry>
						</row>
						<row>
							<entry condition="pot">0x0000000000002000</entry>
							<entry>Delete</entry>
						</row>
						<row>
							<entry condition="pot">0x0000000000004000</entry>
							<entry>Rename</entry>
						</row>
						<row>
							<entry condition="pot">0x0000000000008000</entry>
							<entry>Submodule Update</entry>
						</row>
						<row>
							<entry condition="pot">0x0000000000010000</entry>
							<entry>Diff</entry>
						</row>
						<row>
							<entry condition="pot">0x0000000000020000</entry>
							<entry>Show Log</entry>
						</row>
						<row>
							<entry condition="pot">0x0000000000040000</entry>
							<entry>Edit Conflicts</entry>
						</row>
						<row>
							<entry condition="pot">0x0000000000080000</entry>
							<entry>Reference Browser</entry>
						</row>

						<row>
							<entry condition="pot">0x0000000000100000</entry>
							<entry>Check for modifications</entry>
						</row>
						<row>
							<entry condition="pot">0x0000000000200000</entry>
							<entry>Ignore</entry>
						</row>
						<row>
							<entry condition="pot">0x0000000000400000</entry>
							<entry>RefLog</entry>
						</row>
						<row>
							<entry condition="pot">0x0000000000800000</entry>
							<entry>Blame</entry>
						</row>
						<row>
							<entry condition="pot">0x0000000001000000</entry>
							<entry>Repository Browser</entry>
						</row>
						<row>
							<entry condition="pot">0x0000000002000000</entry>
							<entry>Apply Patch</entry>
						</row>
						<row>
							<entry condition="pot">0x0000000004000000</entry>
							<entry>Delete (keep local)</entry>
						</row>
						<row>
							<entry condition="pot">0x0000000008000000</entry>
							<entry>SVN Rebase</entry>
						</row>
						<row>
							<entry condition="pot">0x0000000010000000</entry>
							<entry condition="pot">SVN DCommit</entry>
						</row>
						<row>
							<entry condition="pot">0x0000000040000000</entry>
							<entry>SVN Ignore</entry>
						</row>
						<row>
							<entry condition="pot">0x0000000100000000</entry>
							<entry>Log of Submodule folder</entry>
						</row>
						<row>
							<entry condition="pot">0x0000000200000000</entry>
							<entry>Rev Diff</entry>
						</row>
						<row>
							<entry condition="pot">0x0000000800000000</entry>
							<entry>Pull</entry>
						</row>
						<row>
							<entry condition="pot">0x0000001000000000</entry>
							<entry>Push</entry>
						</row>
						<row>
							<entry condition="pot">0x0000002000000000</entry>
							<entry>Clone</entry>
						</row>
						<row>
							<entry condition="pot">0x0000004000000000</entry>
							<entry>Tag</entry>
						</row>
						<row>
							<entry condition="pot">0x0000008000000000</entry>
							<entry>Format Patch</entry>
						</row>
						<row>
							<entry condition="pot">0x0000010000000000</entry>
							<entry>Import Patch</entry>
						</row>
						<row>
							<entry condition="pot">0x0000040000000000</entry>
							<entry>Fetch</entry>
						</row>
						<row>
							<entry condition="pot">0x0000080000000000</entry>
							<entry>Rebase</entry>
						</row>
						<row>
							<entry condition="pot">0x0000100000000000</entry>
							<entry>Stash Save</entry>
						</row>
						<row>
							<entry condition="pot">0x0000200000000000</entry>
							<entry>Stash Apply</entry>
						</row>
						<row>
							<entry condition="pot">0x0000400000000000</entry>
							<entry>Stash List</entry>
						</row>
						<row>
							<entry condition="pot">0x0000800000000000</entry>
							<entry>Submodule Add</entry>
						</row>
						<row>
							<entry condition="pot">0x0001000000000000</entry>
							<entry>Submodule Sync</entry>
						</row>
						<row>
							<entry condition="pot">0x0002000000000000</entry>
							<entry>Stash Pop</entry>
						</row>
						<row>
							<entry condition="pot">0x0004000000000000</entry>
							<entry>Diff two files</entry>
						</row>
						<row>
							<entry condition="pot">0x0008000000000000</entry>
							<entry>Bisect</entry>
						</row>
						<row>
							<entry condition="pot">0x0080000000000000</entry>
							<entry>SVN Fetch</entry>
						</row>
						<row>
							<entry condition="pot">0x0100000000000000</entry>
							<entry>Revision graph</entry>
						</row>
						<row>
							<entry condition="pot">0x0200000000000000</entry>
							<entry>Daemon</entry>
						</row>
						<row>
							<entry condition="pot">0x2000000000000000</entry>
							<entry>Settings</entry>
						</row>
						<row>
							<entry condition="pot">0x4000000000000000</entry>
							<entry>Help</entry>
						</row>
						<row>
							<entry condition="pot">0x8000000000000000</entry>
							<entry>About</entry>
						</row>
					</tbody>
				</tgroup>
			</table>
		</para>
		<para>
			Example: to disable the <literal>Sendmail</literal>, the
			<literal>Rebase</literal>
			and the <literal>Settings</literal> menu entries, add the values assigned
			to the entries like this:
<screen>
  0x0000000000000100
+ 0x0000080000000000
+ 0x2000000000000000
= 0x2000080000000100
</screen>
			The lower <literal>DWORD</literal> value (<literal>0x00000100</literal>)
			must then be stored in
			<filename>HKEY_CURRENT_USER\Software\TortoiseGit\ContextMenuEntriesMaskLow</filename>,
			the higher <literal>DWORD</literal> value (<literal>0x20000800</literal>) in
			<filename>HKEY_CURRENT_USER\Software\TortoiseGit\ContextMenuEntriesMaskHigh</filename>.
		</para>
		<para>
			To enable the menu entries again, simply delete the two registry keys.
		</para>
	</sect1>
</appendix>
