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