doc/source/en/TortoiseGit/tsvn_dug/dug_settings_hooks.xml

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   2 <!DOCTYPE sect2 SYSTEM "../../../dtd/dblite.dtd">\r
   3 <sect2 id="tsvn-dug-settings-hooks">\r
   4         <title>Client Side Hook Scripts</title>\r
   5         <?dbhh topicname="HIDD_SETTINGSHOOKS"?>\r
   6         <?dbhh topicname="HIDD_SETTINGSHOOKCONFIG"?>\r
   7         <!--\r
   8         <indexterm>\r
   9                 <primary>client hooks</primary>\r
  10         </indexterm>\r
  11         <indexterm>\r
  12                 <primary>hook scripts</primary>\r
  13         </indexterm>\r
  14         <para>\r
  15                 <figure id="tsvn-dug-settings-dia-hooks">\r
  16                         <title>The Settings Dialog, Hook Scripts Page</title>\r
  17                         <graphic fileref="../images/SettingsHooks.png"/>\r
  18                 </figure>\r
  19                 This dialog allows you to set up hook scripts which will be\r
  20                 executed automatically when certain Git actions are performed.\r
  21                 As opposed to the hook scripts explained in <xref linkend="tsvn-repository-hooks"/>,\r
  22                 these scripts are executed locally on the client. \r
  23         </para>\r
  24         <para>\r
  25                 One application for such hooks might be to call a program like\r
  26                 <literal>SubWCRev.exe</literal> to update version numbers after a commit,\r
  27                 and perhaps to trigger a rebuild.\r
  28         </para>\r
  29         <para>\r
  30                 For various security and implementation reasons, hook scripts are defined\r
  31                 locally on a machine, rather than as project properties. You define what\r
  32                 happens, no matter what someone else commits to the repository. Of course\r
  33                 you can always choose to call a script which is itself under version control.\r
  34         </para>\r
  35         <para>\r
  36                 <figure id="tsvn-dug-settings-dia-hook-edit">\r
  37                         <title>The Settings Dialog, Configure Hook Scripts</title>\r
  38                         <graphic fileref="../images/SettingsHookEdit.png"/>\r
  39                 </figure>\r
  40                 To add a new hook script, simply click <guibutton>Add</guibutton>\r
  41                 and fill in the details.\r
  42         </para>\r
  43         <para>\r
  44                 There are currently six types of hook script available\r
  45                 <variablelist>\r
  46                         <varlistentry>\r
  47                                 <term>Start-commit</term>\r
  48                                 <listitem>\r
  49                                         <para>\r
  50                                                 Called before the commit dialog is shown.\r
  51                                                 You might want to use this if the hook modifies a versioned\r
  52                                                 file and affects the list of files that need to be committed\r
  53                                                 and/or commit message. However you should note that because\r
  54                                                 the hook is called at an early stage, the full list of objects\r
  55                                                 selected for commit is not available.\r
  56                                         </para>\r
  57                                 </listitem>\r
  58                         </varlistentry>\r
  59                         <varlistentry>\r
  60                                 <term>Pre-commit</term>\r
  61                                 <listitem>\r
  62                                         <para>\r
  63                                                 Called after the user clicks <guibutton>OK</guibutton>\r
  64                                                 in the commit dialog, and before the actual commit begins.\r
  65                                                 This hook has a list of exactly what will be committed.\r
  66                                         </para>\r
  67                                 </listitem>\r
  68                         </varlistentry>\r
  69                         <varlistentry>\r
  70                                 <term>Post-commit</term>\r
  71                                 <listitem>\r
  72                                         <para>\r
  73                                                 Called after the commit finishes (whether successful or not).\r
  74                                         </para>\r
  75                                 </listitem>\r
  76                         </varlistentry>\r
  77                         <varlistentry>\r
  78                                 <term>Start-update</term>\r
  79                                 <listitem>\r
  80                                         <para>\r
  81                                                 Called before the update-to-revision dialog is shown.\r
  82                                         </para>\r
  83                                 </listitem>\r
  84                         </varlistentry>\r
  85                         <varlistentry>\r
  86                                 <term>Pre-update</term>\r
  87                                 <listitem>\r
  88                                         <para>\r
  89                                                 Called before the actual Git update begins.\r
  90                                         </para>\r
  91                                 </listitem>\r
  92                         </varlistentry>\r
  93                         <varlistentry>\r
  94                                 <term>Post-update</term>\r
  95                                 <listitem>\r
  96                                         <para>\r
  97                                                 Called after the update finishes (whether successful or not).\r
  98                                         </para>\r
  99                                 </listitem>\r
 100                         </varlistentry>\r
 101                 </variablelist>\r
 102         </para>\r
 103         <para>\r
 104                 A hook is defined for a particular working copy path. You only need to\r
 105                 specify the top level path; if you perform an operation in a sub-folder,\r
 106                 TortoiseGit will automatically search upwards for a matching path.\r
 107         </para>\r
 108         <para>\r
 109                 Next you must specify the command line to execute, starting with the path\r
 110                 to the hook script or executable.\r
 111                 This could be a batch file, an executable file or any other file which\r
 112                 has a valid windows file association, eg. a perl script.\r
 113         </para>\r
 114         <para>\r
 115                 The command line includes several parameters which get filled in\r
 116                 by TortoiseGit. The parameters passed depend upon which hook is called.\r
 117                 Each hook has its own parameters which are passed in the following order:\r
 118                 <variablelist>\r
 119                         <varlistentry>\r
 120                                 <term>Start-commit</term>\r
 121                                 <listitem condition="pot">\r
 122                                         <para>\r
 123                                                 <literal>PATH</literal>\r
 124                                                 <literal>MESSAGEFILE</literal>\r
 125                                                 <literal>CWD</literal>\r
 126                                         </para>\r
 127                                 </listitem>\r
 128                         </varlistentry>\r
 129                         <varlistentry>\r
 130                                 <term>Pre-commit</term>\r
 131                                 <listitem condition="pot">\r
 132                                         <para>\r
 133                                                 <literal>PATH</literal>\r
 134                                                 <literal>DEPTH</literal>\r
 135                                                 <literal>MESSAGEFILE</literal>\r
 136                                                 <literal>CWD</literal>\r
 137                                         </para>\r
 138                                 </listitem>\r
 139                         </varlistentry>\r
 140                         <varlistentry>\r
 141                                 <term>Post-commit</term>\r
 142                                 <listitem condition="pot">\r
 143                                         <para>\r
 144                                                 <literal>PATH</literal>\r
 145                                                 <literal>DEPTH</literal>\r
 146                                                 <literal>MESSAGEFILE</literal>\r
 147                                                 <literal>REVISION</literal>\r
 148                                                 <literal>ERROR</literal>\r
 149                                                 <literal>CWD</literal>\r
 150                                         </para>\r
 151                                 </listitem>\r
 152                         </varlistentry>\r
 153                         <varlistentry>\r
 154                                 <term>Start-update</term>\r
 155                                 <listitem condition="pot">\r
 156                                         <para>\r
 157                                                 <literal>PATH</literal>\r
 158                                                 <literal>CWD</literal>\r
 159                                         </para>\r
 160                                 </listitem>\r
 161                         </varlistentry>\r
 162                         <varlistentry>\r
 163                                 <term>Pre-update</term>\r
 164                                 <listitem condition="pot">\r
 165                                         <para>\r
 166                                                 <literal>PATH</literal>\r
 167                                                 <literal>DEPTH</literal>\r
 168                                                 <literal>REVISION</literal>\r
 169                                                 <literal>CWD</literal>\r
 170                                         </para>\r
 171                                 </listitem>\r
 172                         </varlistentry>\r
 173                         <varlistentry>\r
 174                                 <term>Post-update</term>\r
 175                                 <listitem condition="pot">\r
 176                                         <para>\r
 177                                                 <literal>PATH</literal>\r
 178                                                 <literal>DEPTH</literal>\r
 179                                                 <literal>REVISION</literal>\r
 180                                                 <literal>ERROR</literal>\r
 181                                                 <literal>CWD</literal>\r
 182                                         </para>\r
 183                                 </listitem>\r
 184                         </varlistentry>\r
 185                 </variablelist>\r
 186         </para>\r
 187         <para>\r
 188                 The meaning of each of these parameters is described here:\r
 189                 <variablelist>\r
 190                         <varlistentry>\r
 191                                 <term condition="pot">PATH</term>\r
 192                                 <listitem>\r
 193                                         <para>\r
 194                                                 A path to a temporary file which contains all the\r
 195                                                 paths for which the operation was started.\r
 196                                                 Each path is on a separate line in the temp file.\r
 197                                         </para>\r
 198                                 </listitem>\r
 199                         </varlistentry>\r
 200                         <varlistentry>\r
 201                                 <term condition="pot">DEPTH</term>\r
 202                                 <listitem>\r
 203                                         <para>\r
 204                                                 The depth with which the commit/update is done.\r
 205                                         </para>\r
 206                                         <para>\r
 207                                         Possible values are:\r
 208                                         <variablelist>\r
 209                                                 <varlistentry>\r
 210                                                         <term condition="pot">-2</term>\r
 211                                                         <listitem>\r
 212                                                                 <para>\r
 213                                                                         <literal>svn_depth_unknown</literal>\r
 214                                                                 </para>\r
 215                                                         </listitem>\r
 216                                                 </varlistentry>\r
 217                                                 <varlistentry>\r
 218                                                         <term condition="pot">-1</term>\r
 219                                                         <listitem>\r
 220                                                                 <para>\r
 221                                                                         <literal>svn_depth_exclude</literal>\r
 222                                                                 </para>\r
 223                                                         </listitem>\r
 224                                                 </varlistentry>\r
 225                                                 <varlistentry>\r
 226                                                         <term condition="pot">0</term>\r
 227                                                         <listitem>\r
 228                                                                 <para>\r
 229                                                                         <literal>svn_depth_empty</literal>\r
 230                                                                 </para>\r
 231                                                         </listitem>\r
 232                                                 </varlistentry>\r
 233                                                 <varlistentry>\r
 234                                                         <term condition="pot">1</term>\r
 235                                                         <listitem>\r
 236                                                                 <para>\r
 237                                                                         <literal>svn_depth_files</literal>\r
 238                                                                 </para>\r
 239                                                         </listitem>\r
 240                                                 </varlistentry>\r
 241                                                 <varlistentry>\r
 242                                                         <term condition="pot">2</term>\r
 243                                                         <listitem>\r
 244                                                                 <para>\r
 245                                                                         <literal>svn_depth_immediates</literal>\r
 246                                                                 </para>\r
 247                                                         </listitem>\r
 248                                                 </varlistentry>\r
 249                                                 <varlistentry>\r
 250                                                         <term condition="pot">3</term>\r
 251                                                         <listitem>\r
 252                                                                 <para>\r
 253                                                                         <literal>svn_depth_infinity</literal>\r
 254                                                                 </para>\r
 255                                                         </listitem>\r
 256                                                 </varlistentry>\r
 257                                         </variablelist>\r
 258                                         </para>\r
 259                                 </listitem>\r
 260                         </varlistentry>\r
 261                         <varlistentry>\r
 262                                 <term condition="pot">MESSAGEFILE</term>\r
 263                                 <listitem>\r
 264                                         <para>\r
 265                                                 Path to a file containing the log message for\r
 266                                                 the commit. The file contains the text in UTF-8\r
 267                                                 encoding. After successful execution of the\r
 268                                                 start-commit hook, the log message is read back,\r
 269                                                 giving the hook a chance to modify it.\r
 270                                         </para>\r
 271                                 </listitem>\r
 272                         </varlistentry>\r
 273                         <varlistentry>\r
 274                                 <term condition="pot">REVISION</term>\r
 275                                 <listitem>\r
 276                                         <para>\r
 277                                                 The repository revision to which the update should\r
 278                                                 be done or after a commit completes.\r
 279                                         </para>\r
 280                                 </listitem>\r
 281                         </varlistentry>\r
 282                         <varlistentry>\r
 283                                 <term condition="pot">ERROR</term>\r
 284                                 <listitem>\r
 285                                         <para>\r
 286                                                 Path to a file containing the error message.\r
 287                                                 If there was no error, the file will be empty.\r
 288                                         </para>\r
 289                                 </listitem>\r
 290                         </varlistentry>\r
 291                         <varlistentry>\r
 292                                 <term condition="pot">CWD</term>\r
 293                                 <listitem>\r
 294                                         <para>\r
 295                                                 The current working directory with which the script is run.\r
 296                                                 This is set to the common root directory of all affected paths.\r
 297                                         </para>\r
 298                                 </listitem>\r
 299                         </varlistentry>\r
 300                 </variablelist>\r
 301         </para>\r
 302         <para>\r
 303                 Note that although we have given these parameters names for convenience,\r
 304                 you do not have to refer to those names in the hook settings.\r
 305                 All parameters listed for a particular hook are always passed,\r
 306                 whether you want them or not ;-)\r
 307         </para>\r
 308         <para>\r
 309                 If you want the Git operation to hold off until the hook has completed,\r
 310                 check <guilabel>Wait for the script to finish</guilabel>.\r
 311         </para>\r
 312         <para>\r
 313                 Normally you will want to hide ugly DOS boxes when the script runs,\r
 314                 so <guilabel>Hide the script while running</guilabel> is checked by default.\r
 315         </para>\r
 316         <para>\r
 317                 Sample client hook scripts can be found in the <literal>contrib</literal> folder in the\r
 318                 <ulink url="http://TortoiseGit.tigris.org/svn/TortoiseGit/trunk/contrib/hook-scripts">\r
 319                         <citetitle>TortoiseGit repository</citetitle>\r
 320                 </ulink>.\r
 321                 (<xref linkend="tsvn-preface-source"/> explains how to access the repository).\r
 322         </para>\r
 323         -->\r
 324         <sect3 id="tsvn-dug-settings-hooks-issuetracker">\r
 325                 <title>Issue Tracker Integration</title>\r
 326                 <?dbhh topicname="HIDD_SETTINGSBUGTRAQ"?>\r
 327                 <?dbhh topicname="HIDD_SETTINGSBUGTRAQADV"?>\r
 328                 <para>\r
 329                         TortoiseGit can use a COM plugin to query issue trackers when in the\r
 330                         commit dialog. The use of such plugins is described in\r
 331                         <xref linkend="tsvn-dug-bugtracker-ref" />.\r
 332                         If your system administrator has provided you with a plugin, which\r
 333                         you have already installed and registered, this is the place to\r
 334                         specify how it integrates with your working copy.\r
 335                 </para>\r
 336                 <para>\r
 337                         <figure id="tsvn-dug-settings-dia-issuetracker">\r
 338                                 <title>The Settings Dialog, Issue Tracker Integration Page</title>\r
 339                                 <graphic fileref="../images/SettingsIssueTracker.png"/>\r
 340                         </figure>\r
 341                         Click on <guibutton>Add...</guibutton> to use the plugin with\r
 342                         a particular working copy. Here you can specify the working copy\r
 343                         path, choose which plugin to use from a drop down list of all\r
 344                         registered issue tracker plugins, and any parameters to pass.\r
 345                         The parameters will be specific to the plugin, but might include\r
 346                         your user name on the issue tracker so that the plugin can\r
 347                         query for issues which are assigned to you.\r
 348                 </para>\r
 349                 <para>\r
 350                         If you want all users to use the same COM plugin for your project, you\r
 351                         can specify the plugin also with the properties <literal>bugtraq:provideruuid</literal>\r
 352                         and <literal>bugtraq:providerparams</literal>.\r
 353 \r
 354                         <variablelist>\r
 355                                 <varlistentry>\r
 356                                         <term condition="pot">bugtraq:provideruuid</term>\r
 357                                         <listitem>\r
 358                                                 <para>\r
 359                                                         This property specifies the COM UUID of the IBugTraqProvider,\r
 360                                                         for example <literal>{91974081-2DC7-4FB1-B3BE-0DE1C8D6CE4E}</literal>.\r
 361                                                 </para>\r
 362                                         </listitem>\r
 363                                 </varlistentry>\r
 364                                 <varlistentry>\r
 365                                         <term condition="pot">bugtraq:providerparams</term>\r
 366                                         <listitem>\r
 367                                                 <para>\r
 368                                                         This property specifies the parameters passed to the IBugTraqProvider.\r
 369                                                 </para>\r
 370                                         </listitem>\r
 371                                 </varlistentry>\r
 372                         </variablelist>\r
 373                         Please check the documentation of your IBugTraqProvider plugin to find out what\r
 374                         to specify in these two properties.\r
 375                 </para>\r
 376         </sect3>\r
 377         <sect3 id="tsvn-dug-settings-hooks-issuetracker-config">\r
 378         <title>Config</title>\r
 379                 <?dbhh topicname="HIDD_SETTINGSBUGTRAQ_CONFIG"?>\r
 380                 <para>\r
 381                         <figure id="tsvn-dug-settings-hooks-issuetrack-config">\r
 382                                 <title>The Settings Dialog, issue track config</title>\r
 383                                 <graphic fileref="../images/SettingsIssueTrackerConfig.png"/>\r
 384                         </figure>\r
 385                 </para>\r
 386         </sect3>\r
 387 </sect2>\r