Docs/Manual/EN/Command_line.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <article id="Command_line">
   3   <title>Command line<indexterm>
   4       <primary>command line</primary>
   5     </indexterm><indexterm>
   6       <primary>WinMerge command line</primary>
   7
   8       <see>command line</see>
   9     </indexterm></title>
  10
  11   <para>The WinMerge command line accepts several parameters in addition to the
  12   paths to compare. Most of these parameters are intended for using WinMerge as
  13   an external compare application or starting a compare operation from a batch
  14   file.</para>
  15
  16   <para>Use one of these formats for the WinMerge command:</para>
  17
  18   <para><cmdsynopsis sepchar=" ">
  19       <command>WinMergeU</command>
  20
  21       <arg choice="opt" rep="norepeat"><option>/?</option></arg>
  22     </cmdsynopsis></para>
  23
  24   <para><cmdsynopsis sepchar=" ">
  25       <command>WinMergeU</command>
  26
  27       <arg choice="opt" rep="norepeat"><option>/r</option></arg>
  28
  29       <arg choice="opt" rep="norepeat"><option>/e</option></arg>
  30
  31       <arg choice="opt" rep="norepeat"><option>/f</option>
  32       <replaceable>filter</replaceable></arg>
  33
  34       <arg choice="opt" rep="norepeat"><option>/m</option>
  35       <replaceable>compare-method</replaceable></arg>
  36
  37       <arg><option>/x</option></arg>
  38
  39       <arg><option>/xq</option></arg>
  40
  41       <arg><option>/s</option></arg>
  42
  43       <arg><option>/sw</option></arg>
  44
  45       <arg><option>/s-</option></arg>
  46
  47       <arg choice="opt" rep="norepeat"><option>/ul</option></arg>
  48
  49       <arg choice="opt" rep="norepeat"><option>/um</option></arg>
  50
  51       <arg choice="opt" rep="norepeat"><option>/ur</option></arg>
  52
  53       <arg choice="opt" rep="norepeat"><option>/u</option></arg>
  54
  55       <arg choice="opt" rep="norepeat"><option>/wl</option></arg>
  56
  57       <arg choice="opt" rep="norepeat"><option>/wm</option></arg>
  58
  59       <arg choice="opt" rep="norepeat"><option>/wr</option></arg>
  60
  61       <arg choice="opt" rep="norepeat"><option>/self-compare</option></arg>
  62
  63       <arg><option>/minimize</option></arg>
  64
  65       <arg><option>/maximize</option></arg>
  66
  67       <arg choice="opt" rep="norepeat"><option>/fl</option></arg>
  68
  69       <arg choice="opt" rep="norepeat"><option>/fm</option></arg>
  70
  71       <arg choice="opt" rep="norepeat"><option>/fr</option></arg>
  72
  73       <arg choice="opt" rep="norepeat"><option>/dl</option>
  74       <replaceable>leftdesc</replaceable></arg>
  75
  76       <arg choice="opt" rep="norepeat"><option>/dm</option>
  77       <replaceable>middledesc</replaceable></arg>
  78
  79       <arg choice="opt" rep="norepeat"><option>/dr</option>
  80       <replaceable>rightdesc</replaceable></arg>
  81
  82       <arg choice="plain"
  83       rep="norepeat"><replaceable>leftpath</replaceable></arg>
  84
  85       <arg cchoice="opt"
  86       rep="norepeat"><replaceable>middlepath</replaceable></arg>
  87
  88       <arg choice="plain"
  89       rep="norepeat"><replaceable>rightpath</replaceable></arg>
  90
  91       <arg choice="opt"
  92       rep="norepeat"><option>/o</option>
  93       <replaceable>outputpath</replaceable></arg>
  94
  95       <arg choice="opt" rep="norepeat"><option>/al</option></arg>
  96
  97       <arg choice="opt" rep="norepeat"><option>/am</option></arg>
  98
  99       <arg choice="opt" rep="norepeat"><option>/ar</option></arg>
 100
 101     </cmdsynopsis></para>
 102
 103   <cmdsynopsis sepchar=" ">
 104     <command>WinMergeU</command>
 105
 106     <arg choice="plain"
 107     rep="norepeat"><replaceable>conflictfile</replaceable></arg>
 108   </cmdsynopsis>
 109
 110   <para>Entering the command with no parameters or pathnames simply opens the
 111   WinMerge window. Parameters are prefixed with either a forward slash (
 112   <literal>/</literal> ) or dash ( <literal>-</literal> ) character. Pathnames
 113   have no prefix character.</para>
 114
 115   <variablelist>
 116     <varlistentry>
 117       <term><option>/?</option></term>
 118       <listitem>
 119         <para>Opens WinMerge Help at this topic.</para>
 120       </listitem>
 121     </varlistentry>
 122
 123     <varlistentry>
 124       <indexterm>
 125         <primary>recursive folder compare</primary>
 126       </indexterm>
 127       <term><option>/r</option></term>
 128       <listitem>
 129         <para>Compares all files in all subfolders (recursive
 130         compare). Unique folders (occurring only on one side) are listed in the
 131         compare result as separate items. Note that including subfolders can
 132         increase compare time significantly. Without this parameter, WinMerge
 133         lists only files and subfolders at the top level of the two target
 134         folders. It does not compare the subfolders.</para>
 135       </listitem>
 136     </varlistentry>
 137
 138     <varlistentry>
 139       <indexterm>
 140         <primary>WinMerge window</primary>
 141         <secondary>closing</secondary>
 142       </indexterm>
 143
 144       <term><option>/e</option></term>
 145       <listitem>
 146         <para>Enables you to close WinMerge with a single
 147         <keycap>Esc</keycap> key press. This is useful when you use WinMerge as an
 148         external compare application: you can close WinMerge quickly, like a
 149         dialog. Without this parameter, you might have to press
 150         <keycap>Esc</keycap> multiple times to close all its windows.</para>
 151       </listitem>
 152     </varlistentry>
 153
 154     <varlistentry>
 155       <indexterm>
 156         <primary>filters</primary>
 157         <secondary>applying in command line</secondary>
 158       </indexterm>
 159
 160       <term><option>/f</option></term>
 161       <listitem>
 162         <para>Applies a specified filter to restrict the
 163         comparison. The filter can be a filemask like <filename><userinput>*.h
 164         *.cpp</userinput></filename>, or the name of a file filter like
 165         <userinput>XML/HTML Devel</userinput>. Add quotation marks around a filter
 166         mask or name that contains spaces.</para>
 167       </listitem>
 168     </varlistentry>
 169
 170     <varlistentry>
 171       <indexterm>
 172         <primary>compare method</primary>
 173         <secondary>applying in command line</secondary>
 174       </indexterm>
 175
 176       <term><option>/m</option></term>
 177       <listitem>
 178         <para>Sets the compare method to use for the comparison.
 179         This can be one of the keywords <userinput>Full</userinput>,
 180         <userinput>Quick</userinput>, <userinput>Binary</userinput>,
 181         <userinput>Date</userinput>, <userinput>SizeDate</userinput>,
 182         <userinput>Size</userinput>.</para>
 183       </listitem>
 184     </varlistentry>
 185
 186     <varlistentry>
 187       <term><option>/x</option></term>
 188       <listitem>
 189         <para>Closes WinMerge (after displaying an information
 190         dialog) when you start a comparison of identical files. The parameter has
 191         no effect after the comparison, for example if the files become identical
 192         as a result of merging or editing. This parameter is useful when you use
 193         WinMerge as an external compare application, or when you want to eliminate
 194         unnecessary steps by ignoring files that don't have any
 195         differences.</para>
 196       </listitem>
 197     </varlistentry>
 198
 199     <varlistentry>
 200       <term><option>/xq</option></term>
 201       <listitem>
 202         <para>Is similar to <option>/x</option> but does not
 203         show the message about identical files.</para>
 204       </listitem>
 205     </varlistentry>
 206
 207     <varlistentry>
 208       <indexterm>
 209         <primary>WinMerge window</primary>
 210         <secondary>limiting instances</secondary>
 211       </indexterm>
 212
 213       <term><option>/s</option></term>
 214       <listitem>
 215         <para>Limits WinMerge windows to a single instance.
 216         For example, if WinMerge is already running, a new compare opens in the
 217         same instance. Without this parameter, multiple windows are allowed:
 218         depending on other settings, a new compare might open in the existing
 219         window or in a new window.</para>
 220       </listitem>
 221     </varlistentry>
 222
 223     <varlistentry>
 224       <term><option>/sw</option></term>
 225       <listitem>
 226         <para>Limit the WinMerge window to one instance as well as the option /s.
 227          However, it waits for the instance displaying the window to terminate.
 228         </para>
 229       </listitem>
 230     </varlistentry>
 231
 232     <varlistentry>
 233       <term><option>/s-</option></term>
 234       <listitem>
 235         <para>Ensure that another instance is always executed, ignoring the
 236         value of the "Allow only one instance to run" option.</para>
 237       </listitem>
 238     </varlistentry>
 239
 240     <varlistentry>
 241       <indexterm>
 242         <primary>MRU list</primary>
 243       </indexterm>
 244
 245       <term><option>/ul</option></term>
 246       <listitem>
 247         <para>Prevents WinMerge from adding the left path to
 248         the Most Recently Used (MRU) list. External applications should not add
 249         paths to the MRU list in the Select Files or Folders dialog.</para>
 250       </listitem>
 251     </varlistentry>
 252
 253     <varlistentry>
 254       <term><option>/um</option></term>
 255       <listitem>
 256         <para>Prevents WinMerge from adding the middle path to
 257         the Most Recently Used (MRU) list. External applications should not add
 258         paths to the MRU list in the Select Files or Folders dialog.</para>
 259       </listitem>
 260     </varlistentry>
 261
 262     <varlistentry>
 263       <term><option>/ur</option></term>
 264       <listitem>
 265         <para>Prevents WinMerge from adding the right path to
 266         the Most Recently Used (MRU) list. External applications should not add
 267         paths to the MRU list in the Select Files or Folders dialog.</para>
 268       </listitem>
 269     </varlistentry>
 270
 271     <varlistentry>
 272       <term><option>/u</option></term>
 273       <listitem>
 274         <para>Prevents WinMerge from adding either path (left
 275         or right) to the Most Recently Used (MRU) list. External applications
 276         should not add paths to the MRU list in the Select Files or Folders
 277         dialog.</para>
 278       </listitem>
 279     </varlistentry>
 280
 281     <varlistentry>
 282       <indexterm>
 283         <primary>protecting files</primary>
 284       </indexterm>
 285
 286       <term><option>/wl</option></term>
 287       <listitem>
 288         <para>Opens the left side as read-only. Use this when
 289         you don't want to change left side items in the compare.</para>
 290       </listitem>
 291     </varlistentry>
 292
 293     <varlistentry>
 294       <term><option>/wm</option></term>
 295       <listitem>
 296         <para>Opens the middle side as read-only. Use this
 297         when you don't want to change right side items in the compare.</para>
 298       </listitem>
 299     </varlistentry>
 300
 301     <varlistentry>
 302       <term><option>/wr</option></term>
 303       <listitem>
 304         <para>Opens the right side as read-only. Use this
 305         when you don't want to change right side items in the compare.</para>
 306       </listitem>
 307     </varlistentry>
 308
 309     <varlistentry>
 310       <term><option>/self-compare</option></term>
 311       <listitem>
 312         <para>Compares the specified file with a copy of the file.</para>
 313       </listitem>
 314     </varlistentry>
 315
 316     <varlistentry>
 317       <indexterm>
 318         <primary>WinMerge window</primary>
 319         <secondary>opening minimized or maximized</secondary>
 320       </indexterm>
 321
 322       <term><option>/minimize</option></term>
 323       <listitem>
 324         <para>Starts WinMerge as a minimized window.
 325         This option can be useful during lengthy compares.</para>
 326       </listitem>
 327     </varlistentry>
 328
 329     <varlistentry>
 330       <term><option>/maximize</option></term>
 331       <listitem>
 332         <para>Starts WinMerge as a maximized
 333         window.</para>
 334       </listitem>
 335     </varlistentry>
 336
 337     <varlistentry>
 338       <term><option>/fl</option></term>
 339       <listitem>
 340         <para>Sets focus to the left side at startup.</para>
 341       </listitem>
 342     </varlistentry>
 343
 344     <varlistentry>
 345       <term><option>/fm</option></term>
 346       <listitem>
 347         <para>Sets focus to the middle side at startup.</para>
 348       </listitem>
 349     </varlistentry>
 350
 351     <varlistentry>
 352       <term><option>/fr</option></term>
 353       <listitem>
 354         <para>Sets focus to the right side at startup.</para>
 355       </listitem>
 356     </varlistentry>
 357
 358     <varlistentry>
 359       <term><option>/dl</option></term>
 360       <listitem>
 361         <para>Specifies a description in the left side title
 362         bar, overriding the default folder or filename text. For example:
 363         <userinput>/dl "Version 1.0</userinput>" or <userinput>/dl
 364         WorkingCopy</userinput>. Use quotation marks around descriptions that
 365         contain spaces.</para>
 366       </listitem>
 367     </varlistentry>
 368
 369     <varlistentry>
 370       <term><option>/dm</option></term>
 371       <listitem>
 372         <para>Specifies a description in the middle side title
 373         bar, just like <option>/dl</option>.</para>
 374       </listitem>
 375     </varlistentry>
 376
 377     <varlistentry>
 378       <term><option>/dr</option></term>
 379       <listitem>
 380         <para>Specifies a description in the right side title
 381         bar, just like <option>/dl</option>.</para>
 382       </listitem>
 383     </varlistentry>
 384
 385     <varlistentry>
 386       <term><option>leftpath</option></term>
 387       <listitem>
 388         <para>Specifies the folder, file or project file to open on the left side.</para>
 389       </listitem>
 390     </varlistentry>
 391
 392     <varlistentry>
 393       <term><option><replaceable>middlepath</replaceable></option></term>
 394       <listitem>
 395         <para>Specifies the folder, file or project file to open on the middle side.</para>
 396       </listitem>
 397     </varlistentry>
 398
 399     <varlistentry>
 400       <term><option><replaceable>rightpath</replaceable></option></term>
 401       <listitem>
 402         <para>Specifies the folder, file or project file to open on the right side.</para>
 403
 404         <para>WinMerge cannot compare files to folders, so the path parameters
 405         (<option><replaceable>leftpath</replaceable></option>,
 406         <option><replaceable>middlepath</replaceable></option> and
 407         <option><replaceable>rightpath</replaceable></option>) must point to the
 408         same target type (either folders or files). If WinMerge cannot find either
 409         of the specified paths, it opens the Select Files or Folders dialog, where
 410         you can browse for the correct paths.</para>
 411
 412         <tip>
 413           <para>In file comparisons, you can specify a folder name in one of the
 414           path parameters, as long as the folder contains a file with the same
 415           name as the one specified in the other, file path.</para>
 416
 417           <para>For example, consider this command:</para>
 418
 419           <para><userinput>WinMergeU <filename>C:\Folder\File.txt</filename>
 420           <filename class="directory">C:\Folder2</filename> </userinput></para>
 421
 422           <para>If <filename class="directory">C:\Folder2</filename> contains a
 423           file named <filename>File.txt</filename>: WinMerge implicitly resolves
 424           the second path as a file specification, and compares the two files. Of
 425           course, the command is invalid if <filename
 426           class="directory">C:\Folder2</filename> does <emphasis>not</emphasis>
 427           contain a file named <filename>File.txt</filename>.</para>
 428         </tip>
 429         <para></para>
 430       </listitem>
 431     </varlistentry>
 432
 433     <varlistentry>
 434       <indexterm>
 435         <primary>merging differences</primary>
 436         <secondary>result file</secondary>
 437       </indexterm>
 438
 439       <term><option>/o <replaceable>outputpath</replaceable></option></term>
 440       <listitem>
 441         <para>Specifies an optional output folder where you want merged result files to be
 442         saved.</para>
 443
 444         <para>The output path is rarely needed when you start WinMerge from
 445         the command line. It is meant to be used with version control tools, where
 446         you might need to specify a output path for the
 447         <wordasword>result</wordasword> file. If you specify a output path,
 448         WinMerge still shows only two or three files in the File Compare window. However,
 449         if you save either of these files, it is written to the output path,
 450         leaving the two or three source files intact.</para>
 451
 452         <para>Version control systems typically refer to the source and result
 453         files using terms like <glossterm>theirs</glossterm>,
 454         <glossterm>mine</glossterm>, and either <glossterm>merged</glossterm> or
 455         <glossterm>resolved</glossterm>. If you specify a output path on the
 456         WinMerge command line, and are working with a version control system, you
 457         should list the files in that order.</para>
 458       </listitem>
 459     </varlistentry>
 460
 461     <varlistentry>
 462       <term><option>/al</option></term>
 463       <listitem>
 464         <para>Auto-merges at the left side at startup.</para>
 465       </listitem>
 466     </varlistentry>
 467
 468     <varlistentry>
 469       <term><option>/am</option></term>
 470       <listitem>
 471         <para>Auto-merges at the middle side at startup.</para>
 472       </listitem>
 473     </varlistentry>
 474
 475     <varlistentry>
 476       <term><option>/ar</option></term>
 477       <listitem>
 478         <para>Auto-merges at the right side at startup.</para>
 479       </listitem>
 480     </varlistentry>
 481
 482     <varlistentry>
 483       <indexterm>
 484         <primary>conflict files</primary>
 485         <secondary>specifying on command line</secondary>
 486       </indexterm>
 487
 488       <term><option><replaceable>conflictfile</replaceable></option></term>
 489       <listitem>
 490         <para>Specifies a conflict file, typically generated by a Version control system. The
 491         conflict file opens in the File Compare window, where you can merge and
 492         resolve conflicts, as described in <xref
 493         linkend="ResolveConflictFiles" />. Note that no other paths can be used
 494         with a conflict file.</para>
 495       </listitem>
 496     </varlistentry>
 497
 498   </variablelist>
 499 </article>