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
  • DIFF viewer
  • Inline DIFF
  • Conflict solving tool description
  • Other open issues for design
• 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:

1. Remote versus Local (the tooltip on the first button is Remote vs local) ,
2. Local versus Local (the tooltip on the second button is Local vs local),
3. Remote versus Remote (the tooltip on the third button is Remote vs remote),
   1. in this state is not possible to edit both files.

Choose of diff file:

1. - 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.
2. For example:
3. The file chooser has tooltip with all path for the file.

Diff navigation pointers:

1. 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.
2. This pointer allows the user move all differences from the base file to local file. This functionality is similar with the Rollback function.
3. This pointer allows the user move particular difference from base to local file.
4. This icon allows the user remove the new code from the local file

 

Commit file:

1. This button allows the user commit the local file.

Diff viewer legend:

1. The system shows the user count of differences.
2. 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:

1. Choose working mode:
   1. Remote versus Local (the tooltip on the first button is Remote vs local) ,
   2. Local versus Local (the tooltip on the second button is Local vs local),
   3. Remote versus Remote (the tooltip on the third button is Remote vs remote),
      1. in this state is not possible to edit both files.
2. The system allows the user to see:
   1. The system shows the name of the file.
   2. The system shows the color of the diffed file,
   3. All path for the file.
      1. This path is written behind of the name of diffed file,
      2. 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,
      3. The user can to select the diffed file. The path of the file is key for recognizing of the particular diffed file.
   4. 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.

 

The NetBeans IDE shows the count of differences in the DIFF Counter. The form of the counter is:

1. position of the user cursor (on which difference the user is now) / count of differences in the file=> Diff 1 / 2.

If the user works with the NetBeans diff, he/se can commit the file. That is a reason, why we have the commit button on the edge of diff - .

The system allows the user Move (Figure 2.3), Replace (Figure 2.4), Insert (Figure 2.5) differences from base file into the local file:

1. 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 .
2. On mouse over the system changes the color of this button too.

The system allows the user Move all differences from left (Base file) to local file . He/she can use double pointer button located in the center column between the diff frames .If the user clicks on this button, the system moves all differences from the base file to local file (from left to right).

• 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.

On the each differences is located special button. This button allows:

1. 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.
2. 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.

The system shows the user the modified word in the code (Figure 2)

1. If the difference is only in some part of code, the system highlights the different word (Figure 2) - first differences.

The system shows error stripe (Figure 2.7) .

The system shows in the error stripe differences navigator

1. Light blue for modified code
2. Light red for deleted code
3. Light green for inserted code
4. 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.6: Remove 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)

Figure 3. Inline DIFF

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

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.