Installation & Upgrade

What are the system prerequisites of TortoiseGit?

  • Windows Vista SP2 or newer is required (last version which is compatible with Windows XP is
  • For Windows 7, SP1 is required; for Windows Vista, SP2 is required
  • Admin privileges for the installation
  • Windows Installer 4.5 (required since TortoiseGit
  • A command line git.exe is required by TortoiseGit; see this nice StackOverflow answer for clarification
    • Git for Windows 2.0+ is recommended
    • Installation of Git for Windows can be done with preselected options, however, no need to install the "Windows Explorer integration". If you know about CRLF and LF line endings and you have editors coping with that, you should select "Checkout as-is, commit as-is" in order to prevent automatic translations.
    • minimum compatible version is 1.9.5
    • (Cygwin and Msys2 Git also work, see manual for configuration. Please note that Cygwin and Msys2 Git are not officially supported by TortoiseGit as the developers only use Git for Windows. Bug reports, however, are welcome.)

↑ Top

How to install TortoiseGit?

Check the system prerequisites which are listed above.

As a command-line git client is required for using TortoiseGit, you have to install both. The recommended order is to install TortoiseGit first.

Just download the setup package for your system and install it. If you want a localized interface of TortoiseGit, also download a language pack and install it. If you are running a 64 bit system, you do not need to download and install the 32 bit version: the 32 bit shell extension is included in the 64 bit installer since TortoiseGit

↑ Top

How to update/upgrade TortoiseGit?

Before upgrading you should read the release notes so that you know what changed.

Just download the setup package for your system and install it. The old version will be replaced automatically. If possible please use the automatic updater of TortoiseGit (in this case the binaries are cryptographically verified). You can trigger an update check by going to the about dialog of TortoiseGit and clicking "Check for update".

If you are upgrading from or older and you have installed the 32-bit version on a 64-bit system you have to uninstall the 32-bit version first.

↑ Top

The installer fails with an error message

There are some error messages which are more common:

"This installation package is not supported by this processor type. Contact your product vendor."
This means you are trying to install the 64-bit version of TortoiseGit on a normal 32-bit operating system. You need to download and use the correct msi file for your OS. For normal 32-bit OS, make sure the msi filename does not have "64-bit" in it.
"Please wait while the installer finishes determining your disk space requirements."
Cleanup/empty the temp-directory (e.g. C:\Users\<your user>\AppData\Local\Temp, C:\User and Settings\<your user>\Local Settings\Temp, c:\Windows\Temp\).

↑ Top

Installer requires to close/restart at lot of programs on update

TortoiseGit is a shell extension. Any program that displays an Explorer-like dialog (such as a File Open or Save dialog) will load TortoiseGit.dll. Therefore, many processes might require to be restarted, but due to known installer issues that are outside the scope of TortoiseGit, this can go wrong. The easiest workaround is to first close all applications before running an install/upgrade. For more info, see also issue #2557.

↑ Top

Overlay icons

Why don't the icon overlays appear?

  • Don't forget to reboot your PC after the installation; if you haven't, please do so now. TortoiseGit is a Windows Explorer Shell extension and will be loaded together with Explorer.
  • Go to the settings of TortoiseGit and activate the icon overlays for at least the fixed drives. The installer does this automatically for the current user (can't do it for other users…) but since you are using TortoiseGit as a different user than you installed it you need to set this manually.

(Based on a similar TortoiseSVN FAQ entry.)

↑ Top

The overlay icons appear, but not all of them!

You may find that not all of these icons are used on your system. This is because the number of overlays allowed by Windows is limited to 15. Windows uses 4 of those, and the remaining 11 can be used by other applications. And if you have OneDrive installed, that uses another 5 slots. If you then have another cloud drive tool installed, those slots can be used up. TortoiseGit and TortoiseSVN try to be a "Good Citizen ™" and limit its use of overlays to give other apps a chance.

  • Normal, Modified and Conflicted are always loaded and visible (if possible!).
  • Deleted is loaded if possible, but falls back to Modified if there are not enough slots.
  • ReadOnly is loaded if possible, but falls back to Normal if there are not enough slots.
  • Locked is only loaded if there are less than 13 overlays already loaded. It falls back to Normal if there are not enough slots.
  • Added is only loaded if there are less than 14 overlays already loaded. It falls back to Modified if there are not enough slots.

You can check which other apps are using overlays by using Regedit to look at HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Explorer\ShellIconOverlayIdentifiers

Other apps which are known to use overlays:

  • Windows itself. Vista and Win7 use more than XP.
  • SkyDrive
  • OneDrive
  • GDrive
  • Mega
  • Dropbox
  • OwnCloud
  • many others…

If there are too many overlay handlers installed and TortoiseGit does not show any overlays, you can try to delete some of the installed handlers from the registry. But be careful when editing the registry!

Deletion is sometimes a bit tricky. You can also try to prefix the Tortoise* entries with spaces and/or double quotes (").

Please also see issues #692 and #2548 for more user reports.

(Based on a similar TortoiseSVN FAQ entry.)

↑ Top

Why are the icons only visible on local and not on network drives?

Go to the Settings -> Look and Feel -> Icon Overlays and check the drive types for which you want to see overlay icons. Be aware that enabling overlays for network drives will slow down not only TortoiseGit but the whole system.

Based on a similar TortoiseSVN FAQ entry

↑ Top

How can I…

… make TortoiseGit remember HTTP(s) credentials?

There is a very good answer on StackOverflow.

↑ Top

… make TortoiseGit forget stored HTTP(s) credentials?

There is a very good answer on StackOverflow.

↑ Top

… use PuTTY for git cli and git bash?

Create an environment variable called "GIT_SSH" with the path to the PuTTY plink.exe or preferably to TortoiseGitPLink.exe. This can be done on the command line by executing "set GIT_SSH=PATH_TO_PLINK.EXE" ("C:\Program Files\TortoiseGit\bin\TortoiseGitPLink.exe" on default installations) or permanently.

↑ Top

… close/push/pull from a server with a self signed or "invalid" certificate?

There is a very good answer on StackOverflow.

↑ Top

General questions

~/.ssh/config seems to be ignored by TortoiseGit

TortoiseGit uses TortoiseGitPlink by default as SSH client. PuTTY and TortoiseGitPlink do not respect ~/.ssh/config (which is the config file for OpenSSH). Both tools store, like Windows tools, their configuration in registry.

Please see the TortoiseGit Manual - Tips and tricks for SSH/PuTTY for configuration hints.

If you want to use OpenSSH, set the SSH client to ssh.exe in TortoiseGit network settings (there is no need to use the full path to "ssh.exe" as it is on the %PATH%).

(Based on an answer on StackOverflow.)

↑ Top

TortoiseGitBlame shows menu in wrong language

You have to reset the menu bar (even if you did not make any changes to it). Left click -> Customize -> Menu tab and hit Reset/Restore.

↑ Top