DIFF Specification
Author: Josef Pavlicek
$Revision: 1.32 $
$Date: 2007/01/18 15:13:23 $
$Id: DIFFSpecification.html,v 1.32 2007/01/18 15:13:23 josefpavlicek Exp $ (see full CVS history)
Content
- Requirements
- Goals
- Used terms
- The current NetBeans DIFF design
- The redesign of NetBeans DIFF
- Open issues
- Appendix
Requirements
Motivation
Motivation of the DIFF Specification is to improve current NetBeans DIFF. This version is not able to cover the main Use Cases (read here). To improve DIFF functionality is necessary in the future.
Goals
To improve NetBeans DIFF functionality.
Used terms
- CVS = for purpose of this paper we will understand some common system for controlling versions of files like Source Safe and other.
- DIFF = differences between two objects
- could be between files or directories
- Local (base) = If the user updated from CVS file (these terms are used for directory too) according to model Picture 1, it is the file in version 1,2
- Local = the user's local file. This file the user can edit.
- Remote = file if is located in the CVS server in the last version. On the Picture 1 it is file version 1,4
- Local Non CVS base = the file which is selected by the user like base. If the user doesn't use CVS, he/she can use private
- private directory and file system (file server)
- FTP server
- etc
and he/she can need diff files between his/her Local Non CVS base and particular file on the other place on:
- Hard Disc
- Flash Disc
- etc
Picture 1: Explanation of terms Local versus Remote etc. in CVS and other source control system
The current NetBeans DIFF design
The current Figure 1 NetBeans DIFF design is not able to cover all main Use Cases(read here).
Figure 1: The current design of the NetBeans DIFF
The redesign of NetBeans DIFF
According to collected DIFF Use Cases, the new design of NetBeans Diff should allows these functionality:
NOTE: Bold points are realized in this specification!
- Diff files
- Local (base) versus Local file
- Local Non CVS base versus Local
- Remote versus Local file
- Remote versus Remote
- For Diff files the system has to
- show differences navigator in the error stripe
- allow to edit diffed Local file
- allow to save the Local file
- to allow accept particular differences from Local /Remote (base)
- to allow accept all differences from Local /Remote (base)
- Distinguished differences
- Modified (light blue)
- New (light green)
- Deleted (light red)
- Highlighting part of diffed code (by light blue color)
- Diff directories
(not realized in this spec - it is open issue)
- Local (base) versus Local
- Local (selected local base NON CVS) versus Local
- Remote versus Local
- Remote versus Remote
- distinguishes differences
- new directory/file
- modified directory/file
- deleted directory/file
- Inline DIFF
- The system allows the user to see differences between Local (base) versus Local directories
- Conflict solving
- Diff for more files in the one time
- All functionality like Editor has
- for example Undo function etc.
On the Figure 2 is a new design of NetBeans DIFF. This design is valid for DIFF Files from CVS. Figure 2.1 describes new changes compared to actual DIFF viewer.
Figure 2: The new version of NetBeans DIFF design (the new Diff viewer has to have spline curves like the Figure 5)
Figure 2.1: Detail description of new DIFF viewer for files
List of functionality:
Choose working mode:
Remote versus Local (the tooltip on the first button is Remote vs local) ,
Local versus Local (the tooltip on the second button is Local vs local),
Remote versus Remote (the tooltip on the third button is Remote vs remote),
- in this state is not possible to edit both files.
Choose of diff file:
- the combo box allows the user choose the file for Diff. The path behind of the name of file is written from right to left. If the path is longer than the place in the combobox, the system shows ellipses.
- For example:
- The file chooser has tooltip with all path for the file.
Diff navigation pointers:
These pointers allow the user move between differences. The user can use short cut F12 - go down, Shift + F12 - go to UP - Figure 2.9, Figure 3.5.
This pointer allows the user move all differences from the base file to local file. This functionality is similar with the Rollback function.
This pointer allows the user move particular difference from base to local file.
This icon allows the user remove the new code from the local file
Commit file:
This button allows the user commit the local file.
Diff viewer legend:
The system shows the user count of differences.
-
The system shows the user name of the diffed files. On the left side is always base file, on the right side is always local file.
DIFF viewer
The new diff viewer allows the user new functionality like you can read in the Figure 2.1. These functionality depend on the Diff Use Cases. We can collect them:
- Choose working mode:
Remote versus Local (the tooltip on the first button is Remote vs local) ,
Local versus Local (the tooltip on the second button is Local vs local),
Remote versus Remote (the tooltip on the third button is Remote vs remote),
- in this state is not possible to edit both files.
- The system allows the user to see:
- The system shows the name of the file.
- The system shows the color of the diffed file,
- All path for the file.
- This path is written behind of the name of diffed file,
- If the path is longer like the size of combo box, the system shows the tooltip on the mouse over via the combo box, with all path,
- The user can to select the diffed file. The path of the file is key for recognizing of the particular diffed file.
- While the user works, the system shows him/her the current differences (if the user goes via navigation pointers or by mouse click) in the center of the diff viewer.
- position of the user cursor (on which difference the user is now) / count of differences in the file=> Diff 1 / 2.

