Installation & Upgrade

What are the system prerequisites of TortoiseGit?

  • Windows 7 (SP1) or newer is required (last version compatiable with Vista (SP2) is 2.4.0; last version compatible with Windows XP is 1.8.16.0
  • Admin privileges for the installation
  • A command line git.exe is required by TortoiseGit; see this nice StackOverflow answer for clarification
    • Git for Windows 2.24+ is required
    • 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.
    • (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 1.7.3.0.

↑ 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 1.7.3.0 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

How to update/upgrade Git?

Basically just install a new version of Git for Windows. Then, it is recommended to open TortoiseGit settings and selecting "Check now". This should do the trick and update/restart all components of TortoiseGit. If you just installed a Git for Windows version >= 2.24 and you use the Shell status cache, it is recommended to log-off and on again for changes in the Windows Explorer to take effect.

↑ Top

Overlay icons

Why don't the icon overlays appear?

(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 (and also HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Windows\CurrentVersion\Explorer\ShellIconOverlayIdentifiers on 64-bit Windows for 32-bit applications).

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!

The overlay handler are loaded by the order of the ASCII code. Thus, you need to make sure the Tortoise* overlay handler has a high precedence to be honored. Deletion of other handlers is sometimes a bit tricky. But you can also try to prefix the Tortoise* entries with spaces and/or double quotes (") - in general there seems to be a real war going on who has the most spaces.

Please also see issue #692 and issue #2548 and this answer on StackOverflow 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 -> 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

Why are the icons only visible on folders (green) and not on files?

In case files have no overlay icon and folders are displayed as modified the setting "Show excluded folders as normal" is active. Go to Settings -> Icon Overlays and make sure the path is not on a disabled drive type and is not explicitly excluded as an "Excluded path".

↑ Top

Why are the icons only visible in the Windows Explorer?

There is a very good answer on StackOverflow.

↑ Top

Why do versioned files show up as unversioned?

There is a very good answer on StackOverflow.

↑ 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 TortoiseGit with multiple accounts on one platform?

There is a very good answer on StackOverflow.

↑ Top

… use TortoiseGit with a SSH remote which uses a custom port?

When you use TortoiseGitPlink (the default), see this very good answer on StackOverflow. If you want to use OpenSSH, see this answer on StackOverflow. You might also be interested in this 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

In the commit dialog there is only little space for the commit message

The commit, the log and several other dialogs allow to adjust the size of some GUI elements. There is a slider between the GUI elements which allows to resize some GUI elements vertically, cf. issue #1761.

↑ Top

Why is non Git for Windows unsupported?

There are several reasons why non Git for Windows git.exe are not officially supported by TortoiseGit. MSYS2 Git, Cygwin Git and WSL Git run in an emulated *nix environment:

  • They have a separate %HOME% directory. Therefore, you need to take special care that your git.exe as well as TortoiseGit use the very same config.
  • Additionally to the different %HOME% directories, the used git.exe might behave differently based on specific platform dependant defaults, e.g. AutoCrLr or other CrLf text conversions. TortoiseGit tries to cope with that at various places (if specific quirks are enabled and is significantly slower), however, cannot do and test all possible scanarios. This is especially an issue for methods where libgit2 is used in TortoiseGit instead of calling git.exe, e.g. GitWCRev.
  • When you use submodules or different worktrees, Git uses .git files which contain a path. This path might be platform specific and, therefore, not valid on Windows (e.g., "/cygdrive/c/Users/...").
  • Reports by the Git for Windows maintainers underline that especially the MSYS2 Git and Cygwin Git variants don't even pass the whole test suite on Windows. Therefore, you cannot expect it to work properly in all cases.

The TortoiseGit developers only use Git for Windows. Bug reports, however, are welcome.

↑ Top