1 <?xml version="1.0" encoding="UTF-8"?>
\r
2 <!DOCTYPE appendix SYSTEM "../../dtd/dblite.dtd">
\r
3 <appendix id="tgit-automation">
\r
4 <title>Automating TortoiseGit</title>
\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
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
20 <!-- ================================================================= -->
\r
21 <!-- ======================== SECTION 1 ============================== -->
\r
22 <!-- ================================================================= -->
\r
23 <sect1 id="tgit-automation-basics">
\r
24 <title>TortoiseGit Commands</title>
\r
26 <primary>automation</primary>
\r
29 <primary>command line</primary>
\r
32 The TortoiseGit GUI program is called <literal>TortoiseGitProc.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
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
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
52 The progress dialog which is used for commits, updates and many more git.exe 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 in the settings dialog.
\r
55 You may use <option>/closeonend</option> parameter to override the this setting
\r
56 from your batch file.
\r
59 To close the (git.exe) progress dialog at the end of a command automatically without
\r
60 using the permanent setting you can pass the <option>/closeonend</option>
\r
65 <option>/closeonend:0</option> Close manually
\r
70 <option>/closeonend:1</option> Auto-close if no further options are available
\r
75 <option>/closeonend:2</option> Auto-close if no errors
\r
81 <option>/closeonend:3</option> auto close if no errors, conflicts and merges
\r
86 <option>/closeonend:4</option> auto close if no errors, conflicts and merges
\r
87 for local operations
\r
94 The table below lists all the commands which can be accessed
\r
95 using the TortoiseGitProc.exe command line. As described above,
\r
96 these should be used in the form <literal>/command:abcd</literal>.
\r
97 In the table, the <literal>/command</literal> prefix is omitted
\r
101 ATTENTION ATTENTION ATTENTION ATTENTION ATTENTION ATTENTION ATTENTION ATTENTION
\r
102 Don't touch these lines:
\r
103 <entry condition="pot">:about</entry>
\r
105 The condition="pot" prevents the strings from being extracted into
\r
106 the .pot file, so nobody translates them.
\r
107 The colons in front of the command have to stay there to prevent these strings
\r
108 from being translated if the po file "by chance" contains a matching translation.
\r
111 <table id="tgit-automation-1-table">
\r
112 <title>List of available commands and options</title>
\r
114 <colspec colnum="1" colwidth="2*"/>
\r
115 <colspec colnum="2" colwidth="6*"/>
\r
118 <entry>Command</entry>
\r
119 <entry>Description</entry>
\r
124 <entry condition="pot">:about</entry>
\r
126 Shows the about dialog. This is also shown if no
\r
131 <entry condition="pot">:bisect</entry>
\r
133 Allows to control the <link linkend="tgit-dug-bisect">bisect logic</link> of TortoiseGit.
\r
134 Use the <option>/start</option> parameter to start a bisect you can specify <option>/good:REF</option> and <option>/bad:REF</option> here).
\r
135 When bisect is active, you can use <option>/good</option>, <option>/bad</option> and <option>/reset</option> to control the bisect process.
\r
139 <entry condition="pot">:fetch</entry>
\r
141 Opens the <link linkend="tgit-dug-pull">fetch dialog</link>.
\r
142 Use the <option>/remote</option> parameter to control the remote which should be pre-selected.
\r
146 <entry condition="pot">:log</entry>
\r
148 Opens the <link linkend="tgit-dug-showlog">log dialog</link>. The <option>/path</option> specifies the
\r
149 file or folder for which the log should be shown.
\r
150 Additional options can be set:
\r
151 <option>/rev:"SHA1"</option> highlights and automatically scrolls to the specified revision,
\r
152 <option>/endrev:"SHA1/branch"</option>, shows the log of the specified revision,
\r
153 <option>/startrev:"SHA1/branch"</option> (only in combination with endrev), shows the log of the revision range startrev..endrev,
\r
154 <option>/range:"gitrevision"</option>, shows the log of the entered gitrevision (e.g. "branch1...branch2"),
\r
155 <option>/limit:"N SCALE"</option>, SCALE could be "Commit", "Year", "Month", "Week";
\r
156 it shows last N commit(s), last N year(s), last N month(s), last N week(s).
\r
157 Use <option>/limit:0</option> to disable any default limit.
\r
158 <option>/findstring:"filterstring"</option> fills in the filter text,
\r
159 <option>/findtext</option> forces the filter to use text, not regex, or
\r
160 <option>/findregex</option> forces the filter to use regex, not simple text search, and
\r
161 <option>/findtype:X</option> with X being a number between 0 and 127. The numbers
\r
162 are the sum of the following options:
\r
166 <option>/findtype:0</option> filter by everything
\r
171 <option>/findtype:1</option> filter by messages
\r
176 <option>/findtype:2</option> filter by path
\r
181 <option>/findtype:4</option> filter by authors
\r
186 <option>/findtype:8</option> filter by revisions
\r
191 <option>/findtype:16</option> not used
\r
196 <option>/findtype:32</option> filter by bug ID
\r
201 <option>/findtype:64</option> filter by subject
\r
205 If <option>/outfile:path\to\file</option> is specified,
\r
206 the selected revision is written to that file when
\r
207 the log dialog is closed.
\r
211 <entry condition="pot">:clone</entry>
\r
213 Opens the <link linkend="tgit-dug-clone">clone dialog</link>.
\r
214 The <option>/url</option> specifies the URL to clone from.
\r
215 The <option>/path</option> specifies the target directory
\r
217 If <option>/exactpath</option> is not specfied, the
\r
218 repository name (without trailing .git) will be appended to
\r
219 target directory. This is the default behaviour.
\r
220 If <option>/exactpath</option> is specfied, the
\r
221 exact <option>/path</option> is considered the target directory,
\r
222 without appending repository name to it.
\r
227 <entry condition="pot">:import</entry>
\r
229 Opens the import dialog. The <option>/path</option>
\r
230 specifies the directory with the data to import.
\r
236 <entry condition="pot">:update</entry>
\r
238 Updates the working tree in <option>/path</option> to
\r
239 HEAD. If the option <option>/rev</option> is given
\r
240 then a dialog is shown to ask the user to which
\r
241 revision the update should go. To avoid the dialog
\r
242 specify a revision number <option>/rev:1234</option>.
\r
243 Other options are <option>/nonrecursive</option> and
\r
244 <option>/ignoreexternals</option>.
\r
249 <entry condition="pot">:commit</entry>
\r
251 Opens the <link linkend="tgit-dug-commit">commit dialog</link>. The <option>/path</option> specifies the
\r
252 target directory or the list of files to commit.
\r
253 You can also specify the <option>/logmsg</option> switch
\r
254 to pass a predefined log message to the commit dialog.
\r
255 Or, if you don't want to pass the log message on the
\r
256 command line, use <option>/logmsgfile:path</option>,
\r
257 where <option>path</option>
\r
258 points to a file containing the log message.
\r
259 To pre-fill the bug ID box (in case you've set up
\r
260 integration with bug trackers properly), you can use
\r
261 the <option>/bugid:"the bug id here"</option> to
\r
266 <entry condition="pot">:add</entry>
\r
268 Adds the files in <option>/path</option> to
\r
273 <entry condition="pot">:revert</entry>
\r
275 Reverts local modifications of a working tree.
\r
276 The <option>/path</option> tells which items
\r
281 <entry condition="pot">:cleanup</entry>
\r
283 <link linkend="tgit-dug-cleanup">Cleans up the working tree</link> in <option>/path</option>.
\r
287 <entry condition="pot">:resolve</entry>
\r
289 Marks a conflicted file specified in
\r
290 <option>/path</option> as resolved. If
\r
291 <option>/noquestion</option> is given, then resolving
\r
292 is done without asking the user first if it really
\r
297 <entry condition="pot">:repocreate</entry>
\r
299 <link linkend="tgit-dug-create">Creates a repository</link> in <option>/path</option>
\r
303 <entry condition="pot">:switch</entry>
\r
305 Opens the <link linkend="tgit-dug-checkout">switch dialog</link>. The <option>/path</option> specifies the
\r
310 <entry condition="pot">:export</entry>
\r
312 <link linkend="tgit-dug-export">Exports a revision</link> of the repository in <option>/path</option>
\r
317 <entry condition="pot">:merge</entry>
\r
319 Opens the <link linkend="tgit-dug-merge">merge dialog</link>. The <option>/path</option> specifies the
\r
325 <entry condition="pot">:copy</entry>
\r
327 Brings up the branch/tag dialog.
\r
328 The <option>/path</option>
\r
329 is the working tree to branch/tag from.
\r
330 And the <option>/url</option> is the
\r
332 You can also specify the <option>/logmsg</option> switch
\r
333 to pass a predefined log message to the branch/tag dialog.
\r
334 Or, if you don't want to pass the log message on the
\r
335 command line, use <option>/logmsgfile:path</option>,
\r
336 where <option>path</option>
\r
337 points to a file containing the log message.
\r
342 <entry condition="pot">:settings</entry>
\r
344 Opens the <link linkend="tgit-dug-settings">settings dialog</link>.
\r
348 <entry condition="pot">:remove</entry>
\r
350 Removes the file(s) in <option>/path</option> from
\r
355 <entry condition="pot">:rename</entry>
\r
357 Renames the file in <option>/path</option>. The new
\r
358 name for the file is asked with a dialog.
\r
360 To avoid the question about renaming similar files
\r
361 in one step, pass <option>/noquestion</option>.
\r
366 <entry condition="pot">:diff</entry>
\r
368 Starts the external diff program specified in the
\r
369 TortoiseGit settings. The <option>/path</option>
\r
370 specifies the first file.
\r
371 If the option <option>/path2</option>
\r
372 is set, then the diff program is started with those
\r
373 two files. If <option>/path2</option> is omitted,
\r
374 then the diff is done between the file in
\r
375 <option>/path</option> and its BASE.
\r
376 To explicitly set the revision use
\r
377 <option>/startrev:xxx</option> and
\r
378 <option>/endrev:xxx</option>.
\r
379 Add <option>/unified</option> to get a unified diff.
\r
380 Add <option>/line:NN</option> to get scroll to the mentioned line.
\r
382 If <option>/blame</option> is set and <option>/path2</option>
\r
383 is not set, then the diff is done by first blaming
\r
384 the files with the given revisions.
\r
389 <entry condition="pot">:showcompare</entry>
\r
392 Depending on revisions to compare and the path, this
\r
393 either shows a unified diff (if the option <option>unified</option> is set),
\r
394 a dialog with a list of files that have changed (filtered by a possibly entered subpath) or if
\r
395 the path point to a file starts the diff viewer for
\r
396 those the file in the different revisions.
\r
397 Use <option>/revision1:xxx</option> and <option>/revision2:xxx</option> to specify the revisions to compare.
\r
402 <entry condition="pot">:conflicteditor</entry>
\r
404 Starts the conflict editor specified in the TortoiseGit
\r
405 settings with the correct files for the conflicted
\r
406 file in <option>/path</option>.
\r
410 <entry condition="pot">:help</entry>
\r
412 Opens the help file.
\r
416 <entry condition="pot">:repostatus</entry>
\r
418 Opens the check-for-modifications dialog. The <option>/path</option>
\r
419 specifies the working tree directory.
\r
423 <entry condition="pot">:repobrowser</entry>
\r
425 Starts the <link linkend="tgit-dug-repobrowser">repository browser dialog</link>, pointing to
\r
426 the working tree given in <option>/path</option>.
\r
427 An additional option <option>/rev:xxx</option> can
\r
428 be used to specify the revision which the repository
\r
429 browser should show. If the <option>/rev:xxx</option>
\r
430 is omitted, it defaults to HEAD.
\r
434 <entry condition="pot">:ignore</entry>
\r
436 Adds all targets in <option>/path</option> to the
\r
437 ignore list, i.e. adds file(s) to the <literal>.gitignore</literal>
\r
442 <entry condition="pot">:blame</entry>
\r
445 Opens <link linkend="tgit-dug-blame">TortoiseGitBlame</link> for the file specified
\r
446 in <option>/path</option>.
\r
449 If the option <option>/endrev</option> is set TortoiseGitBlame
\r
450 ends at that revision.
\r
453 If the option <option>/line:nnn</option> is set,
\r
454 TortoiseGitBlame will open with the specified line
\r
460 <entry condition="pot">:cat</entry>
\r
462 Saves a file from an URL or working tree path given
\r
463 in <option>/path</option> to the location given in
\r
464 <option>/savepath:path</option>. The revision is
\r
465 given in <option>/revision:xxx</option>. This can
\r
466 be used to get a file with a specific revision.
\r
471 <entry condition="pot">:createpatch</entry>
\r
473 Creates a patch file for the path given in
\r
474 <option>/path</option>.
\r
479 <entry condition="pot">:pull</entry>
\r
481 Opens the <link linkend="tgit-dug-pull">pull dialog</link> in the working tree located in
\r
482 <option>/path</option>.
\r
486 <entry condition="pot">:push</entry>
\r
488 Opens the <link linkend="tgit-dug-push">push dialog</link> in the working tree located in
\r
489 <option>/path</option>.
\r
493 <entry condition="pot">:rebase</entry>
\r
495 Opens the <link linkend="tgit-dug-rebase">rebase dialog</link> for the working tree located in
\r
496 <option>/path</option>.
\r
500 <entry condition="pot">:stashsave</entry>
\r
502 Opens the <link linkend="tgit-dug-stash">stash save dialog</link> for the working tree located in
\r
503 <option>/path</option>. A prefilled mesage can be achieved by using the <option>/msg</option> parameter.
\r
507 <entry condition="pot">:stashapply</entry>
\r
509 Applies to latest stash to the working tree located in
\r
510 <option>/path</option>.
\r
514 <entry condition="pot">:stashpop</entry>
\r
516 Applies to latest stash to the working tree located in
\r
517 <option>/path</option> and drops the latest stash entry.
\r
521 <entry condition="pot">:subadd</entry>
\r
523 Opens the <link linkend="tgit-dug-submodules">submodule add dialog</link>.
\r
524 <option>/path</option>.
\r
528 <entry condition="pot">:subupdate</entry>
\r
530 Opens the <link linkend="tgit-dug-submodules">submodule update dialog</link> for and filters the submodules regarding the folder
\r
531 <option>/path</option>.
\r
535 <entry condition="pot">:subsync</entry>
\r
537 Syncs the submodule information for the working tree located in
\r
538 <option>/path</option>.
\r
542 <entry condition="pot">:reflog</entry>
\r
544 Opens the reflog dialog for the repository located in <option>/path</option>.
\r
548 <entry condition="pot">:refbrowse</entry>
\r
550 Opens the <link linkend="tgit-dug-browse-ref">browse references dialog</link> for the repository located in
\r
551 <option>/path</option>.
\r
555 <entry condition="pot">:updatecheck</entry>
\r
557 <option>/visible</option>: Shows the dialog even if no newer TortoiseGit version is available.
\r
558 <option>/force</option>: Shows file list for download even if the latest TortoiseGit has been installed.
\r
562 <entry condition="pot">:revisiongraph</entry>
\r
564 Shows the <link linkend="tgit-dug-revgraph">revision graph</link> for the repository given in
\r
565 <option>/path</option>.
\r
567 To create an image file of the revision graph for a specific path, but
\r
568 without showing the graph window, pass <option>/output:path</option>
\r
569 with the path to the output file. The output file must have
\r
570 an extension that the revision graph can actually
\r
571 export to. These are:
\r
572 <literal>.svg</literal>,
\r
573 <literal>.wmf</literal>,
\r
574 <literal>.gv</literal>,
\r
575 <literal>.png</literal>,
\r
576 <literal>.jpg</literal>,
\r
577 <literal>.bmp</literal> and
\r
578 <literal>.gif</literal>.
\r
583 <entry condition="pot">:daemon</entry>
\r
585 Launches the <link linkend="tgit-dug-daemon">Git Daemon</link> for the repository given in
\r
586 <option>/path</option>.
\r
590 <entry condition="pot">:pgpfp</entry>
\r
592 Prints the TortoiseGit Release Signing Key fingerprint. If you trust the current TortoiseGit installation, this can be used as a trust anchor to future releases.
\r
597 <entry condition="pot">:rebuildiconcache</entry>
\r
599 Rebuilds the windows icon cache. Only use this in
\r
600 case the windows icons are corrupted. A side effect
\r
601 of this (which can't be avoided) is that the icons
\r
602 on the desktop get rearranged.
\r
603 To suppress the message box, pass <option>/noquestion</option>.
\r
608 <entry condition="pot">:tag</entry>
\r
610 Opens the <link linkend="tgit-dug-branchtag">Create Tag dialog</link>. The <option>/path</option> specifies the
\r
612 Additional options can be set:
\r
613 <option>/rev:"ref"</option> tags on the specified ref/commit,
\r
614 <option>/name:"tag_name"</option> fills the Tag name in Create Tag dialog.
\r
622 Examples (which should be entered on one line):
\r
624 TortoiseGitProc.exe /command:commit
\r
625 /path:"d:\git_wc\file1.txt*c:\git_wc\file2.txt"
\r
626 /logmsg:"test log message" /closeonend:2
\r
628 TortoiseGitProc.exe /command:log /path:"c:\git_wc\file1.txt"
\r
629 /startrev:master~100 /endrev:master
\r
635 When calling TortoiseGit from within the msys environment, you can also use more *nix style command line parameters:
\r
637 TortoiseGitProc.exe -command commit
\r
638 -path "d:\git_wc\file1.txt*c:\git_wc\file2.txt"
\r
639 -logmsg "test log message" -closeonend 2
\r
646 <sect1 id="tgit-automation-idiff">
\r
647 <title>TortoiseGitIDiff Commands</title>
\r
649 <primary>automation</primary>
\r
652 <primary>command line</primary>
\r
655 The image diff tool has a few command line options which you
\r
656 can use to control how the tool is started.
\r
657 The program is called <literal>TortoiseGitIDiff.exe</literal>.
\r
660 The table below lists all the options which can be passed
\r
661 to the image diff tool on the command line.
\r
664 ATTENTION ATTENTION ATTENTION ATTENTION ATTENTION ATTENTION ATTENTION ATTENTION
\r
665 Don't touch these lines:
\r
666 <entry condition="pot">:about</entry>
\r
668 The condition="pot" prevents the strings from being extracted into
\r
669 the .pot file, so nobody translates them.
\r
670 The colons in front of the command have to stay there to prevent these strings
\r
671 from being translated if the po file "by chance" contains a matching translation.
\r
674 <table id="tgit-automation-idiff-1-table">
\r
675 <title>List of available options</title>
\r
677 <colspec colnum="1" colwidth="2*"/>
\r
678 <colspec colnum="2" colwidth="6*"/>
\r
681 <entry>Option</entry>
\r
682 <entry>Description</entry>
\r
687 <entry condition="pot">:left</entry>
\r
689 Path to the file shown on the left.
\r
693 <entry condition="pot">:lefttitle</entry>
\r
695 A title string. This string is used in the image view
\r
696 title instead of the full path to the image file.
\r
700 <entry condition="pot">:right</entry>
\r
702 Path to the file shown on the right.
\r
706 <entry condition="pot">:righttitle</entry>
\r
708 A title string. This string is used in the image view
\r
709 title instead of the full path to the image file.
\r
713 <entry condition="pot">:overlay</entry>
\r
715 If specified, the image diff tool switches
\r
716 to the overlay mode (alpha blend).
\r
720 <entry condition="pot">:fit</entry>
\r
722 If specified, the image diff tool fits both
\r
727 <entry condition="pot">:showinfo</entry>
\r
729 Shows the image info box.
\r
737 Example (which should be entered on one line):
\r
739 TortoiseGitIDiff.exe /left:"c:\images\img1.jpg" /lefttitle:"image 1"
\r
740 /right:"c:\images\img2.jpg" /righttitle:"image 2"
\r