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

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   2 <!DOCTYPE sect2 SYSTEM "../../../dtd/dblite.dtd">\r
   3 <sect2 id="tsvn-dug-settings-progs">\r
   4         <title>External Program Settings</title>\r
   5         <para>\r
   6                 <figure id="tsvn-dug-settings-dia-5">\r
   7                         <title>The Settings Dialog, Diff Viewer Page</title>\r
   8                         <?dbhh topicname="HIDD_SETTINGSPROGSDIFF"?>\r
   9                         <graphic fileref="../images/SettingsProgs.png"/>\r
  10                 </figure>\r
  11                 Here you can define your own diff/merge programs that TortoiseGit\r
  12                 should use. The default setting is to use TortoiseMerge\r
  13                 which is installed alongside TortoiseGit.\r
  14         </para>\r
  15         <para>\r
  16                 Read <xref linkend="tsvn-dug-diff-tools"/> for a list of some of the\r
  17                 external diff/merge programs that people are using with TortoiseGit.\r
  18         </para>\r
  19         <sect3 id="tsvn-dug-settings-Diff">\r
  20                 <title>Diff Viewer</title>\r
  21                 <?dbhh topicname="HIDD_SETTINGSPROGSDIFF"?>\r
  22                 <para>\r
  23                         An external diff program may be used for comparing different\r
  24                         revisions of files. The external program will need to\r
  25                         obtain the filenames from the command line, along with\r
  26                         any other command line options. TortoiseGit uses\r
  27                         substitution parameters prefixed with <literal>%</literal>.\r
  28                         When it encounters one of these it will substitute the\r
  29                         appropriate value. The order of the parameters will depend\r
  30                         on the Diff program you use.\r
  31                         <variablelist>\r
  32                                 <varlistentry>\r
  33                                         <term condition="pot">%base</term>\r
  34                                         <listitem>\r
  35                                                 <para>\r
  36                                                         The original file without your changes\r
  37                                                 </para>\r
  38                                         </listitem>\r
  39                                 </varlistentry>\r
  40                                 <varlistentry>\r
  41                                         <term condition="pot">%bname</term>\r
  42                                         <listitem>\r
  43                                                 <para>\r
  44                                                         The window title for the base file\r
  45                                                 </para>\r
  46                                         </listitem>\r
  47                                 </varlistentry>\r
  48                                 <varlistentry>\r
  49                                         <term condition="pot">%mine</term>\r
  50                                         <listitem>\r
  51                                                 <para>\r
  52                                                         Your own file, with your changes\r
  53                                                 </para>\r
  54                                         </listitem>\r
  55                                 </varlistentry>\r
  56                                 <varlistentry>\r
  57                                         <term condition="pot">%yname</term>\r
  58                                         <listitem>\r
  59                                                 <para>\r
  60                                                         The window title for your file\r
  61                                                 </para>\r
  62                                         </listitem>\r
  63                                 </varlistentry>\r
  64                         </variablelist>\r
  65                 </para>\r
  66                 <para>\r
  67                         The window titles are not pure filenames.\r
  68                         TortoiseGit treats that as a name to display and creates\r
  69                         the names accordingly. So e.g. if you're doing a\r
  70                         diff from a file in revision 123 with a file \r
  71                         in your working copy, the names will be\r
  72                         <filename>filename : revision 123</filename>\r
  73                         and\r
  74                         <filename>filename : working copy</filename>\r
  75                 </para>\r
  76                 <para>\r
  77                         For example, with ExamDiff Pro:\r
  78 <screen>\r
  79 C:\Path-To\ExamDiff.exe %base %mine --left_display_name:%bname\r
  80     --right_display_name:%yname\r
  81 </screen>\r
  82                         or with KDiff3:\r
  83 <screen>\r
  84 C:\Path-To\kdiff3.exe %base %mine --L1 %bname --L2 %yname\r
  85 </screen>\r
  86                         or with WinMerge:\r
  87 <screen>\r
  88 C:\Path-To\WinMerge.exe -e -ub -dl %bname -dr %yname %base %mine\r
  89 </screen>\r
  90                         or with Araxis:\r
  91 <screen>\r
  92 C:\Path-To\compare.exe /max /wait /title1:%bname /title2:%yname\r
  93     %base %mine\r
  94 </screen>\r
  95                 </para>\r
  96                 <para>\r
  97                         If you use the <literal>svn:keywords</literal> property to\r
  98                         expand keywords, and in particular the <emphasis>revision</emphasis>\r
  99                         of a file, then there may be a difference between files which\r
 100                         is purely due to the current value of the keyword. Also if you use\r
 101                         <literal>svn:eol-style = native</literal> the BASE file will have\r
 102                         pure <literal>LF</literal> line endings whereas your file will\r
 103                         have <literal>CR-LF</literal> line endings. TortoiseGit will normally hide\r
 104                         these differences automatically by first parsing the BASE file to\r
 105                         expand keywords and line endings before doing the diff operation.\r
 106                         However, this can take a long time with large files. If\r
 107                         <guilabel>Convert files when diffing against BASE</guilabel>\r
 108                         is unchecked then TortoiseGit will skip pre-processing the files.\r
 109                 </para>\r
 110                 <para>\r
 111                         You can also specify a different diff tool to use on Git\r
 112                         properties. Since these tend to be short simple text strings, you\r
 113                         may want to use a simpler more compact viewer.\r
 114                 </para>\r
 115                 <para>\r
 116                         If you have configured an alternate diff tool, you can access\r
 117                         TortoiseMerge <emphasis>and</emphasis> the third party tool\r
 118                         from the context menus.\r
 119                         <menuchoice>\r
 120                                 <guimenu>Context menu</guimenu>\r
 121                                 <guimenuitem>Diff</guimenuitem>\r
 122                         </menuchoice>\r
 123                         uses the primary diff tool, and\r
 124                         <keycap>Shift</keycap>+\r
 125                         <menuchoice>\r
 126                                 <guimenu>Context menu</guimenu>\r
 127                                 <guimenuitem>Diff</guimenuitem>\r
 128                         </menuchoice>\r
 129                         uses the secondary diff tool.\r
 130                 </para>\r
 131         </sect3>\r
 132         <sect3 id="tsvn-dug-settings-Merge">\r
 133                 <title>Merge Tool</title>\r
 134                 <?dbhh topicname="HIDD_SETTINGSPROGSMERGE"?>\r
 135                 <para>\r
 136                         An external merge program used to resolve conflicted\r
 137                         files. Parameter substitution is used in the same way\r
 138                         as with the Diff Program.\r
 139                         <variablelist>\r
 140                                 <varlistentry>\r
 141                                         <term condition="pot">%base</term>\r
 142                                         <listitem>\r
 143                                                 <para>\r
 144                                                         the original file without your or\r
 145                                                         the others changes\r
 146                                                 </para>\r
 147                                         </listitem>\r
 148                                 </varlistentry>\r
 149                                 <varlistentry>\r
 150                                         <term condition="pot">%bname</term>\r
 151                                         <listitem>\r
 152                                                 <para>\r
 153                                                         The window title for the base file\r
 154                                                 </para>\r
 155                                         </listitem>\r
 156                                 </varlistentry>\r
 157                                 <varlistentry>\r
 158                                         <term condition="pot">%mine</term>\r
 159                                         <listitem>\r
 160                                                 <para>\r
 161                                                         your own file, with your changes\r
 162                                                 </para>\r
 163                                         </listitem>\r
 164                                 </varlistentry>\r
 165                                 <varlistentry>\r
 166                                         <term condition="pot">%yname</term>\r
 167                                         <listitem>\r
 168                                                 <para>\r
 169                                                         The window title for your file\r
 170                                                 </para>\r
 171                                         </listitem>\r
 172                                 </varlistentry>\r
 173                                 <varlistentry>\r
 174                                         <term condition="pot">%theirs</term>\r
 175                                         <listitem>\r
 176                                                 <para>\r
 177                                                         the file as it is in the repository\r
 178                                                 </para>\r
 179                                         </listitem>\r
 180                                 </varlistentry>\r
 181                                 <varlistentry>\r
 182                                         <term condition="pot">%tname</term>\r
 183                                         <listitem>\r
 184                                                 <para>\r
 185                                                         The window title for the file in the repository\r
 186                                                 </para>\r
 187                                         </listitem>\r
 188                                 </varlistentry>\r
 189                                 <varlistentry>\r
 190                                         <term condition="pot">%merged</term>\r
 191                                         <listitem>\r
 192                                                 <para>\r
 193                                                         the conflicted file, the result of\r
 194                                                         the merge operation\r
 195                                                 </para>\r
 196                                         </listitem>\r
 197                                 </varlistentry>\r
 198                                 <varlistentry>\r
 199                                         <term condition="pot">%mname</term>\r
 200                                         <listitem>\r
 201                                                 <para>\r
 202                                                         The window title for the merged file\r
 203                                                 </para>\r
 204                                         </listitem>\r
 205                                 </varlistentry>\r
 206                         </variablelist>\r
 207                 </para>\r
 208                 <para>\r
 209                         For example, with Perforce Merge:\r
 210 <screen>\r
 211 C:\Path-To\P4Merge.exe %base %theirs %mine %merged\r
 212 </screen>\r
 213                         or with KDiff3:\r
 214 <screen>\r
 215 C:\Path-To\kdiff3.exe %base %mine %theirs -o %merged\r
 216     --L1 %bname --L2 %yname --L3 %tname\r
 217 </screen>\r
 218                         or with Araxis:\r
 219 <screen>\r
 220 C:\Path-To\compare.exe /max /wait /3 /title1:%tname /title2:%bname\r
 221     /title3:%yname %theirs %base %mine %merged /a2\r
 222 </screen>\r
 223                         or with WinMerge (2.8 or later):\r
 224 <screen>\r
 225 C:\Path-To\WinMerge.exe %merged\r
 226 </screen>\r
 227                 </para>\r
 228         </sect3>\r
 229         <sect3 id="tsvn-dug-settings-Progs-Adv">\r
 230                 <title>Diff/Merge Advanced Settings</title>\r
 231                 <?dbhh topicname="HIDD_SETTINGSPROGSADV"?>\r
 232                 <para>\r
 233                         <figure id="tsvn-dug-settings-dia-6">\r
 234                                 <title>The Settings Dialog, Diff/Merge Advanced Dialog</title>\r
 235                                 <graphic fileref="../images/SettingsProgsAdv.png"/>\r
 236                         </figure>\r
 237                         In the advanced settings, you can define a different diff and merge\r
 238                         program for every file extension. For instance you could associate\r
 239                         Photoshop as the <quote>Diff</quote> Program for <filename>.jpg</filename> files :-)\r
 240                         You can also associate the <literal>svn:mime-type</literal> property\r
 241                         with a diff or merge program.\r
 242                 </para>\r
 243                 <para>\r
 244                         To associate using a file extension, you need to specify the extension.\r
 245                         Use <literal>.bmp</literal> to describe Windows bitmap files.\r
 246                         To associate using the <literal>svn:mime-type</literal> property, specify\r
 247                         the mime type, including a slash, for example\r
 248                         <literal>text/xml</literal>.\r
 249                 </para>\r
 250         </sect3>\r
 251         <sect3 id="tsvn-dug-settings-Patch">\r
 252                 <title>Unified Diff Viewer</title>\r
 253                 <?dbhh topicname="HIDD_SETTINGSPROGSUNIDIFF"?>\r
 254                 <para>\r
 255                         A viewer program for unified-diff files (patch files).\r
 256                         No parameters are required.\r
 257                         The <guilabel>Default</guilabel> option is to check for\r
 258                         a file association for <filename>.diff</filename> files,\r
 259                         and then for <filename>.txt</filename> files.\r
 260                         If you don't have a viewer for <filename>.diff</filename>\r
 261                         files, you will most likely get NotePad.\r
 262                 </para>\r
 263                 <para>\r
 264                         The original Windows NotePad program does not behave\r
 265                         well on files which do not have standard CR-LF\r
 266                         line-endings. Since most unified diff files have pure\r
 267                         LF line-endings, they do not view well in NotePad.\r
 268                         However, you can download a free NotePad replacement\r
 269                         <ulink url="http://www.flos-freeware.ch/notepad2.html">\r
 270                                 <citetitle>Notepad2</citetitle>\r
 271                         </ulink>\r
 272                         which not only displays the line-endings correctly,\r
 273                         but also colour codes the added and removed lines.\r
 274                 </para>\r
 275         </sect3>\r
 276 </sect2>\r