PageRenderTime 23ms CodeModel.GetById 14ms app.highlight 3ms RepoModel.GetById 1ms app.codeStats 0ms

/doc/source/common.txt

https://bitbucket.org/tortoisehg/hgtk/
Plain Text | 136 lines | 106 code | 30 blank | 0 comment | 0 complexity | a51d54d0209e128f5ba59adc9629fd27 MD5 | raw file
  1Common Features
  2===============
  3
  4.. module:: common.dialog
  5	:synopsis: Features common to many dialogs
  6
  7These features are common to many TortoiseHg tools, so we document them
  8here just once.
  9
 10Visual Diffs
 11------------
 12
 13.. figure:: figures/visual-diff.jpg
 14	:alt: Visual Diff Window 
 15
 16	Visual Diff Window
 17
 18In TortoiseHg 1.0, the visual (external) diff infrastructure was
 19refactored.  The new system uses tool descriptions in
 20:file:`mergetools.rc` to detect most common diff tools on your computer
 21(including KDiff3, which ships in our installer) and select the best
 22available tool.
 23
 24If the user has selected a merge tool
 25(:menuselection:`TortoiseHg --> Three-way Merge Tool`), that tool will
 26also be used to perform visual diffs, bypassing the tool selection
 27process.  However the user can still select a separate tool
 28(:menuselection:`TortoiseHg --> Visual Diff Tool`) for visual diffs if
 29they chose.
 30
 31The merge tool configuration file contains optimal command lines for
 32each tool, so no further configuration is required by the user.  They
 33only need to select the tools they wish use, or accept the defaults.
 34
 35The visual diff system will use any existing extdiff configuration it
 36finds.  Since extdiff did not support three way diff arguments until
 37very recently and still does not support label arguments, you will
 38likely have a better experience by disabling or deleting any extdiff
 39configuration you may have.
 40
 41The visual diff system will directly use the selected diff tool unless
 42the action you are attempting requires the use of the TortoiseHg visual
 43diff window.  The list of conditions includes:
 44
 451) The selection of files being compared require multiple tools
 462) The selected tool forks detached background processes
 473) The selected tool does not support the required directory diffs
 484) The selected tool does not support three way comparisons
 495) The file changes include renames or copies
 50
 51When the visual diff window is used, the temporary files are cleaned up
 52when the dialog is closed.  Thus it should be left open until you close
 53all of your diff tool instances.  When your diff tool is launched
 54directly, the temporary files are deleted when your tool exits.
 55
 56If your diff tool is launched directly to compare a working copy file,
 57it will directly diff against the working file so you may modify it from
 58within the diff tool.  If you are comparing multiple files, the visual
 59diff system will make a snapshot of the working copy files and track
 60their initial sizes and timestamps.  When your diff tool exits, the
 61system compares the sizes and timestamps and copies modified files back
 62over the original working copies.  In this way, you can still modify
 63your working copy files from your visual diff tool even when performing
 64directory comparisons.
 65
 66When the visual diff window is used to compare working copy files, it
 67always directly diffs against the working copy files since it always
 68operates on a single file at a time.
 69
 70.. note::
 71	The :menuselection:`TortoiseHg --> Skip Diff Window` configurable
 72	has been removed because it is now redundant.
 73
 74Adding Tools
 75~~~~~~~~~~~~
 76
 77If you have a visual diff tool installed that is not supported by
 78TortoiseHg, you can create a tool configuration for it in your user
 79:file:`Mercurial.ini` file.  See Mercurial's
 80`documentation <http://www.selenic.com/mercurial/hgrc.5.html#merge-tools>`_
 81on how to configure your tool for use in file merges.  When that is
 82complete, you can add the extra keys used by TortoiseHg for visual
 83diff::
 84
 85	diffargs:  the arguments to use for two-way file comparisons
 86	diff3args: the arguments to use for three-way file comparisons
 87	dirdiff:   this tool supports two-way directory comparisons
 88	dir3diff:  this tool supports three-way directory comparisons
 89
 90When building command line arguments, you can use the following
 91variables::
 92
 93	$parent1:  the file or directory from the first parent revision
 94	$parent2:  the file or directory from the second parent revision
 95	$child:    the file or directory from the revision being compared
 96	$ancestor: the file or directory from the ancestor of a merge
 97	$parent:   a synonym for $parent1
 98
 99	$plabel1:  a symbolic name for the first parent revision
100	$plabel2:  a symbolic name for the second parent revision
101	$clabel:   a symbolic name for the revision being compared
102	$alabel:   a symbolic name for the ancestor revision
103
104Obviously, $parent2 and $ancestor are only meaningful when used in three
105way diff arguments, for viewing merge changesets.  If your diff tool
106cannot use the ancestor revision in any productive way, it is safe to
107leave it out of the diff3args command line.
108
109.. note::
110	On Windows, the `executable` parameter can use environment variables
111	using the syntax ${ProgramFiles}
112
113If unconfigured, the default value of **diffargs** is '$parent $child'.
114The default value of **diff3args** is "", indicating the visual diff
115tool cannot perform three way comparisons.
116
117If you create a new visual diff tool configuration, or improve upon an
118existing configuration, please email it to our development mailing list
119so it may be incorporated in a future release.
120
121
122Word Diffs
123~~~~~~~~~~
124
125The TortoiseHg Windows installers now include TortoiseSVN's scripts for
126comparing (and sometimes merging) many binary document formats.  These
127are configured in the site-wide :file:`mergepatterns.rc` as handlers for
128each binary format's common file extensions, so no user intervention is
129required.
130
131In order to support file extension based tool selection, TortoiseHg has
132added support for a **[diff-patterns]** section equivalent to Mercurial's
133`merge-patterns <http://www.selenic.com/mercurial/hgrc.5.html#merge-patterns>`_
134section.
135
136.. vim: noet ts=4