@DATABASE "gdiff" @MASTER "gdiff.guide" @NODE "MAIN" "gdiff" @TOC "MAIN" gdiff A graphical frontend to diff and diff3 Copyright (C) 2001-2002 Stefan Burstrom @{"Introduction" LINK "INTRODUCTION"} @{"Copyright and disclaimer" LINK "COPYRIGHT"} @{"Requirements" LINK "REQUIREMENTS"} @{"Installation" LINK "INSTALLATION"} @{"Usage" LINK "USAGE"} @{"Troubleshooting" LINK "TROUBLESHOOTING"} @{"Future" LINK "FUTURE"} @{"Acknowledgements" LINK "ACKNOWLEDGEMENTS"} @{"History" LINK "HISTORY"} @ENDNODE @NODE "INTRODUCTION" "Introduction" @NEXT "COPYRIGHT" @TOC "MAIN" Introduction ============ Ever wondered what the difference between 2 text files are, or wanted to merge 3 textfiles, but found the output from diff and diff3 hard to read ? Use this tool as a graphical frontend to simplify this! This software is released as email-improvements-ware. If you use it, please think of any improvements that might be useful for you or others. If you can't find any (hehe) feel free to send any other comments. If you really want to contribute, I suggest you buy iBrowse which is the real reason why this program was created. The author, Stefan Burstrom, can be reached via email at: f94sbu@efd.lth.se or stefan@ibrowse-dev.net @ENDNODE @NODE "COPYRIGHT" "Copyright and disclaimer" @NEXT "REQUIREMENTS" @PREV "INTRODUCTION" @TOC "MAIN" Copyright and disclaimer ======================== Permission is granted to make and distribute copies of this software provided the copyright notice and this permission notice are preserved on all copies. COPYRIGHT Copyright (C) 2001-2002 Stefan Burstrom No program from this software package, neither in whole nor in part, may be included or used in other software packages unless it is authorized by a written permission from the author. NO WARRANTY There is no warranty for this software package. Although the author has tried to prevent errors he can't guarantee that the software package described in this document is 100% reliable. You are therefore using this material at your own risk. The author cannot be made responsible for any damage which is caused by using this software package. DISTRIBUTION This software is freely distributable. It may be transfered to any media which is used for the distribution of free software like Public Domain disk collections, CDROMs, FTP servers or bulletin board systems. In order to ensure the integrity of this software package, distributors should use the original archive file gdiff.lha. The author cannot be made responsible if this software package has become unusable due to modifications of the archive contents or of the archive file itself. There is no limit on the fee taken by distributors, e.g. for the media costs of floppy disks, streamer tapes or compact discs, or the process of duplicating. Such limits have proven to be harmful to the idea of freely distributable software, e.g. the software package was removed instead of reducing the price of a floppy disk below the limit. Although the author does not impose any limit on these fees he would like to express his personal opinions on this matter: * This software package should be made available to everyone free of charge whenever this is possible. * If you have purchased this software package under normal conditions from a Public Domain dealer on a floppy disk and have paid more than US $5 then you have definitely paid too much. Please don't support this improper profit making any longer, and switch to a cheaper source as soon as possible. @ENDNODE @NODE "REQUIREMENTS" "System requirements" @NEXT "INSTALLATION" @PREV "INTRODUCTION" @TOC "MAIN" System Requirments ================== Any Amiga running OS3.0+, that has MUI and GNU diffutils compatible diff and diff3 programs installed. NOTE: The diff program included with SAS/C (6.50) does not work since its output is not compatible with diffutils. gdiff has successfully been tested with * Geekgadgets GNU-diffutils 2.6 * Geekgadgets GNU-diffutils 2.7 ( Aminet: diffutils-bin.lha for latest version ) * Heinz Wrobels port of GNU-diffutils ( Aminet: HWGdiffP1_2_6.lha ) Also, some text files that appears to be different would be good... @ENDNODE @NODE "INSTALLATION" "Installation" @NEXT "USAGE" @PREV "REQUIREMENTS" @TOC "MAIN" Installation ============ Copy the files gdiff and gdiffimages.iff to a location somewhere in your path. Also, make sure that diff and diff3 are accessable from from your shell. If not, you can edit the path for them in the preferences. @ENDNODE @NODE "USAGE" "Usage" @NEXT "FUTURE" @PREV "INSTALLATION" @TOC "MAIN" Usage ===== Simpy run gdiff from the Shell as you would invoke diff or diff3. eg. gdiff myfile.txt yourfile.txt gdiff myfile.txt originalfile.txt yourfile.txt gdiff -m myfile.txt originalfile.txt yourfile.txt >output.txt gdiff MERGE myfile.txt originalfile.txt yourfile.txt output.txt gdiff will detect if you are using it as diff3 (eg. with the -m option) or as a standard AmigaDOS command. If you do not specify an output file, the result will be sent to standard out if you 'save' your merges. When the main window has opened, it may consist of 2, 3 or 4 text displays. If you passed 2 files, the 2 files will be displayed side by side with the differences highlighted. If you supplied 3 files, the files will be displayed side by side. The middle file is considered to be the 'base' file. Additionally, if you specify merge (-m or the MERGE keyword) the merged result will be displayed above the 3 original files. There is no actual difference in how the data from the 3 original files are interpreted. The only difference is that the original file will never have any lines marked as 'deleted'. Also, if there is a difference, the original file is marked as the 'original' text while the other 2 are marked as 'changed' text. The merged output is based on which files contain the changes. If file 1 and 2 contains the same line, and file 3 contains another one, file 3 is used for the merged output. If all 3 files differ, this is considered as a merge conflict and no default choice is made. Please consult the diff and diff3 documentation for additional info on how to handle differences between text files. Settings handling ================= gdiff will save its current settings to env: every time you exit. Use Save settings to save them permanently to envarc: Main window =========== Depending on which of the 3 different ways gdiff has been started, the following elements may appear: Buttons: 'Resolved mergepoints: nn' The number of differences where gdiff has been able to make a choice by itself 'Unresolved mergepoints: nn' The number of conflicting differences. You can not save the result before this number is 0 '|<' Move to the first difference. '<<' Move to the previous unresolved difference. '<' Move to the previous difference. '|' Center the views around the currently selected difference. '>' Move to the next difference. '>>' Move to the next unresolved difference. '>|' Move to the next difference. '1' For the current difference, select file 1 as the choice. If another file(s) is already selected, the lines from file 1 will be appended after the other file(s). If you deselect this, the additions from file 1 will be removed from the merged view. Depending on your preferences, the other 2 selections for this difference may also be deselected. '2' For the current difference, select file 2 as the choice. If another file(s) is already selected, the lines from file 2 will be appended after the other file(s). If you deselect this, the additions from file 2 will be removed from the merged view. Depending on your preferences, the other 2 selections for this difference may also be deselected. '3' For the current difference, select file 3 as the choice. If another file(s) is already selected, the lines from file 3 will be appended after the other file(s). If you deselect this, the additions from file 3 will be removed from the merged view. Depending on your preferences, the other 2 selections for this difference may also be deselected. 'Save' Save your merged file Merge view: This view is displayed above the 3 file views if the merge option has been chosen. The left part of the text displays the properties of the different parts of the text. The different properties may be: Red arrow: The current selected difference. You may select a different one simply by clicking on another one or by using the navigation buttons or menus. If you double click on a difference, all views will center around this difference. Gray arrow: A difference between the files. Blue checkmark: A resolved difference. If neither file is selected as the merged result for a difference, the result is considerd unresolved. You cannot save before all differences are resolved. Additionally, the text '<<< difference resolved - line(s) deleted >>>' or '<<< merge needed >>>' may appear. They will of course not be saved in the final result. File view: This view displays one of the original files. Above each view, the filename is displayed. The full path of the file is displayed in a help bubble if you hold the mouse above the filename. The left part of the view displays the properties of the different parts of the text. The different properties may be: Green checkmark: A difference has been detected, and this part is considered as the original text. Yellow triangle: A difference has been detected, and this part is considered as the modified text. An 'a' with a small red triangle under it. A difference has been detected where lines were added, and these are the added ones. An 'a' with a red cross over it. A difference has been detected where lines were deleted, and these are the deleted ones. A dashed rectangle A difference has been detected where lines were added in one of the other files, and this shows the spot where they were added. A line that extends vertically below any of the above symbol indicates that the change extends for several lines. Finally, a blue mark to the very left indicates that this is the current selected change. The appearance of the text with the different properties may be changed in the settings. Settings window =============== You may select the properties for the different texts here, aswell as selecting the font to use. If no font is selected, gdiff will use the font configured for fixed width listviews in MUI. The graphics are designed for a 12pt font, but it will of course work with any size font. Finally, you can edit the commands used to invoke diff and diff3. Normally you should not need to modify these. If you do, you need to include %t, %1, %2 and %3 somewhere in the string. %t is the temporary file where the result from diff/diff3 is read and %1 %2 and %3 are the 3 files. There are 2 different 'themes' to select from the menus. Default is a selection based on the pens selected on the Workbench. The 'ClearCase' theme matches the look of the commercial package ClearCase by Rational Software Corp. (from where the graphics are borrowed from aswell ;) Menus ===== Project: Save Save the merged file. gdiff will quit after saving the file. Merge If you are vieing the difference between 3 files without running gdiff with the merge option, gdiff will transform into gdiff -m. If you select 'Save' gdiff will output the result to standard out. Refresh Reload the viewed files. Iconify Iconify the window(s). About Display About information. About MUI Display About MUI information. Quit Exit without saving. Merge Select file 1 Same as pressing the '1' button Select file 2 Same as pressing the '2' button Select file 3 Same as pressing the '3' button Select all unmerged from 1 Select file 1 for all unmerged changes Select all unmerged from 2 Select file 2 for all unmerged changes Select all unmerged from 3 Select file 3 for all unmerged changes Navigation First difference Move to the first difference. Previous unmerged difference Move to the previous unresolved difference. Previous difference Move to the previous difference. Current difference Center the views around the currently selected difference. Next difference Move to the next difference. Next unmerged difference Move to the next unresolved difference. Last difference Move to the next difference. Settings Deselect merge choice deselects the other 2 choices Try it :-) Force file 1 if conflict is detected Next time gdiff tries to merge 3 files, it will default to file 1 in all cases where there is a merge conflict. NB. file 2 and 3 may of course still be chosen if there is no conflict. Force original file if conflict is detected Next time gdiff tries to merge 3 files, it will default to file 2 in all cases where there is a merge conflict. NB. file 1 and 3 may of course still be chosen if there is no conflict. Force file 2 if conflict is detected Next time gdiff tries to merge 3 files, it will default to file 3 in all cases where there is a merge conflict. NB. file 1 and 2 may of course still be chosen if there is no conflict. Use file notification in input files When gdiff is run, it will set up a file notify on the input files. If any of them change, gdiff will rerun diff or diff3. Deselect this option and use 'Refresh' instead if you think that this is too slow on your system if you save the files often. Settings Open the settings window MUI Settings Open the MUI settings window Reset settings Reset the GUI and menu settings Restore settings The last saved settings will replace the current one Save settings Saves the settings to ENVARC: Examples ======== Try: gdiff MERGE examples/sb.c examples/orig.c examples/db.c gdiff examples/sb.c examples/db.c @ENDNODE @NODE "TROUBLESHOOTING" "Troubleshooting" @NEXT "FUTURE" @PREV "USAGE" @TOC "MAIN" Troubleshooting =============== Most errors that can be generated are caused by non GNU diffutils compatible programs. SAS/C diff does not work. Also problems will of course occur if no diff or diff3 is installed at all. In this case 'unable to open output file' will be the error. gdiff has successfully been tested with * Geekgadgets GNU-diffutils 2.6 * Geekgadgets GNU-diffutils 2.7 ( Aminet: diffutils-bin.lha for latest version ) * Heinz Wrobels port of GNU-diffutils ( Aminet: HWGdiffP1_2_6.lha ) If everything else fails, you can always contact the author... @ENDNODE @NODE "FUTURE" "Future" @NEXT "ACKNOWLEDGEMENTS" @PREV "TROUBLESHOOTING" @TOC "MAIN" Future ====== Based on your input, this program might actully get improved. Feel free to email me suggestions or bug reports at: f94sbu@efd.lth.se These are the following improvements I have planned: * Possibility to edit the merged data before saving it. * Faster refresh of the views * Help bubble support for the different text properties * Possibility to merge 2 files also. This can currently be done by specifying the same file for file 1 and file 2 of course * Mark only the changed parts within a line as different * Option to ignore changes in whitespaces @ENDNODE @NODE "ACKNOWLEDGEMENTS" "Acknowledgements" @NEXT "HISTORY" @PREV "FUTURE" @TOC "MAIN" Acknowledgements ================ Oliver Roberts - For testing this software during its development David Burström - For testing this software under low stack conditions Stefan Stuntz - For his excellent GUI toolkit Magic User Interface Dave Fisher - For helping me with the manual Free Software - For encouraging the development of GNU diffutils Foundation Rational Software - For not sueing me for borrowing some graphics from your ClearCase suite And finally I would like to dedicate this piece of work to my friend Michael, who recently died in a very tragic skydiving accident. May you live on forever in our memories together with our dream of flight! @ENDNODE @NODE "HISTORY" "History" @PREV "ACKNOWLEDGEMENTS" @TOC "MAIN" History ======= v1.0 - First public release Monday 07-Jan-02 v0.10 - unreleased - Sunday 06-Jan-02 v0.9 - unreleased - Friday 04-Jan-02 Initial version released @ENDNODE