| blob | 29c27278c4f3c3aa1bb5da96dea52fe1de7a9de0 |
1 <?xml version="1.0" encoding="UTF-8"?>\r
2 <!DOCTYPE sect2 SYSTEM "../../../dtd/dblite.dtd">\r
3 <sect2 id="tgit-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 <indexterm>\r
8 <primary>client hooks</primary>\r
9 </indexterm>\r
10 <indexterm>\r
11 <primary>hook scripts</primary>\r
12 </indexterm>\r
13 <para>\r
14 <figure id="tgit-dug-settings-dia-hooks">\r
15 <title>The Settings Dialog, Hook Scripts Page</title>\r
16 <graphic fileref="../images/SettingsHooks.png"/>\r
17 </figure>\r
18 This dialog allows you to set up hook scripts which will be\r
19 executed automatically when certain TortoiseGit actions are performed on the client side.\r
20 </para>\r
21 <para>\r
22 For various security and implementation reasons, hook scripts are defined\r
23 locally on a machine, rather than as project properties. You define what\r
24 happens, no matter what someone else commits to the repository. Of course\r
25 you can always choose to call a script which is itself under version control.\r
26 </para>\r
27 <para>\r
28 One application for such hooks might be to call a program like\r
29 <literal>GitWCRev.exe</literal> (<xref linkend="tgit-gitwcrev"/>)\r
30 to update version numbers after a commit,\r
31 and perhaps to trigger a rebuild.\r
32 </para>\r
33 <para>\r
34 <figure id="tgit-dug-settings-dia-hook-edit">\r
35 <title>The Settings Dialog, Configure Hook Scripts</title>\r
36 <graphic fileref="../images/SettingsHookEdit.png"/>\r
37 </figure>\r
38 To add a new hook script, simply click <guibutton>Add</guibutton>\r
39 and fill in the details.\r
40 </para>\r
41 <para>\r
42 There are currently six types of hook script available\r
43 <variablelist>\r
44 <varlistentry>\r
45 <term>Start-commit</term>\r
46 <listitem>\r
47 <para>\r
48 Called before the commit dialog is shown.\r
49 You might want to use this if the hook modifies a versioned\r
50 file and affects the list of files that need to be committed\r
51 and/or commit message. However you should note that because\r
52 the hook is called at an early stage, the full list of objects\r
53 selected for commit is not available.\r
54 </para>\r
55 </listitem>\r
56 </varlistentry>\r
57 <varlistentry>\r
58 <term>Pre-commit</term>\r
59 <listitem>\r
60 <para>\r
61 Called after the user clicks <guibutton>OK</guibutton>\r
62 in the commit dialog, and before the actual commit begins.\r
63 This hook has a list of exactly what will be committed.\r
64 </para>\r
65 </listitem>\r
66 </varlistentry>\r
67 <varlistentry>\r
68 <term>Post-commit</term>\r
69 <listitem>\r
70 <para>\r
71 Called after the commit finished successfully.\r
72 </para>\r
73 </listitem>\r
74 </varlistentry>\r
75 <varlistentry>\r
76 <term>Pre-push</term>\r
77 <listitem>\r
78 <para>\r
79 Called before actual Git push begins.\r
80 </para>\r
81 </listitem>\r
82 </varlistentry>\r
83 <varlistentry>\r
84 <term>Post-push</term>\r
85 <listitem>\r
86 <para>\r
87 Called after pushing finishes (whether successful or not).\r
88 </para>\r
89 </listitem>\r
90 </varlistentry>\r
91 <varlistentry>\r
92 <term>Pre-rebase</term>\r
93 <listitem>\r
94 <para>\r
95 Called before rebasing starts (after clicking on Start or autostart).\r
96 </para>\r
97 </listitem>\r
98 </varlistentry>\r
99 </variablelist>\r
100 </para>\r
101 <para>\r
102 A hook is defined for a particular working tree path. You only need to\r
103 specify the top level path; if you perform an operation in a sub-folder,\r
104 TortoiseGit will automatically search upwards for a matching path.\r
105 Use <literal>*</literal> for matching all working trees.\r
106 </para>\r
107 <para>\r
108 If the checkbox <guibutton>Run for this repository</guibutton> is checked then\r
109 the hook script is attached to the current repository and configured\r
110 automatically for every clone and checkout (the hook information is stored in\r
111 the file <filename>.tgitconfig</filename> in the repository root so that it will\r
112 be automatically shared with all other developers using TortoiseGit >= 2.7.1;\r
113 for security reasons TortoiseGit asks the user before running a hook which\r
114 is configured and shared in the repository).\r
115 In this case, you can specify paths for the command line with the\r
116 replacement string <literal>%root%</literal> for the path to the\r
117 working tree folder. The hook script has to be inside the repository and\r
118 also be checked out of course (please also note the security implications below).\r
119 If a user locally configures a hook for the exact repository root folder, the client side\r
120 defined hook takes precedence.\r
121 </para>\r
122 <para>\r
123 Next you must specify the command line to execute, starting with the path\r
124 to the hook script or executable.\r
125 This could be a batch file, an executable file or any other file which\r
126 has a valid windows file association, e.g. a perl script.\r
127 </para>\r
128 <para>\r
129 The command line includes several parameters which get filled in\r
130 by TortoiseGit. The parameters passed depend upon which hook is called.\r
131 Each hook has its own parameters which are passed in the following order:\r
132 <variablelist>\r
133 <varlistentry>\r
134 <term>Start-commit</term>\r
135 <listitem condition="pot">\r
136 <para>\r
137 <literal>PATH</literal>\r
138 <literal>MESSAGEFILE</literal>\r
139 <literal>CWD</literal>\r
140 </para>\r
141 </listitem>\r
142 </varlistentry>\r
143 <varlistentry>\r
144 <term>Pre-commit</term>\r
145 <listitem condition="pot">\r
146 <para>\r
147 <literal>PATH</literal>\r
148 <literal>MESSAGEFILE</literal>\r
149 <literal>CWD</literal>\r
150 </para>\r
151 </listitem>\r
152 </varlistentry>\r
153 <varlistentry>\r
154 <term>Post-commit</term>\r
155 <listitem condition="pot">\r
156 <para>\r
157 <literal>CWD</literal>\r
158 <literal>(commit was amend (true or false))</literal>\r
159 </para>\r
160 </listitem>\r
161 </varlistentry>\r
162 <varlistentry>\r
163 <term>Pre-push</term>\r
164 <listitem condition="pot">\r
165 <para>\r
166 <literal>ERROR</literal>\r
167 <literal>CWD</literal>\r
168 </para>\r
169 </listitem>\r
170 </varlistentry>\r
171 <varlistentry>\r
172 <term>Post-push</term>\r
173 <listitem condition="pot">\r
174 <para>\r
175 <literal>ERROR</literal>\r
176 <literal>CWD</literal>\r
177 </para>\r
178 </listitem>\r
179 </varlistentry>\r
180 <varlistentry>\r
181 <term>Pre-rebase</term>\r
182 <listitem condition="pot">\r
183 <para>\r
184 <literal>(upstream branch)</literal>\r
185 <literal>(rebased branch)</literal>\r
186 <literal>ERROR</literal>\r
187 <literal>CWD</literal>\r
188 </para>\r
189 </listitem>\r
190 </varlistentry>\r
191 </variablelist>\r
192 </para>\r
193 <para>\r
194 The meaning of each of these parameters is described here:\r
195 <variablelist>\r
196 <varlistentry>\r
197 <term condition="pot">PATH</term>\r
198 <listitem>\r
199 <para>\r
200 A path to a temporary file which contains all the\r
201 paths for which the operation was started in UTF-8 encoding.\r
202 Each path is on a separate line in the temp file.\r
203 </para>\r
204 </listitem>\r
205 </varlistentry>\r
206 <varlistentry>\r
207 <term condition="pot">MESSAGEFILE</term>\r
208 <listitem>\r
209 <para>\r
210 Path to a file containing the log message for\r
211 the commit. The file contains the text in UTF-8\r
212 encoding. After successful execution of the\r
213 start-commit and pre-commit hooks, the log message is read back,\r
214 giving the hook a chance to modify it.\r
215 </para>\r
216 </listitem>\r
217 </varlistentry>\r
218 <!--\r
219 <varlistentry>\r
220 <term condition="pot">REVISION</term>\r
221 <listitem>\r
222 <para>\r
223 The repository revision to which the update should\r
224 be done or after a commit completes.\r
225 </para>\r
226 </listitem>\r
227 </varlistentry>\r
228 -->\r
229 <varlistentry>\r
230 <term condition="pot">ERROR</term>\r
231 <listitem>\r
232 <para>\r
233 Path to a file containing the error message.\r
234 If there was no error, the file will be empty.\r
235 </para>\r
236 </listitem>\r
237 </varlistentry>\r
238 <varlistentry>\r
239 <term condition="pot">CWD</term>\r
240 <listitem>\r
241 <para>\r
242 The current working directory with which the script is run.\r
243 This is set to the working tree root.\r
244 </para>\r
245 </listitem>\r
246 </varlistentry>\r
247 </variablelist>\r
248 </para>\r
249 <para>\r
250 Note that although we have given these parameters names for convenience,\r
251 you do not have to refer to those names in the hook settings.\r
252 All parameters listed for a particular hook are always passed,\r
253 whether you want them or not ;-)\r
254 </para>\r
255 <para>\r
256 If you want the Git operation to hold off until the hook has completed,\r
257 check <guilabel>Wait for the script to finish</guilabel>.\r
258 </para>\r
259 <para>\r
260 Normally you will want to hide ugly DOS boxes when the script runs,\r
261 so <guilabel>Hide the script while running</guilabel> is checked by default.\r
262 </para>\r
263 <caution>\r
264 <para>\r
265 If you are executing a versioned file/script from the repository, please note that the file possibly\r
266 gets altered by third parties unnoticed (e.g. after pull or merge).\r
267 </para>\r
268 </caution>\r
269 <sect3 id="tgit-dug-settings-hooks-issuetracker">\r
270 <title>Issue Tracker Integration</title>\r
271 <?dbhh topicname="HIDD_SETTINGSBUGTRAQ"?>\r
272 <?dbhh topicname="HIDD_SETTINGSBUGTRAQADV"?>\r
273 <para>\r
274 TortoiseGit can use a COM plugin to query issue trackers when in the\r
275 commit dialog. The use of such plugins is described in\r
276 <xref linkend="tgit-dug-bugtracker-ref" />.\r
277 If your system administrator has provided you with a plugin, which\r
278 you have already installed and registered, this is the place to\r
279 specify how it integrates with your working tree.\r
280 </para>\r
281 <tip>\r
282 There is also a hierarchical git configuration to associate issue tracker plugin with your project,\r
283 rather than with to a specific directory path. Such settings are more portable.\r
284 See <xref linkend="tgit-dug-bugtracker"/> to configure these settings.\r
285 </tip>\r
286 <para>\r
287 <figure id="tgit-dug-settings-dia-issuetracker">\r
288 <title>The Settings Dialog, Issue Tracker Integration Page</title>\r
289 <graphic fileref="../images/SettingsIssueTrackerIntegration.png"/>\r
290 <graphic fileref="../images/SettingsIssueTracker.png"/>\r
291 </figure>\r
292 Click on <guibutton>Add...</guibutton> to use the plugin with\r
293 a particular working tree. Here you can specify the working tree\r
294 path, choose which plugin to use from a drop down list of all\r
295 registered issue tracker plugins, and any parameters to pass.\r
296 The parameters will be specific to the plugin, but might include\r
297 your user name on the issue tracker so that the plugin can\r
298 query for issues which are assigned to you.\r
299 </para>\r
300 </sect3>\r
301 <sect3 id="tgit-dug-settings-hooks-issuetracker-config">\r
302 <title>Config</title>\r
303 <para>\r
304 <figure id="tgit-dug-settings-hooks-issuetrack-config">\r
305 <title>The Settings Dialog, Issue Tracker Config</title>\r
306 <graphic fileref="../images/SettingsIssueTrackerConfig.png"/>\r
307 </figure>\r
308 See <xref linkend="tgit-dug-bugtracker"/> for a descriptions of the different options.\r
309 </para>\r
310 <important>\r
311 <para>\r
312 If you have problems entering/storing data please see <xref linkend="tgit-dug-settings-hierarchical"/>.\r
313 </para>\r
314 </important>\r
315 </sect3>\r
316 </sect2>\r