Navigation
This manual describes version 0.4.8 of Diffuse.
Copyright © 2009-2014 Derrick Moser
Table of Contents
Diffuse is a graphical tool for merging and comparing text files. Diffuse is able to compare an arbitrary number of files side-by-side and gives users the ability to manually adjust line matching and directly edit files. Diffuse can also retrieve revisions of files from Bazaar, CVS, Darcs, Git, Mercurial, Monotone, RCS, Subversion, and SVK repositories for comparison and merging.
Diffuse is free software; you may redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the licence, or (at your option) any later version.
Diffuse is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with Diffuse. You may also obtain a copy of the GNU General Public License from the Free Software Foundation by visiting their web site or by writing to
Free Software Foundation, Inc.
51 Franklin St, Fifth Floor,
Boston, MA 02110-1301
USA
diffuse [ -h | -? | --help | -v | --version ]Display information about Diffuse.
diffuse [ [option]... [file]... ]...Compare and merge files.
If a help option is specified, it must be the only argument specified on the command line. Diffuse will immediately quit after displaying the help information.
-h,-?,--helpDisplay usage information.
-v,--versionDisplay version number and copyright information.
If a configuration option is specified, it must be the first argument specified on the command line.
--no-rcfileDo not read any initialisation files.
--rcfilefileOnly read initialisation commands from file
file.
-c,--commitrevOpen separate file comparison tabs for all files affected by commit
revfrom the remaining paths specified in the command line arguments.-D,--close-if-sameClose all tabs with no differences.
-e,--encodingcodecUse
codecto read and write files.-L,--labellabelDisplay
labelinstead of the file name.-m,--modifiedOpen separate file comparison tabs for all modified files from the remaining paths specified in the command line arguments.
-r,--revisionrevInclude revision
revof the next file named in the command line arguments in a file comparison tab.-s,--separateOpen all remaining files specified in the command line arguments in separate file comparison tabs.
-t,--tabStart a new tab for any remaining files named in the command line arguments.
--linelineStart with line
lineselected.--null-fileCreate a blank file comparison pane.
Display options specified in the command line arguments will override saved preference values.
-b,--ignore-space-changeIgnore changes to the amount of white space.
-B,--ignore-blank-linesIgnore changes whose lines are all blank.
-E,--ignore-end-of-lineIgnore end of line differences.
-i,--ignore-caseIgnore case differences in file contents.
-w,--ignore-all-spaceIgnore all white space.
Table of Contents
Use the → , → , and → menu items to create additional tabs for comparing text files. File names and revisions can be specified either in the command line arguments used to invoke Diffuse or in fields on the Open File dialogue.
Diffuse displays files side-by-side inserting gaps to align similar lines of text. Differences are highlighted with a different background colour.
A summary of the compared files is located in the far right margin. The summary illustrates where gaps have been inserted to align matching lines of text and highlights differences using colour. Manual edits are also highlighted in green. A blue cursor identifies the region currently being viewed. The viewed region can be changed by clicking anywhere on the summary.
Lines of text can be selected using the mouse pointer or keyboard. Select lines of text with the mouse pointer by clicking on a line. Click and drag to select multiple lines. Holding down the shift key when clicking will extend the current selection. Select lines using the keyboard by pressing the page up/down or arrow keys. Extend the current selection by holding down the shift key and pressing the page up/down or arrow keys. Move the selection to an adjacent file using the left and right arrow keys.
The mouse pointer or keyboard can be used to manually align lines of text with adjacent files. To aligning lines of text using the mouse pointer, select a line of text with the left mouse button, right click on a line of text from an adjacent file, and choose . To align lines of text using the keyboard, move the selection with the cursor keys, press the space bar to pick the current line of text, move the selection with the cursor keys to a line of text in an adjacent file, and press the space bar to pick the target line of text. Pressing the Escape key will cancel the operation.
Use the menu item to prevent the selected lines from being matched with any lines from the adjacent files.
Press the Enter key or double-click on a text area to enter text editing mode. The cursor will change to indicate text editing mode and the status bar at the bottom of the window will display the cursor's column position.
In text editing mode, text can be selected with the mouse pointer by click and dragging. The current selection can be extended by holding down the shift key and moving the cursor by clicking with the mouse pointer or pressing any of the arrow, home, end or page up/down keys. Individual words can be selected by double-clicking on them with the mouse pointer. Whole lines can be selected by triple-clicking on them with the mouse pointer.
Modify text by typing on the keyword. Modified lines will be highlighted in green. Use the and menu items to undo and redo the previously preformed operations.
Press the Escape key or click on another file's text area using the left mouse button to leave editing mode.
Use the difference buttons or menu items to navigate between blocks of differences within a file. When navigating, Diffuse will move the selection to the next continuous set of lines with differences or edits.
Use the merge buttons or menu items to copy blocks of text into the selected range of lines. The and menu items can be used to undo and redo the previously preformed operations. All changes to a set of lines can be reverted using the menu item regardless of the order the edits were performed.
Table of Contents
Diffuse can retrieve file revisions from several version control systems via their command line interface. The Microsoft Windows build of Diffuse is able to use both the Cygwin and native versions of the supported version control systems. When using Diffuse with Cygwin, ensure Diffuse's Cygwin preferences correctly describe your system. If the Update paths for Cygwin preference exists for a version control system, it must be enabled to use the Cygwin version.
Version control systems are sensitive to the system path and other environment variable settings. The Launch from a Bash login shell preference may be used to easily set the environment for Cygwin version control systems.
The -m option will cause Diffuse to open
comparison tabs for each file the version control system indicates has
uncommitted modifications. This is convenient for reviewing all
changes before committing or resolving a merge conflict. If no paths
are specified the current working directory will be used. For example,
view all of your uncommitted modifications with this command line:
$diffuse -m
The default revision of a file will be used for comparison if only one
file is specified. For example, this will display a 2-way merge
between the default revision of foo.C and the
local foo.C file:
$diffuse foo.C
The -r option may also be used to explicitly
specify a particular file revision. Any revision specifier understood
by the version control system may be used. The local file will be used
for comparison if only one file revision is specified. For example,
this will display a 2-way merge between revision 123 of
foo.C and the local foo.C
file:
$diffuse -r 123 foo.C
Multiple file revisions can be compared by specifying multiple
-r options. For example, this will display a
2-way merge between revision 123 of foo.C and
revision 321 of foo.C:
$diffuse -r 123 -r 321 foo.C
Local files can be mixed with files from the version control system.
For example, this will display a 3-way merge between revision
MERGE_HEAD of foo.C, the local
foo.C file, and revision HEAD of
foo.C:
$diffuse -r MERGE_HEAD foo.C foo.C -r HEAD foo.C
For the -c option may be used to easily specify
a pair of sequential revisions. For example, this will display a 2-way
merge between revision 1.2.2 of
foo.C and revision 1.2.3 of
foo.C:
$diffuse -c 1.2.3 foo.C
Diffuse does not limit the number of panes that can be used for comparing files. The inputs to a Git octopus merge could be viewed with a command line like this:
$diffuse -r HEAD^1 -r HEAD^2 -r HEAD^3 -r HEAD^4 -r HEAD^5 foo.C
Table of Contents
Resources can be used to customise several aspects of Diffuse's appearance and behaviour such as changing the colours used in the user interface, customising the keyboard shortcuts, adding or replacing syntax highlighting rules, or changing the mapping from file extensions to syntax highlighting rules.
When Diffuse is started, it will read commands from the system wide
initialisation file /etc/diffuserc
(%INSTALL_DIR%\diffuserc on Microsoft Windows) and
then the personal initialisation file
~/.config/diffuse/diffuserc
(%HOME%\.config\diffuse\diffuserc on Microsoft Windows).
This behaviour can be changed with the --no-rcfile
and --rcfile configuration options. A Bourne
shell-like lexical analyser is used to parse initialisation commands.
Comments and special characters can be embedded using the same style of
escaping used in Bourne shell scripts.
importfileProcesses initialisation commands from
file. Initialisation files will only be processed once.
keybindingcontextactionkey_combinationBinds a key combination to
actionwhen used incontext. Specify Shift and Control modifiers by prependingShift+andCtrl+tokey_combinationrespectively. Keys normally modified by the Shift key should be specified using their modified value ifkey_combinationinvolves the Shift key. For example,Ctrl+gandShift+Ctrl+G. Remove bindings forkey_combinationby specifyingNonefor theaction.
Use menu for the
context to define key bindings for menu
items. The following values are valid for
action:
open_file→ menu item
Default:
Ctrl+oopen_file_in_new_tab→ menu item
Default:
Ctrl+topen_modified_files→ menu item
Default:
Shift+Ctrl+Oopen_commit→ menu item
Default:
Shift+Ctrl+Treload_file→ menu item
Default:
Shift+Ctrl+Rsave_file→ menu item
Default:
Ctrl+ssave_file_as→ menu item
Default:
Shift+Ctrl+Asave_all→ menu item
Default:
Shift+Ctrl+Snew_2_way_file_merge→ menu item
Default:
Ctrl+2new_3_way_file_merge→ menu item
Default:
Ctrl+3new_n_way_file_merge→ menu item
Default:
Ctrl+4close_tab→ menu item
Default:
Ctrl+wundo_close_tab→ menu item
Default:
Shift+Ctrl+wquit→ menu item
Default:
Ctrl+qundo→ menu item
Default:
Ctrl+zredo→ menu item
Default:
Shift+Ctrl+Zcut→ menu item
Default:
Ctrl+xcopy→ menu item
Default:
Ctrl+cpaste→ menu item
Default:
Ctrl+vselect_all→ menu item
Default:
Ctrl+aclear_edits→ menu item
Default:
Ctrl+rdismiss_all_edits→ menu item
Default:
Ctrl+dfind→ menu item
Default:
Ctrl+ffind_next→ menu item
Default:
Ctrl+gfind_previous→ menu item
Default:
Shift+Ctrl+Ggo_to_line→ menu item
Default:
Shift+Ctrl+Lpreferences→ menu item
Default: None
no_syntax_highlighting→ → menu item
Default: None
syntax_highlighting_syntax→ → menu item
Default: None
realign_all→ menu item
Default:
Ctrl+lisolate→ menu item
Default:
Ctrl+ifirst_difference→ menu item
Default:
Shift+Ctrl+Upprevious_difference→ menu item
Default:
Ctrl+Upnext_difference→ menu item
Default:
Ctrl+Downlast_difference→ menu item
Default:
Shift+Ctrl+Downfirst_tab→ menu item
Default:
Shift+Ctrl+Page_Upprevious_tab→ menu item
Default:
Ctrl+Page_Upnext_tab→ menu item
Default:
Ctrl+Page_Downlast_tab→ menu item
Default:
Shift+Ctrl+Page_Downshift_pane_right→ menu item
Default:
Shift+Ctrl+parenleftshift_pane_left→ menu item
Default:
Shift+Ctrl+parenrightconvert_to_upper_case→ menu item
Default:
Ctrl+uconvert_to_lower_case→ menu item
Default:
Shift+Ctrl+Usort_lines_in_ascending_order→ menu item
Default:
Ctrl+ysort_lines_in_descending_order→ menu item
Default:
Shift+Ctrl+Yremove_trailing_white_space→ menu item
Default:
Ctrl+kconvert_tabs_to_spaces→ menu item
Default:
Ctrl+bconvert_leading_spaces_to_tabs→ menu item
Default:
Shift+Ctrl+Bincrease_indenting→ menu item
Default:
Shift+Ctrl+greaterdecrease_indenting→ menu item
Default:
Shift+Ctrl+lessconvert_to_dos→ menu item
Default:
Shift+Ctrl+Econvert_to_mac→ menu item
Default:
Shift+Ctrl+Cconvert_to_unix→ menu item
Default:
Ctrl+ecopy_selection_right→ menu item
Default:
Shift+Ctrl+Rightcopy_selection_left→ menu item
Default:
Shift+Ctrl+Leftcopy_left_into_selection→ menu item
Default:
Ctrl+Rightcopy_right_into_selection→ menu item
Default:
Ctrl+Leftmerge_from_left_then_right→ menu item
Default:
Ctrl+mmerge_from_right_then_left→ menu item
Default:
Shift+Ctrl+Mhelp_contents→ menu item
Default:
F1about→ menu item
Default: None
Use line_mode for the
context to define key bindings for line
editing mode. The following values are valid for
action:
enter_align_modeenter alignment editing mode
Default:
spaceenter_character_modeenter character editing mode
Defaults:
Return,KP_Enterfirst_linemove cursor to the first line
Defaults:
Home,gextend_first_linemove cursor to the first line, extending the selection
Default:
Shift+Homelast_linemove cursor to the last line
Defaults:
End,Shift+Gextend_last_linemove cursor to the last line, extending the selection
Default:
Shift+Endupmove cursor up one line
Defaults:
Up,kextend_upmove cursor up one line, extending the selection
Defaults:
Shift+Up,Shift+Kdownmove cursor down one line
Defaults:
Down,jextend_downmove cursor down one line, extending the selection
Defaults:
Shift+Down,Shift+Jleftmove cursor left one file
Defaults:
Left,hextend_leftmove cursor left one file, extending the selection
Default:
Shift+Leftrightmove cursor right one file
Defaults:
Right,lextend_rightmove cursor right one file, extending the selection
Default:
Shift+Rightpage_upmove cursor up one page
Defaults:
Page_Up,Ctrl+uextend_page_upmove cursor up one page, extending the selection
Defaults:
Shift+Page_Up,Shift+Ctrl+upage_downmove cursor down one page
Defaults:
Page_Down,Ctrl+dextend_page_downmove cursor down one page, extending the selection
Defaults:
Shift+Page_Down,Shift+Ctrl+ddelete_textdelete the selected text
Defaults:
BackSpace,Delete,xfirst_differenceselect the first difference
Defaults:
Ctrl+Home,Shift+Pprevious_differenceselect the previous difference
Default:
pnext_differenceselect the next difference
Default:
nlast_differenceselect the last difference
Defaults:
Ctrl+End,Shift+Nclear_editsclear all edits from the selected lines
Default:
rcopy_selection_leftcopy lines from the selection into the file on the left
Default: None
copy_selection_rightcopy lines from the selection into the file on the right
Default: None
copy_left_into_selectioncopy lines from the file on the left into the selection
Default:
Shift+Lcopy_right_into_selectioncopy lines from the file on the right into the selection
Default:
Shift+Hmerge_from_left_then_rightmerge lines from file on the left then file on the right
Default:
mmerge_from_right_then_leftmerge lines from file on the right then file on the left
Default:
Shift+Misolateisolate the selected lines
Default:
i
Use align_mode for the
context to define key bindings for
alignment editing mode. The following values are valid for
action:
enter_line_modeenter line editing mode
Default:
Escapeenter_character_modeenter character editing mode
Defaults:
Return,KP_Enterfirst_linemove cursor to the first line
Default:
glast_linemove cursor to the last line
Default:
Shift+Gupmove cursor up one line
Defaults:
Up,kdownmove cursor down one line
Defaults:
Down,jleftmove cursor left one file
Defaults:
Left,hrightmove cursor right one file
Defaults:
Right,lpage_upmove cursor up one page
Defaults:
Page_Up,Ctrl+upage_downmove cursor down one page
Defaults:
Page_Down,Ctrl+dalignalign the selected line to the cursor position
Default:
space
stringnamevalueDeclares a string resource called
namewith valuevalue.
[ colour | color ]nameredgreenblueDeclares a colour resource called
name. Individual colour components should be expressed as a value between 0 and 1.
The following colour resources are used by Diffuse:
alignmentcolour used to indicate a line picked for manual alignment
Default:
1 1 0character_selectioncolour used to indicate selected characters
Default:
0.7 0.7 1cursorcolour used for the cursor
Default:
0 0 0difference_1colour used to identify differences between the first pair of files
Default:
1 0.625 0.625difference_2colour used to identify differences between the second pair of files
Default:
0.85 0.625 0.775difference_3colour used to identify differences between the third pair of files
Default:
0.85 0.775 0.625editedcolour used to indicate edited lines
Default:
0.5 1 0.5hatchcolour used for indicating alignment gaps
Default:
0.8 0.8 0.8line_numbercolour used for line numbers
Default:
0 0 0line_number_backgroundbackground colour for the line number area
Default:
0.75 0.75 0.75line_selectioncolour used to indicate selected lines
Default:
0.7 0.7 1map_backgroundbackground colour for the map area
Default:
0.6 0.6 0.6margincolour used to indicate the right margin
Default:
0.8 0.8 0.8preeditpre-edit text colour
Default:
0 0 0textregular text colour
Default:
0 0 0text_backgroundbackground colour for the text area
Default:
1 1 1
floatnamevalueDeclares a floating point resource called
namewith valuevalue.
The following floating point resources are used by Diffuse:
alignment_opacityopacity used when compositing the manual alignment colour
Defaults:
1character_difference_opacityopacity used when compositing character difference colours
Defaults:
0.4character_selection_opacityopacity used when compositing the character selection colour
Defaults:
0.4edited_opacityopacity used when compositing the edited line colour
Defaults:
0.4line_difference_alphaalpha value used when compositing line difference colours
Defaults:
0.3line_selection_opacityopacity used when compositing the line selection colour
Defaults:
0.4
syntaxname[initial_statedefault_tag]Declares a new syntax style called
name. Syntax highlighting uses a simple state machine that transitions between states when certain patterns are matched. The initial state for the state machine will beinitial_state. All characters not matched by a pattern will be tagged asdefault_tagfor highlighting. The syntax style callednamecan be removed by omittinginitial_stateanddefault_tag.syntax_filesname[pattern]Specifies that files with a name matching
patternshould be highlighted using the syntax style calledname. Patterns used to match files for use with the syntax style callednamecan be removed by omittingpattern.syntax_magicname[pattern[ignorecase]]Specifies that files with a first line matching
patternshould be highlighted using the syntax style calledname. Patterns used to match files for use with the syntax style callednamecan be removed by omittingpattern.syntax_patternnameinitial_statefinal_statetagpattern[ignorecase]Adds a pattern to the previously declared syntax style. Patterns are tried one at a time in the order they were declared until the first match is found. A pattern will only be used to match characters if the state machine is in the state
initial_state. The state machine will transition tofinal_stateif the pattern defined bypatternis matched. Case insensitive pattern matching will be used ifignorecaseis specified. All characters matched by the pattern will be tagged astagfor highlighting.
The following files are used by Diffuse:
/etc/diffusercsystem wide initialisations (
%INSTALL_DIR%\diffusercon Microsoft Windows)/usr/share/diffuse/syntax/*.syntaxsyntax files for various languages (
%INSTALL_DIR%\syntax\*.syntaxon Microsoft Windows)~/.config/diffuse/diffusercyour initialisations (
%HOME%\.config\diffuse\diffusercon Microsoft Windows)~/.config/diffuse/prefsyour saved preferences (
%HOME%\.config\diffuse\prefson Microsoft Windows)~/.local/share/diffuse/statedata persistent across sessions (
%HOME%\.local\share\diffuse\stateon Microsoft Windows)