]> &manual-year; Derrick Moser Derrick Moser derrick_moser@yahoo.com This manual describes version &app-version; of &app;. &app; is a graphical tool for merging and comparing text files. &app; 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. &app; can also retrieve revisions of files from Bazaar, CVS, Darcs, Git, Mercurial, Monotone, RCS, and Subversion repositories for comparison and merging. &app; was written by Derrick Moser derrick_moser@yahoo.com. © &app-year; Derrick Moser. All Rights Reserved. &app; 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. &app; 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 &app;. 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 &app;. diffuse [ [ option ]... [ file ]... ]... Compare and merge files. If a help option is specified, it must be the only argument specified on the command line. &app; will immediately quit after displaying the help information. -h, -?, --help Display usage information. -v, --version Display version number and copyright information. If a configuration option is specified, it must be the first argument specified on the command line. --no-rcfile Do not read any initialisation files. --rcfile file Only read initialisation commands from file file. -c, --commit rev Open separate file comparison tabs for all files affected by commit rev from the remaining paths specified in the command line arguments. -D, --close-if-same Close all tabs with no differences. -e, --encoding codec Use codec to read and write files. -L, --label label Display label instead of the file name. -m, --modified Open separate file comparison tabs for all modified files from the remaining paths specified in the command line arguments. -r, --revision rev Include revision rev of the next file named in the command line arguments in a file comparison tab. -s, --separate Open all remaining files specified in the command line arguments in separate file comparison tabs. -t, --tab Start a new tab for any remaining files named in the command line arguments. -V, --vcs vcs-list Search for version control systems in the ordering: vcs-list. --line line Start with line line selected. --null-file Create a blank file comparison pane. Display options specified in the command line arguments will override saved preference values. -b, --ignore-space-change Ignore changes to the amount of white space. -B, --ignore-blank-lines Ignore changes whose lines are all blank. -E, --ignore-end-of-line Ignore end of line differences. -i, --ignore-case Ignore case differences in file contents. -w, --ignore-all-space Ignore all white space. Use the FileNew 2-Way File Merge, FileNew 3-Way File Merge, and FileNew N-Way File Merge 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 &app; or in fields on the Open File dialogue. &app; 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 Align with Selection. 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 Isolate 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 Undo and Redo 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, &app; 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 Undo and Redo 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 Clear Edits menu item regardless of the order the edits were performed. &app; can retrieve file revisions from several version control systems via their command line interface. The Microsoft Windows build of &app; is able to use both the Cygwin and native versions of the supported version control systems. When using &app; with Cygwin, ensure &app;'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 &app; 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 &app; 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 Resources can be used to customise several aspects of &app;'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 &app; 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. import file Processes initialisation commands from file. Initialisation files will only be processed once. keybinding context action key_combination Binds a key combination to action when used in context. Specify Shift and Control modifiers by prepending Shift+ and Ctrl+ to key_combination respectively. Keys normally modified by the Shift key should be specified using their modified value if key_combination involves the Shift key. For example, Ctrl+g and Shift+Ctrl+G. Remove bindings for key_combination by specifying None for the action. Use menu for the context to define key bindings for menu items. The following values are valid for action: open-file FileOpen File... menu item Default: Ctrl+o open-file-in-new-tab FileOpen File In New Tab... menu item Default: Ctrl+t open-modified-files FileOpen Modified Files... menu item Default: Shift+Ctrl+O open-commit FileOpen Commit... menu item Default: Shift+Ctrl+T reload-file FileReload File menu item Default: Shift+Ctrl+R save-file FileSave File menu item Default: Ctrl+s save-file-as FileSave File As... menu item Default: Shift+Ctrl+A save-all FileSave All menu item Default: Shift+Ctrl+S new-2-way-file-merge FileNew 2-Way File Merge menu item Default: Ctrl+2 new-3-way-file-merge FileNew 3-Way File Merge menu item Default: Ctrl+3 new-n-way-file-merge FileNew N-Way File Merge menu item Default: Ctrl+4 close-tab FileClose Tab menu item Default: Ctrl+w undo-close-tab FileUndo Close Tab menu item Default: Shift+Ctrl+w quit FileQuit menu item Default: Ctrl+q undo EditUndo menu item Default: Ctrl+z redo EditRedo menu item Default: Shift+Ctrl+Z cut EditCut menu item Default: Ctrl+x copy EditCopy menu item Default: Ctrl+c paste EditPaste menu item Default: Ctrl+v select-all EditSelect All menu item Default: Ctrl+a clear-edits EditClear Edits menu item Default: Ctrl+r dismiss-all-edits EditDismiss All Edits menu item Default: Ctrl+d find EditFind... menu item Default: Ctrl+f find-next EditFind Next menu item Default: Ctrl+g find-previous EditFind Previous menu item Default: Shift+Ctrl+G go-to-line EditGo To Line... menu item Default: Shift+Ctrl+L preferences EditPreferences menu item Default: None no-syntax-highlighting ViewSyntax HighlightingNone menu item Default: None syntax-highlighting-syntax ViewSyntax Highlightingsyntax menu item Default: None realign-all ViewRealign All menu item Default: Ctrl+l isolate ViewIsolate menu item Default: Ctrl+i first-difference ViewFirst Difference menu item Default: Shift+Ctrl+Up previous-difference ViewPrevious Difference menu item Default: Ctrl+Up next-difference ViewNext Difference menu item Default: Ctrl+Down last-difference ViewLast Difference menu item Default: Shift+Ctrl+Down first-tab ViewFirst Tab menu item Default: Shift+Ctrl+Page_Up previous-tab ViewPrevious Tab menu item Default: Ctrl+Page_Up next-tab ViewNext Tab menu item Default: Ctrl+Page_Down last-tab ViewLast Tab menu item Default: Shift+Ctrl+Page_Down shift-pane-right ViewShift Pane Right menu item Default: Shift+Ctrl+parenleft shift-pane-left ViewShift Pane Left menu item Default: Shift+Ctrl+parenright convert-to-upper-case FormatConvert To Upper Case menu item Default: Ctrl+u convert-to-lower-case FormatConvert To Lower Case menu item Default: Shift+Ctrl+U sort-lines-in-ascending-order FormatSort Lines In Ascending Order menu item Default: Ctrl+y sort-lines-in-descending-order FormatSort Lines In Descending Order menu item Default: Shift+Ctrl+Y remove-trailing-white-space FormatRemove Trailing White Space menu item Default: Ctrl+k convert-tabs-to-spaces FormatConvert Tabs To Spaces menu item Default: Ctrl+b convert-leading-spaces-to-tabs FormatConvert Leading Spaces To Tabs menu item Default: Shift+Ctrl+B increase-indenting FormatIncrease Indenting menu item Default: Shift+Ctrl+greater decrease-indenting FormatDecrease Indenting menu item Default: Shift+Ctrl+less convert-to-dos FormatConvert To DOS Format menu item Default: Shift+Ctrl+E convert-to-mac FormatConvert To Mac Format menu item Default: Shift+Ctrl+C convert-to-unix FormatConvert To Unix Format menu item Default: Ctrl+e copy-selection-right MergeCopy Selection Right menu item Default: Shift+Ctrl+Right copy-selection-left MergeCopy Selection Left menu item Default: Shift+Ctrl+Left copy-left-into-selection MergeCopy Left Into Selection menu item Default: Ctrl+Right copy-right-into-selection MergeCopy Right Into Selection menu item Default: Ctrl+Left merge-from-left-then-right MergeMerge From Left Then Right menu item Default: Ctrl+m merge-from-right-then-left MergeMerge From Right Then Left menu item Default: Shift+Ctrl+M help-contents HelpHelp Contents menu item Default: F1 about HelpAbout 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-mode enter alignment editing mode Default: space enter-character-mode enter character editing mode Defaults: Return, KP_Enter first-line move cursor to the first line Defaults: Home, g extend-first-line move cursor to the first line, extending the selection Default: Shift+Home last-line move cursor to the last line Defaults: End, Shift+G extend-last-line move cursor to the last line, extending the selection Default: Shift+End up move cursor up one line Defaults: Up, k extend-up move cursor up one line, extending the selection Defaults: Shift+Up, Shift+K down move cursor down one line Defaults: Down, j extend-down move cursor down one line, extending the selection Defaults: Shift+Down, Shift+J left move cursor left one file Defaults: Left, h extend-left move cursor left one file, extending the selection Default: Shift+Left right move cursor right one file Defaults: Right, l extend-right move cursor right one file, extending the selection Default: Shift+Right page-up move cursor up one page Defaults: Page_Up, Ctrl+u extend-page-up move cursor up one page, extending the selection Defaults: Shift+Page_Up, Shift+Ctrl+u page-down move cursor down one page Defaults: Page_Down, Ctrl+d extend-page-down move cursor down one page, extending the selection Defaults: Shift+Page_Down, Shift+Ctrl+d delete-text delete the selected text Defaults: BackSpace, Delete, x first-difference select the first difference Defaults: Ctrl+Home, Shift+P previous-difference select the previous difference Default: p next-difference select the next difference Default: n last-difference select the last difference Defaults: Ctrl+End, Shift+N clear-edits clear all edits from the selected lines Default: r copy-selection-left copy lines from the selection into the file on the left Default: None copy-selection-right copy lines from the selection into the file on the right Default: None copy-left-into-selection copy lines from the file on the left into the selection Default: Shift+L copy-right-into-selection copy lines from the file on the right into the selection Default: Shift+H merge-from-left-then-right merge lines from file on the left then file on the right Default: m merge-from-right-then-left merge lines from file on the right then file on the left Default: Shift+M isolate isolate 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-mode enter line editing mode Default: Escape enter-character-mode enter character editing mode Defaults: Return, KP_Enter first-line move cursor to the first line Default: g last-line move cursor to the last line Default: Shift+G up move cursor up one line Defaults: Up, k down move cursor down one line Defaults: Down, j left move cursor left one file Defaults: Left, h right move cursor right one file Defaults: Right, l page-up move cursor up one page Defaults: Page_Up, Ctrl+u page-down move cursor down one page Defaults: Page_Down, Ctrl+d align align the selected line to the cursor position Default: space Use character-mode for the context to define key bindings for character editing mode. The following values are valid for action: enter-line-mode enter line editing mode Default: Escape string name value Declares a string resource called name with value value. The following string resources are used by &app;: difference_colours a list of colour resources used to indicate differences Default: difference_1 difference_2 difference_3 [ colour | color ] name red green blue Declares 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 &app;: alignment colour used to indicate a line picked for manual alignment Default: 1 1 0 character_selection colour used to indicate selected characters Default: 0.7 0.7 1 cursor colour used for the cursor Default: 0 0 0 difference_1 colour used to identify differences between the first pair of files Default: 1 0.625 0.625 difference_2 colour used to identify differences between the second pair of files Default: 0.85 0.625 0.775 difference_3 colour used to identify differences between the third pair of files Default: 0.85 0.775 0.625 edited colour used to indicate edited lines Default: 0.5 1 0.5 hatch colour used for indicating alignment gaps Default: 0.8 0.8 0.8 line_number colour used for line numbers Default: 0 0 0 line_number_background background colour for the line number area Default: 0.75 0.75 0.75 line_selection colour used to indicate selected lines Default: 0.7 0.7 1 map_background background colour for the map area Default: 0.6 0.6 0.6 margin colour used to indicate the right margin Default: 0.8 0.8 0.8 preedit pre-edit text colour Default: 0 0 0 text regular text colour Default: 0 0 0 text_background background colour for the text area Default: 1 1 1 float name value Declares a floating point resource called name with value value. The following floating point resources are used by &app;: alignment_opacity opacity used when compositing the manual alignment colour Defaults: 1 character_difference_opacity opacity used when compositing character difference colours Defaults: 0.4 character_selection_opacity opacity used when compositing the character selection colour Defaults: 0.4 edited_opacity opacity used when compositing the edited line colour Defaults: 0.4 line_difference_opacity opacity used when compositing line difference colours Defaults: 0.3 line_selection_opacity opacity used when compositing the line selection colour Defaults: 0.4 syntax name initial_state default_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 be initial_state. All characters not matched by a pattern will be tagged as default_tag for highlighting. The syntax style called name can be removed by omitting initial_state and default_tag. syntax_files name pattern Specifies that files with a name matching pattern should be highlighted using the syntax style called name. Patterns used to match files for use with the syntax style called name can be removed by omitting pattern. syntax_magic name pattern ignorecase Specifies that files with a first line matching pattern should be highlighted using the syntax style called name. Patterns used to match files for use with the syntax style called name can be removed by omitting pattern. syntax_pattern name initial_state final_state tag pattern 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 to final_state if the pattern defined by pattern is matched. Case insensitive pattern matching will be used if ignorecase is specified. All characters matched by the pattern will be tagged as tag for highlighting. The following files are used by &app;: /etc/diffuserc system wide initialisations (%INSTALL_DIR%\diffuserc on Microsoft Windows) /usr/share/diffuse/syntax/*.syntax syntax files for various languages (%INSTALL_DIR%\syntax\*.syntax on Microsoft Windows) ~/.config/diffuse/diffuserc your initialisations (%HOME%\.config\diffuse\diffuserc on Microsoft Windows) ~/.config/diffuse/prefs your saved preferences (%HOME%\.config\diffuse\prefs on Microsoft Windows) ~/.local/share/diffuse/state data persistent across sessions (%HOME%\.local\share\diffuse\state on Microsoft Windows)