/doc/source/intro.txt

  1************
  2Introduction
  3************
  4
  5.. module:: introduction
  6	:synopsis: Introduce TortoiseHg and its various parts
  7
  8What is TortoiseHg?
  9===================
 10
 11TortoiseHg is a set of graphical tools and a shell extension for the
 12`Mercurial <http://mercurial.selenic.com/wiki/>`_ distributed revision control
 13system.
 14
 15On Windows,
 16	TortoiseHg consists of a shell extension, which provides overlay
 17	icons and context menus in your file explorer, and a command line
 18	program named :file:`thg.exe` which can launch the TortoiseHg tools.
 19	Binary packages of TortoiseHg for Windows come with Mercurial and a
 20	merge tool and are thus completely ready for use "Out of the Box".
 21
 22On Linux,
 23	TortoiseHg consists of a command line thg script and a Nautilus
 24	extension which provides overlays and context menus in your file
 25	explorer.  You must have Mercurial installed separately in order to
 26	run TortoiseHg on Linux.  TortoiseHg binary packages list Mercurial
 27	as a dependency, so it is usually installed for you automatically.
 28
 29.. note::
 30	On Windows, TortoiseHg includes both thg.exe and thgw.exe.  The
 31	latter is intended to be launched from desktop shortcuts or menu
 32	entries as it will refuse to open a command console.  thg.exe is for
 33	use on the console, and can provide command line help.  The thg.cmd
 34	batch file that our installer adds into your PATH runs thg.exe.
 35
 36TortoiseHg is primarily written in Python and PyQt (the Windows shell
 37extension being the notable exception).  The thg script and TortoiseHg
 38dialogs can be used on any platform that supports PyQt, including Mac
 39OS X.
 40
 41
 42Installing TortoiseHg
 43=====================
 44
 45On Windows
 46----------
 47
 48TortoiseHg comes with an easy to use MSI installer.  You can always find
 49the most up to date release on our `website
 50<http://tortoisehg.bitbucket.org/download/windows.html>`_.
 51Simply double click on the installer file and follow its instructions.
 52
 53After a first time install, a re-login is usually required to start the
 54icon overlays.
 55
 56During upgrades, the installer will ask to close or restart any
 57applications that have loaded the TortoiseHg shell extension.  If you
 58allow those applications to be closed, the upgrade will not require a
 59reboot or logout.  If other users are logged in, or if there are
 60applications which cannot be shutdown, a reboot will be required to
 61complete the install.
 62
 63.. note::
 64	If you have a legacy version of TortoiseHg installed, the 1.0
 65	installer will ask that you to remove it.  The uninstall can be
 66	initiated from the control panel or the start menu.
 67
 68.. warning::
 69	Legacy uninstallers (<=0.9.3) have a tendency to delete your user
 70	Mercurial.ini file, so backup your file before uninstalling the
 71	older TortoiseHg versions.  This is not a problem with the newer MSI
 72	packages.
 73
 74All legacy TortoiseHg installers (before version 1.0) were built with
 75InnoSetup.  They installed a TortoiseOverlay package as a separate
 76application, so you always saw both TortoiseHg and TortoiseOverlay as
 77two applications in the *Add/Remove Programs* control panel program.
 78(On X64 platforms, there were two TortoiseOverlays, one for x86
 79processes and one of x64 processes).
 80
 81The new MSI installers for TortoiseHg 1.0 and later include the
 82TortoiseOverlay packages as "merge modules" so they do not appear as
 83separate applications anymore.  It should be safe to uninstall the older
 84TortoiseOverlay applications from *Add/Remove Programs* after you
 85uninstall the legacy (<=0.9.3) TortoiseHg installer, unless you have
 86other Tortoise products that still use the separate TortoiseOverlay MSI
 87approach (TortoiseCVS or TortoiseBZR).
 88
 89.. note::
 90	TortoiseOverlay is a shim package that allows multiple Tortoise
 91	style shell extension clients to share overlay slots.  This is
 92	necessary because even modern Windows platforms only support a
 93	limited number of overlay slots (11-14).  TortoiseOverlay
 94	packages are created by the TortoiseSVN developers.
 95
 96To be completely safe, there are two approaches you can take:
 97
 981) Just leave the old TortoiseOverlay packages installed.  They do not
 99   harm anything.
1002) Uninstall all the old TortoiseOverlay packages, then re-install all
101   of your Tortoise products until they are all functional.
102
103Finally, if you have problems with the shell extension even after
104re-logging in, we recommend you re-run the installer and select the
105*Repair* option.  There were problems with a few versions of
106TortoiseOverlays that cause upgrades to subtly fail until the *Repair*
107process is run.
108
109
110
111Language settings
112^^^^^^^^^^^^^^^^^
113
114The TortoiseHg user interface has been translated into many languages.
115Language packs are not required since all available languages are
116installed. Look in :file:`C:\\Program Files\\TortoiseHg\\locale` for the
117available languages. To enable a language just set the environment
118variable ``LANGUAGE`` to the desidered language, e.g. for italian
119``set LANGUAGE=it``.
120
121The Windows shell extension context menus get their translations from
122the Windows registry.  Translations for many locales were installed
123under :file:`C:\\Program Files\\TortoiseHg\\i18n\\cmenu`.  Select the
124locale you would like to use, double-click on it, and confirm all
125requests.
126
127On Linux and Mac
128----------------
129
130The most recent Linux packages can be found on our `download
131<http://tortoisehg.bitbucket.org/download/linux.html>`_ page.
132
133For Mac OS X, no packages are available but you can run thg and all the
134dialogs via the source install method. For details, see
135`Mac OS X <http://bitbucket.org/tortoisehg/thg/wiki/Home>`_.
136
137.. note::
138	If you install TortoiseHg from source, you need to add our
139	contrib/mergetools.rc file to your HGRC path in some way.  One
140	approach is to %include it from your ~/.hgrc file.
141
142Language settings
143^^^^^^^^^^^^^^^^^
144
145The TortoiseHg tools use Python's
146`gettext <http://docs.python.org/library/gettext.html>`_ library to
147localize their text.  To get localized dialogs, it is recommended that
148you set the LANGUAGE environment variable to your locale of choice.
149
150.. vim: noet ts=4