- The system shows the user on which differences he/she is in the particular time by changing the color of the pointers
,
and by the differences navigator Figure 2.7 .
- On mouse over the system changes the color of this button too.

- if the user moves his/her cursor (or if he/she moves on the first differences by some key shortcut F12) the system changes the color of the pointer
( Figure 2.3). This icon is align to center of edge bar between left Base file and right Local file. If the user shows on it by pointer of mouse the system shows tooltip
.
- the system moves differences from left to right.
- if is (are) in the left window some green (inserted) rows, the system remove it (them).
- after this action the left frame has the same content like the right frame. This functionality is similar like roll back function.
- This pointer is not visible, if the user selected Remote vs Remote mode. In this mode is not possible to edit right file.
to Insert (for deleted rows - Figure 2.5) or Replace (for changed rows - Figure 2.4) particular differences (modified and deleted) from left - base file to right - > local file,
- The user can move the differences by drag and drop (drag from left to right),
- The system allows the user to use F12 and for keyboard navigation and if he/she press the enter, the system moves the differences from left to right,
- See on the Figure 2.4 ,Figure 2.5.
Remove particular differences (only for inserted code) from the local file. If the user is on this part of code or if he/she moves by pointer of mouse (mouse over) over that, the system changes the color of the Remove button
.
- The user can press it and remove this code from the local file.
- The system allows the user to use the keyboard navigation
by the F12 shortcut.
- if the user is on it and press Enter, the system removes the code from the file.
- See on the Figure 2.6.
- If the difference is only in some part of code, the system highlights the different word (Figure 2) - first differences.
- Light blue for modified code
- Light red for deleted code
- Light green for inserted code
- If is particular differences "active" - the user is on the particular row, the system fill the rectangle by correct color.
- Notice: All colors are similar with current diff colors. We didn't changed them.
NOTICE: The Diff viewer allows the Undo function like allows the Editor (for Win.XP - Ctrl+Z)
Figure 2.3: Accept all differences
Figure 2.4: Replace the particular difference
Figure 2.5: Insert current difference
Figure 2.7: Detail of Error stripe and Differences navigator
Figure 2.8: Detail of the Diff viewer frames
The Figure 2.8 shows the detail of the Diff viewer frames. All colors are:
- for edge lines of the Diff viewer is used default color like for others edge lines in windows,
- the double dashed line has the same color like diff viewer edge lines,
- the line which separates white body of the base line and edge line of the diff viewer has similar color like has the line, separates the white body of editor and first left slide bar line. You can use the color inside the light-gray square. It's Similar color,
- The defined size of frames depends on the default settings of NetBeans. It is valid for default NetBeans font. If the user changes the font size from current to bigger size, the size should be bigger. The font (with "Base" text for example) has to have minimally 4 pixels from each side space. Especially from top and down edge lines.
Figure 2.9: This figure shows the differences navigation menu items in the Navigation menu.
Description of figure 2.9:
If the user works with the Diff viewer, he/she can use the navigation short cuts instead of the pointer. The short cuts are placed on the main toolbar - Navigation menu item.
Inline DIFF
This chapter describes the inline diff viewer. It is light version of the Diff viewer. The system shows the user (Figure 3):
- modified rows,
- new rows,
- deleted rows.
And allows the user to:
- see the changes,
- rollback the changes,
- commit the edited file,
- instead of that the inline diff has all functionality like the normal NetBeans Editor,
NOTICE: The Inline diff allows the Undo function like allows the Editor (for Win.XP - Ctrl+Z)
List of fuctionalities of the dynamic tooltip
Dynamic tooltip (Figure 3.2) is visible until the user moves his/her pointer of mouse inside boundaries of the dynamic tootip. If the user clicks outside or presses some other button outside, the dynamic tooltip disappears. The dynamic tooltip has:
,
pointer button for moving on prev/next differences in the file. The user can use short cut F12 - go down, Shift + F12 - go to UP,Figure 3.5.
- if prev. of next differences doesn't exist, the pointer is gray and non active
rollback button (pointer back)
- if the user clicks on this button the system inserts the code shown in the body of dynamic tooltip. If is the difference a new code (light green - Figure 3.2), the system removes this code from the file
diff viewer button
- if the user press on this button, the system shows the user DIFF viewer over this file and moves the user cursor on the particular differences in the Diff viewer
Inline DIFF description
For the purpose of the Inline diff is necessary to increase gap between the rows counter and foldings component from particular size to 12 pixels. The Diff component will be added into this gap.
The user chan recognize the type of differences thanks:
- inline diff highlighting ,
- light blue, red, green rectangles and triangles between the rows counter and foldings component,
- by click on the each highlighted differences (Figure 3.2, 3.3, 3.4) ,
- if the user clicks on one of them, the system activates the pointer on the editor toolbar and shows dynamic tooltip for current differences,
- The user can use short cut F12 - go down, Shift + F12 - go to UP (it is dsigned for Editor toolbar pointers too) Figure 3.5,
- or the pointers on the top toolbar,
- or pointers in the dynamic toolbar in each differences,
- or moves on the change by pointer of mouse or by pointer on the top toolbar,
- the system shows the difference dynamic tooltip.
Figure 3.1: Inline diff - other details
Figure 3.2: Inline diff - deleted row highlighting
Figure 3.3: Inline diff - modified highlighting
Figure 3.4: Inline diff - new row highlighting
Figure 3.5: Inline diff menu (navigation)
Conflict solving tool description
If more of users work on the one file together, sometimes can happen that the committed local file is in the conflict with the file on the server (See on the DiffUseCases.html). The Picture 2 shows how the conflict can grow up. We need to have some tool which can solve the conflict problem.
Picture 2: Conflict solving explanation
Figure 4: Conflict solving tool
Figure 4.1: Conflict solving tool detail description
The list of functionality of Conflict solving tool
If the system finds some conflicted file, offers the user possibility to solve it. The system opens the Conflict solving tool (Figure 4). And allows the user to solve the problem.
- The Conflict solving tool has only right frame editable
- this frame has similarly functionality like in the Diff Viewer
- The user can choose which file he/she wants to solve by toogle button on the top head of the left frame.
- The system allows the user:
- Replace the conflict rows from base file to the local file or:
- Resolved , that the particular difference is right in the local file, by check the button
(non active)
(acitve) located in the right frame. The systems shows for this burtton tooltip -> "Resolved".
- The system allows the user to save the file by the button
.
- If he/she press it the system saves the file and changes the background of the button on gray.
- If the user does some changes, the save button starts to be active again
- If he/she press it the system saves the file and changes the background of the button on gray.
NOTICE: The Problem solving tool allows the Undo function like allows the Editor (for Win.XP - Ctrl+Z).
Click here for download of DIFF ICONS.
Open issues for design
This part of specification will be added:
- diff more files together
- diff viewer for Refactoring
- Dir Diff
- Diff of local (non base) files
- conflict solving tool
- diff viewer for local (non base) files
Appendix
I received the suggestion for variant diff viewer design - especially different color design. If we will implemented this color design, the all functionality will be the same like is described in the spec. Only the colors can be similar like the Figure 5.
Figure 5: The different color design of diff viewer
Figure 5.1 Alternative diff viewer - function design
Alternative design like the reader can read on the Figure 5.1 I designed according to requests for Local History tool. Is useful to have diff viewer and conflict solving tool similar like tools for Local History and manual merge and other tools. This part of spec will be updated according these specifications. If we change the design of the DIFF viewer and instead of the combo box for selection of diffed files use the table like in the Figure 5.1 the other design pictures (from figure 2 to figure 4) I will not change. The design and system behavior will be similar like is described in the spec, except the file selection combo box.
If the user call diff function by right click on the project tree or by other way, the system shows the user the Diff viewer deigned on the Figure 5.1. The system shows by default 4 rows in the table on the top of the diff viewer. If are more files here, the system shows the user scrollbar on the right side of the table.
The table contains column:
- Name of the file,
- State of the file,
- new
- deleted
- modified
- Full path for the file. The path of the file is written from right to left. If the path is longer than the place in the table row, the system shows ellipses.