| blob | c69d4da49849b28c170530260e6edde0e16df3e3 |
1 <?xml version="1.0" encoding="UTF-8"?>\r
2 <!DOCTYPE appendix SYSTEM "../../dtd/dblite.dtd">\r
3 <appendix id="tsvn-automation">\r
4 <title>Automating TortoiseGit</title>\r
5 <simplesect>\r
6 <para>\r
7 Since all commands for TortoiseGit are controlled through command\r
8 line parameters, you can automate it with batch scripts or start specific\r
9 commands and dialogs from other programs (e.g. your favourite text editor).\r
10 </para>\r
11 <important>\r
12 <para>\r
13 Remember that TortoiseGit is a GUI client, and this automation guide\r
14 shows you how to make the TortoiseGit dialogs appear to collect user\r
15 input. If you want to write a script which requires no input, you should\r
16 use the official Git command line client instead.\r
17 </para>\r
18 </important>\r
19 </simplesect>\r
20 <!-- ================================================================= -->\r
21 <!-- ======================== SECTION 1 ============================== -->\r
22 <!-- ================================================================= -->\r
23 <sect1 id="tsvn-automation-basics">\r
24 <title>TortoiseGit Commands</title>\r
25 <indexterm>\r
26 <primary>automation</primary>\r
27 </indexterm>\r
28 <indexterm>\r
29 <primary>command line</primary>\r
30 </indexterm>\r
31 <para>\r
32 The TortoiseGit GUI program is called <literal>TortoiseProc.exe</literal>.\r
33 All commands are specified with the parameter <option>/command:abcd</option>\r
34 where <literal>abcd</literal> is the required command name. Most of these\r
35 commands need at least one path argument, which is given with \r
36 <option>/path:"some\path"</option>. In the following table the command \r
37 refers to the <option>/command:abcd</option> parameter and the path\r
38 refers to the <option>/path:"some\path"</option> parameter.\r
39 </para>\r
40 <para>\r
41 Since some of the commands can take a list of target paths (e.g. committing\r
42 several specific files) the <option>/path</option> parameter can take\r
43 several paths, separated by a <literal>*</literal> character.\r
44 </para>\r
45 <para>\r
46 TortoiseGit uses temporary files to pass multiple arguments between\r
47 the shell extension and the main program. From TortoiseGit 1.5.0 on and later,\r
48 <option>/notempfile</option> parameter is obsolete and there is no need\r
49 to add it anymore.\r
50 </para>\r
51 <para>\r
52 The progress dialog which is used for commits, updates and many more commands\r
53 usually stays open after the command has finished until the user presses\r
54 the <guibutton>OK</guibutton> button. This can be changed by checking\r
55 the corresponding option in the settings dialog. But using that setting\r
56 will close the progress dialog, no matter if you start the command\r
57 from your batch file or from the TortoiseGit context menu.\r
58 </para>\r
59 <para>\r
60 To specify a different location of the configuration file, use the parameter\r
61 <option>/configdir:"path\to\config\directory"</option>.\r
62 This will override the default path, including any registry setting.\r
63 </para>\r
64 <!--\r
65 <para>\r
66 To close the progress dialog at the end of a command automatically without\r
67 using the permanent setting you can pass the <option>/closeonend</option>\r
68 parameter.\r
69 <itemizedlist>\r
70 <listitem>\r
71 <para>\r
72 <option>/closeonend:0</option> don't close the dialog automatically\r
73 </para>\r
74 </listitem>\r
75 <listitem>\r
76 <para>\r
77 <option>/closeonend:1</option> auto close if no errors\r
78 </para>\r
79 </listitem>\r
80 <listitem>\r
81 <para>\r
82 <option>/closeonend:2</option> auto close if no errors and conflicts\r
83 </para>\r
84 </listitem>\r
85 <listitem>\r
86 <para>\r
87 <option>/closeonend:3</option> auto close if no errors, conflicts and merges\r
88 </para>\r
89 </listitem>\r
90 <listitem>\r
91 <para>\r
92 <option>/closeonend:4</option> auto close if no errors, conflicts and merges\r
93 for local operations\r
94 </para>\r
95 </listitem>\r
96 </itemizedlist>\r
97 </para>\r
98 -->\r
99 <para>\r
100 The table below lists all the commands which can be accessed\r
101 using the TortoiseProc.exe command line. As described above,\r
102 these should be used in the form <literal>/command:abcd</literal>.\r
103 In the table, the <literal>/command</literal> prefix is omitted\r
104 to save space.\r
105 </para>\r
106 <!--\r
107 ATTENTION ATTENTION ATTENTION ATTENTION ATTENTION ATTENTION ATTENTION ATTENTION\r
108 Don't touch these lines:\r
109 <entry condition="pot">:about</entry>\r
110 \r
111 The condition="pot" prevents the strings from being extracted into\r
112 the .pot file, so nobody translates them.\r
113 The colons in front of the command have to stay there to prevent these strings\r
114 from being translated if the po file "by chance" contains a matching translation.\r
115 -->\r
116 <para>\r
117 <table id="tsvn-automation-1-table">\r
118 <title>List of available commands and options</title>\r
119 <tgroup cols="2">\r
120 <colspec colnum="1" colwidth="2*"/>\r
121 <colspec colnum="2" colwidth="6*"/>\r
122 <thead>\r
123 <row>\r
124 <entry>Command</entry>\r
125 <entry>Description</entry>\r
126 </row>\r
127 </thead>\r
128 <tbody>\r
129 <row>\r
130 <entry condition="pot">:about</entry>\r
131 <entry>\r
132 Shows the about dialog. This is also shown if no\r
133 command is given.\r
134 </entry>\r
135 </row>\r
136 <row>\r
137 <entry condition="pot">:log</entry>\r
138 <entry>\r
139 Opens the log dialog. The <option>/path</option> specifies the\r
140 file or folder for which the log should be shown.\r
141 Additional options can be set:\r
142 <option>/rev:"SHA1"</option> highlights and automatically scrolls to the specified revision,\r
143 <option>/findstring:"filterstring"</option> fills in the filter text,\r
144 <option>/findtext</option> forces the filter to use text, not regex, or\r
145 <option>/findregex</option> forces the filter to use regex, not simple text search, and\r
146 <option>/findtype:X</option> with X being a number between 0 and 127. The numbers\r
147 are the sum of the following options:\r
148 <itemizedlist>\r
149 <listitem>\r
150 <para>\r
151 <option>/findtype:0</option> filter by everything\r
152 </para>\r
153 </listitem>\r
154 <listitem>\r
155 <para>\r
156 <option>/findtype:1</option> filter by messages\r
157 </para>\r
158 </listitem>\r
159 <listitem>\r
160 <para>\r
161 <option>/findtype:2</option> filter by path\r
162 </para>\r
163 </listitem>\r
164 <listitem>\r
165 <para>\r
166 <option>/findtype:4</option> filter by authors\r
167 </para>\r
168 </listitem>\r
169 <listitem>\r
170 <para>\r
171 <option>/findtype:8</option> filter by revisions\r
172 </para>\r
173 </listitem>\r
174 <listitem>\r
175 <para>\r
176 <option>/findtype:16</option> not used\r
177 </para>\r
178 </listitem>\r
179 <listitem>\r
180 <para>\r
181 <option>/findtype:32</option> filter by bug ID\r
182 </para>\r
183 </listitem>\r
184 <listitem>\r
185 <para>\r
186 <option>/findtype:64</option> filter by subject\r
187 </para>\r
188 </listitem>\r
189 </itemizedlist>\r
190 If <option>/outfile:path\to\file</option> is specified,\r
191 the selected revision is written to that file when\r
192 the log dialog is closed.\r
193 </entry>\r
194 </row>\r
195 <row>\r
196 <entry condition="pot">:clone</entry>\r
197 <entry>\r
198 Opens the clone dialog.\r
199 </entry>\r
200 </row>\r
201 <!--\r
202 <row>\r
203 <entry condition="pot">:import</entry>\r
204 <entry>\r
205 Opens the import dialog. The <option>/path</option>\r
206 specifies the directory with the data to import.\r
207 </entry>\r
208 </row>\r
209 -->\r
210 <!--\r
211 <row>\r
212 <entry condition="pot">:update</entry>\r
213 <entry>\r
214 Updates the working tree in <option>/path</option> to\r
215 HEAD. If the option <option>/rev</option> is given\r
216 then a dialog is shown to ask the user to which\r
217 revision the update should go. To avoid the dialog\r
218 specify a revision number <option>/rev:1234</option>.\r
219 Other options are <option>/nonrecursive</option> and\r
220 <option>/ignoreexternals</option>.\r
221 </entry>\r
222 </row>\r
223 -->\r
224 <row>\r
225 <entry condition="pot">:commit</entry>\r
226 <entry>\r
227 Opens the commit dialog. The <option>/path</option> specifies the\r
228 target directory or the list of files to commit.\r
229 You can also specify the <option>/logmsg</option> switch\r
230 to pass a predefined log message to the commit dialog.\r
231 Or, if you don't want to pass the log message on the\r
232 command line, use <option>/logmsgfile:path</option>,\r
233 where <option>path</option>\r
234 points to a file containing the log message.\r
235 To pre-fill the bug ID box (in case you've set up\r
236 integration with bug trackers properly), you can use\r
237 the <option>/bugid:"the bug id here"</option> to\r
238 do that.\r
239 </entry>\r
240 </row>\r
241 <row>\r
242 <entry condition="pot">:add</entry>\r
243 <entry>\r
244 Adds the files in <option>/path</option> to\r
245 version control.\r
246 </entry>\r
247 </row>\r
248 <row>\r
249 <entry condition="pot">:revert</entry>\r
250 <entry>\r
251 Reverts local modifications of a working tree.\r
252 The <option>/path</option> tells which items\r
253 to revert.\r
254 </entry>\r
255 </row>\r
256 <row>\r
257 <entry condition="pot">:cleanup</entry>\r
258 <entry>\r
259 Cleans up interrupted or aborted operations and\r
260 unlocks the working tree in <option>/path</option>.\r
261 </entry>\r
262 </row>\r
263 <row>\r
264 <entry condition="pot">:resolve</entry>\r
265 <entry>\r
266 Marks a conflicted file specified in \r
267 <option>/path</option> as resolved. If \r
268 <option>/noquestion</option> is given, then resolving\r
269 is done without asking the user first if it really\r
270 should be done.\r
271 </entry>\r
272 </row>\r
273 <row>\r
274 <entry condition="pot">:repocreate</entry>\r
275 <entry>\r
276 Creates a repository in <option>/path</option>\r
277 </entry>\r
278 </row>\r
279 <row>\r
280 <entry condition="pot">:switch</entry>\r
281 <entry>\r
282 Opens the switch dialog. The <option>/path</option> specifies the\r
283 target directory.\r
284 </entry>\r
285 </row>\r
286 <row>\r
287 <entry condition="pot">:export</entry>\r
288 <entry>\r
289 Exports the working tree in <option>/path</option>\r
290 to another directory. If the <option>/path</option>\r
291 points to an unversioned directory, a dialog will ask\r
292 for an URL to export to the directory in <option>/path</option>.\r
293 </entry>\r
294 </row>\r
295 <row>\r
296 <entry condition="pot">:merge</entry>\r
297 <entry>\r
298 Opens the merge dialog. The <option>/path</option> specifies the\r
299 target directory.\r
300 <!--\r
301 For merging a revision range, the following options are available:\r
302 <option>/fromurl:URL</option>,\r
303 <option>/revrange:string</option>.\r
304 For merging two repository trees, the following options are available:\r
305 <option>/fromurl:URL</option>,\r
306 <option>/tourl:URL</option>,\r
307 <option>/fromrev:xxx</option> and \r
308 <option>/torev:xxx</option>.\r
309 These pre-fill the relevant fields in the merge dialog.\r
310 -->\r
311 </entry>\r
312 </row>\r
313 <!--\r
314 <row>\r
315 <entry condition="pot">:copy</entry>\r
316 <entry>\r
317 Brings up the branch/tag dialog.\r
318 The <option>/path</option>\r
319 is the working tree to branch/tag from.\r
320 And the <option>/url</option> is the\r
321 target URL.\r
322 You can also specify the <option>/logmsg</option> switch\r
323 to pass a predefined log message to the branch/tag dialog.\r
324 Or, if you don't want to pass the log message on the\r
325 command line, use <option>/logmsgfile:path</option>,\r
326 where <option>path</option>\r
327 points to a file containing the log message.\r
328 </entry>\r
329 </row>\r
330 -->\r
331 <row>\r
332 <entry condition="pot">:settings</entry>\r
333 <entry>\r
334 Opens the settings dialog.\r
335 </entry>\r
336 </row>\r
337 <row>\r
338 <entry condition="pot">:remove</entry>\r
339 <entry>\r
340 Removes the file(s) in <option>/path</option> from\r
341 version control.\r
342 </entry>\r
343 </row>\r
344 <row>\r
345 <entry condition="pot">:rename</entry>\r
346 <entry>\r
347 Renames the file in <option>/path</option>. The new\r
348 name for the file is asked with a dialog.\r
349 To avoid the question about renaming similar files\r
350 in one step, pass <option>/noquestion</option>.\r
351 </entry>\r
352 </row>\r
353 <row>\r
354 <entry condition="pot">:diff</entry>\r
355 <entry>\r
356 Starts the external diff program specified in the\r
357 TortoiseGit settings. The <option>/path</option>\r
358 specifies the first file.\r
359 If the option <option>/path2</option>\r
360 is set, then the diff program is started with those\r
361 two files. If <option>/path2</option> is omitted,\r
362 then the diff is done between the file in\r
363 <option>/path</option> and its BASE.\r
364 To explicitly set the revision numbers use\r
365 <option>/startrev:xxx</option> and\r
366 <option>/endrev:xxx</option>.\r
367 If <option>/blame</option> is set and <option>/path2</option>\r
368 is not set, then the diff is done by first blaming \r
369 the files with the given revisions.\r
370 </entry>\r
371 </row>\r
372 <!--\r
373 <row>\r
374 <entry condition="pot">:showcompare</entry>\r
375 <entry>\r
376 <para>\r
377 Depending on the URLs and revisions to compare, this\r
378 either shows a unified diff (if the option <option>unified</option> is set), \r
379 a dialog with a list of files that have changed or if \r
380 the URLs point to files starts the diff viewer for \r
381 those two files.\r
382 </para>\r
383 <para>\r
384 The options <option>url1</option>, <option>url2</option>,\r
385 <option>revision1</option> and <option>revision2</option>\r
386 must be specified. The options <option>pegrevision</option>,\r
387 <option>ignoreancestry</option>, <option>blame</option> and\r
388 <option>unified</option> are optional.\r
389 </para>\r
390 </entry>\r
391 </row>\r
392 -->\r
393 <row>\r
394 <entry condition="pot">:conflicteditor</entry>\r
395 <entry>\r
396 Starts the conflict editor specified in the TortoiseGit\r
397 settings with the correct files for the conflicted\r
398 file in <option>/path</option>.\r
399 </entry>\r
400 </row>\r
401 <!--\r
402 <row>\r
403 <entry condition="pot">:relocate</entry>\r
404 <entry>\r
405 Opens the relocate dialog. The <option>/path</option>\r
406 specifies the working tree path to relocate.\r
407 </entry>\r
408 </row>\r
409 -->\r
410 <row>\r
411 <entry condition="pot">:help</entry>\r
412 <entry>\r
413 Opens the help file.\r
414 </entry>\r
415 </row>\r
416 <row>\r
417 <entry condition="pot">:repostatus</entry>\r
418 <entry>\r
419 Opens the check-for-modifications dialog. The <option>/path</option>\r
420 specifies the working tree directory.\r
421 </entry>\r
422 </row>\r
423 <row>\r
424 <entry condition="pot">:repobrowser</entry>\r
425 <entry>\r
426 Starts the repository browser dialog, pointing to\r
427 the working tree given in <option>/path</option>.\r
428 An additional option <option>/rev:xxx</option> can\r
429 be used to specify the revision which the repository\r
430 browser should show. If the <option>/rev:xxx</option>\r
431 is omitted, it defaults to HEAD.\r
432 </entry>\r
433 </row>\r
434 <row>\r
435 <entry condition="pot">:ignore</entry>\r
436 <entry>\r
437 Adds all targets in <option>/path</option> to the\r
438 ignore list, i.e. adds the <literal>svn:ignore</literal>\r
439 property to those files.\r
440 </entry>\r
441 </row>\r
442 <row>\r
443 <entry condition="pot">:blame</entry>\r
444 <entry>\r
445 <para>\r
446 Opens the blame dialog for the file specified \r
447 in <option>/path</option>.\r
448 </para>\r
449 <para>\r
450 If the option <option>/endrev</option> is set TortoiseGitBlame\r
451 ends at that revision.\r
452 </para>\r
453 <!--\r
454 <para>\r
455 If the option <option>/line:nnn</option> is set,\r
456 TortoiseBlame will open with the specified line\r
457 number showing.\r
458 </para>\r
459 -->\r
460 </entry>\r
461 </row>\r
462 <row>\r
463 <entry condition="pot">:cat</entry>\r
464 <entry>\r
465 Saves a file from an URL or working tree path given\r
466 in <option>/path</option> to the location given in\r
467 <option>/savepath:path</option>. The revision is\r
468 given in <option>/revision:xxx</option>. This can\r
469 be used to get a file with a specific revision.\r
470 </entry>\r
471 </row>\r
472 <!--\r
473 <row>\r
474 <entry condition="pot">:createpatch</entry>\r
475 <entry>\r
476 Creates a patch file for the path given in\r
477 <option>/path</option>.\r
478 </entry>\r
479 </row>\r
480 -->\r
481 <row>\r
482 <entry condition="pot">:pull</entry>\r
483 <entry>\r
484 Pull change from remote repository\r
485 <option>/path</option>.\r
486 </entry>\r
487 </row>\r
488 <row>\r
489 <entry condition="pot">:push</entry>\r
490 <entry>\r
491 Push change to remote repository\r
492 <option>/path</option>.\r
493 </entry>\r
494 </row>\r
495 <row>\r
496 <entry condition="pot">:rebase</entry>\r
497 <entry>\r
498 Rebase commits to special commit.\r
499 <option>/path</option>.\r
500 </entry>\r
501 </row>\r
502 <row>\r
503 <entry condition="pot">:stashsave</entry>\r
504 <entry>\r
505 <option>/path</option>.\r
506 </entry>\r
507 </row>\r
508 <row>\r
509 <entry condition="pot">:stashapply</entry>\r
510 <entry>\r
511 <option>/path</option>.\r
512 </entry>\r
513 </row>\r
514 <row>\r
515 <entry condition="pot">:stashpop</entry>\r
516 <entry>\r
517 <option>/path</option>.\r
518 </entry>\r
519 </row>\r
520 <row>\r
521 <entry condition="pot">:subadd</entry>\r
522 <entry>\r
523 <option>/path</option>.\r
524 </entry>\r
525 </row>\r
526 <row>\r
527 <entry condition="pot">:subupdate</entry>\r
528 <entry>\r
529 <option>/path</option>.\r
530 </entry>\r
531 </row>\r
532 <row>\r
533 <entry condition="pot">:subsync</entry>\r
534 <entry>\r
535 <option>/path</option>.\r
536 </entry>\r
537 </row>\r
538 <row>\r
539 <entry condition="pot">:reflog</entry>\r
540 <entry>\r
541 <option>/path</option>.\r
542 </entry>\r
543 </row>\r
544 <row>\r
545 <entry condition="pot">:refbrowse</entry>\r
546 <entry>\r
547 <option>/path</option>.\r
548 </entry>\r
549 </row>\r
550 <!--\r
551 <row>\r
552 <entry condition="pot">:revisiongraph</entry>\r
553 <entry>\r
554 Shows the revision graph for the path given in\r
555 <option>/path</option>.\r
556 </entry>\r
557 </row>\r
558 -->\r
559 <!--\r
560 <row>\r
561 <entry condition="pot">:rebuildiconcache</entry>\r
562 <entry>\r
563 Rebuilds the windows icon cache. Only use this in\r
564 case the windows icons are corrupted. A side effect\r
565 of this (which can't be avoided) is that the icons\r
566 on the desktop get rearranged.\r
567 To suppress the message box, pass <option>/noquestion</option>.\r
568 </entry>\r
569 </row>\r
570 -->\r
571 </tbody>\r
572 </tgroup>\r
573 </table>\r
574 </para>\r
575 <para>\r
576 Examples (which should be entered on one line):\r
577 <screen>\r
578 TortoiseProc.exe /command:commit\r
579 /path:"c:\svn_wc\file1.txt*c:\svn_wc\file2.txt"\r
580 /logmsg:"test log message" /closeonend:0\r
581 \r
582 TortoiseProc.exe /command:update /path:"c:\svn_wc\" /closeonend:0\r
583 \r
584 TortoiseProc.exe /command:log /path:"c:\svn_wc\file1.txt"\r
585 /startrev:50 /endrev:60 /closeonend:0\r
586 </screen>\r
587 </para>\r
588 </sect1>\r
589 \r
590 <sect1 id="tsvn-automation-idiff">\r
591 <title>TortoiseIDiff Commands</title>\r
592 <indexterm>\r
593 <primary>automation</primary>\r
594 </indexterm>\r
595 <indexterm>\r
596 <primary>command line</primary>\r
597 </indexterm>\r
598 <para>\r
599 The image diff tool has a few command line options which you\r
600 can use to control how the tool is started.\r
601 The program is called <literal>TortoiseIDiff.exe</literal>.\r
602 </para>\r
603 <para>\r
604 The table below lists all the options which can be passed\r
605 to the image diff tool on the command line.\r
606 </para>\r
607 <!--\r
608 ATTENTION ATTENTION ATTENTION ATTENTION ATTENTION ATTENTION ATTENTION ATTENTION\r
609 Don't touch these lines:\r
610 <entry condition="pot">:about</entry>\r
611 \r
612 The condition="pot" prevents the strings from being extracted into\r
613 the .pot file, so nobody translates them.\r
614 The colons in front of the command have to stay there to prevent these strings\r
615 from being translated if the po file "by chance" contains a matching translation.\r
616 -->\r
617 <para>\r
618 <table id="tsvn-automation-idiff-1-table">\r
619 <title>List of available options</title>\r
620 <tgroup cols="2">\r
621 <colspec colnum="1" colwidth="2*"/>\r
622 <colspec colnum="2" colwidth="6*"/>\r
623 <thead>\r
624 <row>\r
625 <entry>Option</entry>\r
626 <entry>Description</entry>\r
627 </row>\r
628 </thead>\r
629 <tbody>\r
630 <row>\r
631 <entry condition="pot">:left</entry>\r
632 <entry>\r
633 Path to the file shown on the left.\r
634 </entry>\r
635 </row>\r
636 <row>\r
637 <entry condition="pot">:lefttitle</entry>\r
638 <entry>\r
639 A title string. This string is used in the image view\r
640 title instead of the full path to the image file.\r
641 </entry>\r
642 </row>\r
643 <row>\r
644 <entry condition="pot">:right</entry>\r
645 <entry>\r
646 Path to the file shown on the right.\r
647 </entry>\r
648 </row>\r
649 <row>\r
650 <entry condition="pot">:righttitle</entry>\r
651 <entry>\r
652 A title string. This string is used in the image view\r
653 title instead of the full path to the image file.\r
654 </entry>\r
655 </row>\r
656 <row>\r
657 <entry condition="pot">:overlay</entry>\r
658 <entry>\r
659 If specified, the image diff tool switches\r
660 to the overlay mode (alpha blend).\r
661 </entry>\r
662 </row>\r
663 <row>\r
664 <entry condition="pot">:fit</entry>\r
665 <entry>\r
666 If specified, the image diff tool fits both\r
667 images together.\r
668 </entry>\r
669 </row>\r
670 <row>\r
671 <entry condition="pot">:showinfo</entry>\r
672 <entry>\r
673 Shows the image info box.\r
674 </entry>\r
675 </row>\r
676 </tbody>\r
677 </tgroup>\r
678 </table>\r
679 </para>\r
680 <para>\r
681 Example (which should be entered on one line):\r
682 <screen>\r
683 TortoiseIDiff.exe /left:"c:\images\img1.jpg" /lefttitle:"image 1"\r
684 /right:"c:\images\img2.jpg" /righttitle:"image 2"\r
685 /fit /overlay\r
686 </screen>\r
687 </para>\r
688 </sect1>\r
689 \r
690 </appendix>\r