architecture.txt

   1 Overall architecture of TortoiseGit\r
   2 ===================================\r
   3 \r
   4 Mainly TortoiseGit consists of several executables and two DLLs which\r
   5 are of interest here (the project names are in parentheses bebind):\r
   6 \r
   7 * TortoiseGit(32).dll (TortoiseShell)\r
   8 * TortoiseGitStub(32).dll (TortoiseGitStub)\r
   9 * TortoiseGitProc.exe (TortoiseGitProc)\r
  10 * TGitCache.exe (TGitCache)\r
  11 * TortoiseGitBlame.exe (TortoiseGitBlame)\r
  12 * TortoiseGitIDiff.exe (TortoiseGitIDiff)\r
  13 * TortoiseGitUDiff.exe (TortoiseGitIDiff)\r
  14 * TortoiseGitMerge.exe (TortoiseGitMerge)\r
  15 * TortoiseGitPlink.exe (TortoiseGitPlink)\r
  16 * SshAskPass.exe (SshAskPass)\r
  17 * tgittouch.exe (tgittouch)\r
  18 \r
  19 TortoiseGit(32).dll and TortoiseGitStub(32).dll\r
  20 ===============================================\r
  21 These two files are the heart of the Explorer Shell extension.\r
  22 TortoiseGitStub(32).dll is registered as a shell extension and\r
  23 loads TortoiseGit(32).dll which finally provides the context menu\r
  24 and overlay icons (in combination with TGitCache.exe).\r
  25 \r
  26 TortoiseGit(32).dll checks which context menu items to show and when a\r
  27 context menu item is clicked on, it calls TortoiseGitProc.exe which\r
  28 handles all commands from the shell extension.\r
  29 \r
  30 Why two dlls? The reason for TortoiseGitStub(32).dll is the setting\r
  31 "Show overlays and context menu only in explorer". It checks whether\r
  32 the parent process is explorer.exe and depending on the setting\r
  33 TortoiseGit(32).dll gets loaded. - Before supporting this setting\r
  34 TortoiseGit directly registered TortoiseGit(32).dll as the TortoiseGit\r
  35 explorer shell extension w/o using TortoiseGitStub(32).dll.\r
  36 \r
  37 TortoiseGitProc.exe\r
  38 ===================\r
  39 This is the main TortoiseGit GUI program. It is automatically executed\r
  40 by the shell extension (TortoiseGit(32).dll) using command line\r
  41 parameters indicating which action/command to execute and which files/folders\r
  42 are selected in explorer.\r
  43 \r
  44 If you want to see the command line parameters passed to TortoiseGitProc.exe\r
  45 go to TortoiseGit settings, Advanced and set Debug to true. Starting from now\r
  46 you will see all parameters passed to TortoiseGitProc.exe.\r
  47 \r
  48 Some of the command line parameters (which we think are also useful for\r
  49 users) are documented on\r
  50 https://tortoisegit.org/docs/tortoisegit/tgit-automation.html#tgit-automation-basics.\r
  51 \r
  52 If this program is started without any parameter, it just displays the about dialog.\r
  53 \r
  54 Inside TortoiseGitProc all different commands have their own handler classes\r
  55 and maybe dialogs (in MSVC you can see all the project directories for them).\r
  56 Mostly TortoiseGitProc.exe will display its own dialogs and call git.exe. But for\r
  57 diffing or blaming it will execute the other .exe files (such as TortoiseGitBlame.exe)\r
  58 with appropriate command line parameters. Often TortoiseGitProc.exe also creates\r
  59 temp files which are passed to the tools.\r
  60 \r
  61 Noteworthy files\r
  62 ----------------\r
  63 Main class for functionality is AppUtils.cpp, which is called by many commands.\r
  64 \r
  65 The log dialog and other revision lists are handled by GitLogListBase.cpp or\r
  66 derived classes (context menu action handlers are in GitLogListAction.cpp).\r
  67 \r
  68 GitStatusListCtrl.cpp is used everywhere where file lists are displayed\r
  69 in dialogs, such as log dialog and commit dialog.\r
  70 \r
  71 TGitCache.exe\r
  72 =============\r
  73 This is a process running in the background. It calculates working tree and\r
  74 file statuses. The shell extension (TortoiseGit(32).dll) connects to it for\r
  75 asking which overlay icons to show.\r
  76 \r
  77 TGitCache also watches changes on folders which were opened in explorer before\r
  78 in order to instantly react on changes and propagating updates of the overlay\r
  79 icons to the shell extension.\r
  80 \r
  81 For more information you can set the CacheTrayIcon setting to true in the\r
  82 TortoiseGit advanced settings. After restarting TGitCache you can see a new\r
  83 icon in the systray. Double clicking on it opens a window showing which files\r
  84 TGitCache processes right now.\r
  85 \r
  86 TortoiseGitBlame.exe\r
  87 ====================\r
  88 This program displays the blame functionality. It is called by TortoiseGitProc.exe\r
  89 or manually by the user (there is an icon in the startmenu).\r
  90 \r
  91 TortoiseGitIDiff.exe\r
  92 ====================\r
  93 This program is for comparing images. It is called by TortoiseGitProc.exe\r
  94 or manually by the user (there is an icon in the startmenu).\r
  95 \r
  96 Command line parameters are document here:\r
  97 https://tortoisegit.org/docs/tortoisegit/tgit-automation-idiff.html\r
  98 \r
  99 TortoiseGitUDiff.exe\r
 100 ====================\r
 101 This program is for showing .patch and .diff files with syntax highlighting.\r
 102 It is called by TortoiseGitProc.exe or when the user double clicks on a .patch\r
 103 or .diff file (TortoiseGitUDiff.exe is registered as a handler for these file\r
 104 types on installation by default).\r
 105 \r
 106 TortoiseGitMerge.exe\r
 107 ====================\r
 108 This program is for comparing files and resolving conflicts. It is called by\r
 109 TortoiseGitProc.exe or manually by the user (there is an icon in the startmenu).\r
 110 \r
 111 Command line parameters are document here:\r
 112 https://tortoisegit.org/docs/tortoisegitmerge/tme-automation.html\r
 113 \r
 114 SshAskPass.exe\r
 115 ==============\r
 116 This program is for providing a guy for asking for credentials especially in\r
 117 git.exe and ssh.exe.\r
 118 \r
 119 Both, git.exe and ssh.exe (from OpenSSH) are command line tools. When executed\r
 120 from TortoiseGitProc.exe there is no terminal attached and, thus, those tools\r
 121 cannot ask for credentials. However, git.exe and ssh.exe allow to "register"\r
 122 a helper utility (using the enviroment variables SSH_ASKPASS and GIT_ASKPASS).\r
 123 \r
 124 All SshAskPass.exe does is, it displays the command line parameters in the GUI\r
 125 and passes the entered values to STDOUT (where it is read by the calling tool).\r
 126 \r
 127 tgittouch.exe\r
 128 =============\r
 129 This is a helper utility which creates/touches a file which is passed as\r
 130 command line parameter.\r
 131 \r
 132 It is needed for interacting with the Putty authentication agent (peagent).\r
 133 TortoiseGit needs to know when the user finished entering his/her password,\r
 134 but peagent is not blocking. Therefore, peagent is called with the private\r
 135 key and tgittouch.exe together with a tmp filename.Then TortoiseGitProc.exe\r
 136 waits untils the tmp-file is created.\r