VCS UI Spec
This document is a user interface specification of Version Control System (VCS) functionality in NetBeans IDE.
Authors: Jan Rojcek, Richard Gregor
$Revision: 1.24 $
$Date: 2005/10/06 14:55:44 $
Changes: available in CVS
Table of Contents:
- Introduction
- Scenarios
- Specification
Introduction
The user interface of VCS functionality in NetBeans IDE currently isn't well integrated with new project system (introduced in NetBeans Promotion D). The user model of VCS functionality also doesn't support very well the most common use cases performed frequently when using VCS. In this specification we improve the user model and user interface involved in the most common and frequent VCS use cases.
VCS Use Cases are summarized in a separate document: VCS Use Cases in New Project System.
Scenarios
Checkout Sources
This scenario covers the following use cases:
- VCS-1.1: Get Multiple Dependent Projects (Application)
- VCS-1.2: Get Independent Project
- VCS-1.3: Get Required Project
- VCS-1.4: Get Library
- VCS-1.5: Get Branched Project
- VCS-2.1: Get Sources of Application
- VCS-2.2: Get Sources of Application Module
- VCS-2.3: Get Branched Sources
To achieve those use cases, the user needs to know what CVS modules or folders she needs to checkout. The IDE doesn't try to find project's external sources, nor track the project dependencies.
The scenario:
- User invokes main menu item CVS | Checkout... and Checkout Wizard pops up.
- In the first step of Checkout wizard, the user specifies CVS root, password and optionally proxy connection.
- In the second wizard step, the user selects a module (or alias) to checkout and target location. Optionally also specifies branch to checkout from.
- A progress indication appears in the status line and when the checkout finishes, it shows up an information alert giving the user choice of opening an existing NetBeans project or creating a new one from checked out sources.
Configure Project to Use CVS
This scenario covers the following use cases:
In those use cases, all source folders and libraries are on a local disk underneath a folder already containing CVS folder containing CVS metadata. In case of 2.5 also the project folder is underneath such folder. In 2.4, the user needs to create a project from existing sources (or ant script) and make sure that the project folder is put underneath a folder that already contains CVS folder. If that is satisfied, then CVS functions in IDE are enabled automatically. No special setup is required.
Put Project into CVS
This scenario covers the following use cases:
Scenario A:
- The user has the projects underneath a folder that already contains CVS metadata. In such case all CVS actions are already available on project files.
- User selects projects he/she wants to put into CVS.
- Invokes main menu item CVS | Commit <name>... and Commit Dialog pops up.
- In the Commit dialog, the user specifies commit message and clicks the Commit button.
Scenario B:
- The user doesn't have the projects underneath a folder that contains CVS metadata. Therefor the commit action is not available.
- User selects 1 project he/she wants to put into CVS.
- Invokes main menu item CVS | Import into Repository... and Import into Repository wizard pops up.
- In the first step of import wizard, the user specifies CVS root, password and optionally proxy connection.
- In the second wizard step, the user selects a local folder to import and repository folder as target location. Optionally the user can specify that the imported folder should be checked out after the import to make CVS actions available on imported files.
- A progress indication appears in the status line after finishing the wizard.
Update Project
This scenario covers the following use cases:
This use case isn't fully covered as all projects the user wants to update have to be open. It is currently impossible to update required projects together with selected projects.
The scenario:
- User selects projects he/she wants update.
- Invokes main menu item CVS | Update <name>....
- A progress bar appears in the status line. When the update finishes and there are conflict merges due to the update, the Versioning Window shows up showing the local changes of the updated projects, which means the conflicting files in this case. If there are no conflicts, the Versioning Window doesn't shows up.
Commit Project Changes
This scenario covers the following use cases:
The scenario:
- User selects projects containing modified files he/she wants to commit.
- Invokes main menu item CVS | Show <name> Changes . A Versioning Window opens showing the difference between the projects in the repository and local project copy.
- Clicks a Diff toolbar button in the Versioning Window and a Diff Window opens showing the difference between local and repository files.
- Uses Next Difference and Previous Difference toolbar buttons in the Diff window to navigate between the differences.
- Clicks Update toolbar button in the Versioning window, which gets the remote changes from the repository.
- Invokes Clean and Build for sanity checking the build.
- Clicks Commit toolbar button in the Versioning window which opens a Commit Dialog.
- In the Commit dialog, the user specifies the commit message and clicks the commit button.
Specification
Main Menu
The VCS functionality is accessible from the CVS menu, which is located between Run and Tools menus.| CVS | | CVS | (disabled labels) ------- ------- Show All Changes Show All Changes Diff All Files Diff All Files Update All Files Update All Files Commit All Files... Commit All Files... -------------------------------------------------- --------------------------------- Checkout... Checkout... Import into Repository... Import into Repository... -------------------------------------------------- --------------------------------- Update "<project>" with Dependencies Update Project with Dependencies -------------------------------------------------- --------------------------------- Show "<project-or-folder-or-file>" Changes Show Changes Diff "<project-or-folder-or-file>" Diff Update "<project-or-folder-or-file>" Update Commit "<project-or-folder-or-file>"... Commit... -------------------------------------------------- --------------------------------- Export "<project-or-folder-or-file>" Diff Patch... Export Diff Patch... -------------------------------------------------- --------------------------------- Tag "<project-or-folder-or-file>"... Tag... Branches > Branches > -------------------------------------------------- --------------------------------- Show "<file>" Annotations Show File Annotations Search "<project-or-folder-or-file>" History... Search History... -------------------------------------------------- --------------------------------- Revert "<project-or-folder-or-file>" Modifications Revert Modifications Resolve "<project-or-folder-or-file>" Conflicts Resolve Conflicts Ignore "<folder-or-file>" (Unignore) Ignore
Menu items behavior:
- Show All Changes - opens the Versioning window showing the list of modified files between the local copy of all files in all projects and repository. Disabled if no project is versioned.
- Diff All Files - opens the Diff window showing the source code differences of all modified files in all projects. Disabled if no projects is versioned.
- Update All Files - updates the local copy of all projects with repository changes and opens the Versioning window if a conflict merge occurs. Disabled if no projects is versioned.
- Commit All Files - commits the project changes in all projects into the repository. Disabled if no projects is versioned.
- Checkout - opens the Checkout wizard. Always enabled.
- Import into Repository - opens the Import into Repository wizard. Always enabled.
- Show "<project-or-folder-name>" Changes - opens the Versioning window showing the list of modified files between the local copy of all files in all projects and repository. If multiple items are selected it says Show File Changes. If no project or folder is selected it is disabled and it says Show Changes.
- Diff "<project-or-folder-or-file-name>" - opens the Diff window showing the source code differences of all selected modified files. If multiple items are selected then the menu item says Diff Files. It no project nor folder nor file is selected then the menu item is disabled and label changes to Diff.
- Update "<project-or-folder-or-file-name>" - updates the local copy of selected items with repository changes and opens the Versioning window if a conflict merge occurs. If multiple items are selected then the menu item says Update Files . It no project nor folder nor file is selected then the menu item is disabled and label changes to Update.
- Commit "<project-or-folder-or-file-name>" - opens the Commit dialog for committing selected files into the repository. If multiple items are selected then the menu item says Commit Files. It no project nor folder nor file is selected then the menu item is disabled and label changes to Commit.
- Export "<project-or-folder-or-file-name>" Diff Patch - opens up a file chooser titled Export Diff Patch with Export and Cancel buttons. The file type combo box says Diff Files. The initial location is the user home and initial file name is <project-or-folder-or-file-name>.diff. Clicking the Export button saves the diff file to specified location.
- Tag "<project-or-folder-or-file-name>" - see Branches UI Spec.
- Branch "<project-or-folder-or-file-name>" - see Branches UI Spec.
- Show "<file-name>" Annotations - see History UI Spec.
- Search "<project-or-folder-or-file-name>" History - see History UI Spec.
- Revert "<project-or-folder-or-file-name>" Modifications - opens up a confirmation alert titled Revert Modifications with Revert and Cancel buttons. The message says "Reverting modifications will overwrite selected files with their repository version. Are you sure you want to revert modifications?". Enabled only if selected file is modified or selected folder contains modified files.
- Resolve "<project-or-folder-or-file-name>" Conflicts - opens up Conflict Resolver which is not redesigned in this UI spec.
- Ignore "<folder-or-file-name>" - marks selected files and/or folders as ignored. If only ignored files are selected, then the menu item changes to Unignore.
- Unignore "<folder-or-file-name>" - clears the ignore mark on selected files.
Checkout Wizard
The Checkout Wizard allows the user to perform VCS-1: Get New NetBeans Project from VCS and VCS-2: Get New Sources from VCS use cases.
Step 1: CVS Root
In the first step the user specifies CVS Root. Depending on the specified connection method, the wizard dynamically changes components for additional connection parameters like password, proxy, etc.
Figure: CVS Root wizard panel
+---------------------------------------------------------------------------------+ | Checkout | +---------------------------------------------------------------------------------+ | CVS Root | | ------------------------------------------------------------------------------- | | | | Specify location of CVS repository defined by CVS Root. | | | | CVS Root: |_:pserver:annoncvs@cvs.netbeans.org:/cvs_____________v_| [ Edit... ] | | | | IDE directly supports following CVS root types: | | | | :pserver:username@hostname:/repository_path | | for connecting to CVS pserver repository | | :ext:username@hostname:/repository_path | | for connecting to CVS repository using SSH | | | | Following types require external cvs command: | | | | :fork:/repository_path | | for protocol access to local CVS repository | | :local:/repository_path | | for direct access to local CVS repository | | | | | +---------------------------------------------------------------------------------+
Components of this wizard step are:
- CVS Root editable combo box (R) - specifies the CVS root. The combo box contains values taken from passwd file. The recently used CVS root is selected initially. If the combo is empty, the text field is empty as well. In such case, the wizard shows description text as displayed in the figure. If the user types connection method into the text field (e.g. :pserver:) additional components show up in the panel.
- Edit button (R) - opens the Edit CVS Root dialog.
Wizard buttons' behavior:
- Back button - always disabled.
- Next button - enabled if a valid CVS root is specified. After pressing the Next button a progress bar appears at the bottom of the panel. If the connection is successful then the wizard moves to the next step. If the connection fails, a Connection Failed inline error message appears at the position of the progress bar.
- Finish button - always disabled.
Figure: CVS Root wizard panel (:pserver:)
+---------------------------------------------------------------------------------+ | Checkout | +---------------------------------------------------------------------------------+ | CVS Root | | ------------------------------------------------------------------------------- | | | | Specify location of CVS repository defined by CVS Root. | | | | CVS Root: |_:pserver:annoncvs@cvs.netbeans.org:/cvs_____________v_| [ Edit... ] | | (:pserver:username@hostname:/repository_path) | | | | Password: |_____________________________| | | | | [ Proxy Configuration... ] | | | | | +---------------------------------------------------------------------------------+
Components of this wizard step are:
- Password text field (P) - specifies the password used with the CVS root.
- Proxy Configuration... (C) - opens the Proxy Configuration dialog. Always enabled.
Figure: CVS Root wizard panel (:ext:)
+---------------------------------------------------------------------------------+ | Checkout | +---------------------------------------------------------------------------------+ | CVS Root | | ------------------------------------------------------------------------------- | | | | Specify location of CVS repository defined by CVS Root. | | | | CVS Root: |_:ext:annoncvs@cvs.netbeans.org:/cvs_________________v_| [ Edit... ] | | (:ext:username@hostname:/repository_path) | | | | (o) Use Internal SSH | | | | Password: |_________________________| [ ] Remember Password | | | | [ Proxy Configuration... ] | | | | ( ) Use External SSH | | | | SSH Command: |______________________________________________| [ Browse... ] | | | | | +---------------------------------------------------------------------------------+
Components of this wizard step are:
- Use Internal SSH check box (I) - specifies that internal ssh is used for connection.
- Password text field (P) - specifies the password used with SSH.
- Remember Password check box (m) - if selected the password is stored.
- Proxy Configuration... (C) - opens the Proxy Configuration dialog. Always enabled.
- Use External SSH (E) - if selected external ssh command is used for connection.
- SSH Command text field (S) - specifies path to SSH command used for connection.
- Browse SSH Command (B) - opens a file chooser titled Browse SSH Command with OK and Cancel buttons. The file type combo contains label Applications.
Figure: CVS Root wizard panel (:fork:)
+---------------------------------------------------------------------------------+ | Checkout | +---------------------------------------------------------------------------------+ | CVS Root | | ------------------------------------------------------------------------------- | | | | Specify location of CVS repository defined by CVS Root. | | | | CVS Root: |_:fork:/usr/local/cvsroot____________________________v_| [ Edit... ] | | (:fork:/repository_path) | | | | | | | | | +---------------------------------------------------------------------------------+
Figure: CVS Root wizard panel (:local:)
+---------------------------------------------------------------------------------+ | Checkout | +---------------------------------------------------------------------------------+ | CVS Root | | ------------------------------------------------------------------------------- | | | | Specify location of CVS repository defined by CVS Root. | | | | CVS Root: |_:local:/usr/local/cvsroot___________________________v_| [ Edit... ] | | (:local:/repository_path) | | | | | | | | | +---------------------------------------------------------------------------------+
Figure: CVS Root wizard panel (connection progress bar)
+---------------------------------------------------------------------------------+ | Checkout | +---------------------------------------------------------------------------------+ | CVS Root | | ------------------------------------------------------------------------------- | | | ... ... ... | | | Connecting to CVS Repository... | | |///////////////////////_____________________________________________| [ Stop ] | | | +---------------------------------------------------------------------------------+
Components of this wizard step are:
- Connecting to CVS Repository progress bar (-) - shows up after pressing the Next button if the user selected pserver or ext connection method. All components and labels in the wizard panel are disabled when the progress is on (except the progress bar, connecting label and stop button).
- Stop button (S) - shows up together with the progress bar after pressing the Next button. Clicking the stop button terminates connection, enables components and labels in the dialog and dismisses the progress bar, connecting label and stop button. Always enabled.
Inline error messages:
- Connection failed. - if connection to CVS repository fails after pressing the next button.
Dialog: Edit CVS Root
Figure: Edit CVS Root dialog (:pserver:)
+---------------------------------------------------------------------------------+ | Edit CVS Root | +---------------------------------------------------------------------------------+ | | | Access Method: |_pserver_____v_| | | | | User: |___________________| | | Host: |_________________________________________| Port: |__________| | | Repository Path: |_________________________________________| | | | | | | [ OK ] [ Cancel ] | +---------------------------------------------------------------------------------+
Figure: Edit CVS Root dialog (:ext:)
+---------------------------------------------------------------------------------+ | Edit CVS Root | +---------------------------------------------------------------------------------+ | | | Access Method: |_ext_________v_| | | | | User: |___________________| | | Host: |_________________________________________| Port: |__________| | | Repository Path: |_________________________________________| | | | | | | [ OK ] [ Cancel ] | +---------------------------------------------------------------------------------+
Figure: Edit CVS Root dialog (:fork:)
+---------------------------------------------------------------------------------+ | Edit CVS Root | +---------------------------------------------------------------------------------+ | | | Access Method: |_fork________v_| | | | | Repository Path: |_________________________________________| | | | | | | [ OK ] [ Cancel ] | +---------------------------------------------------------------------------------+
Figure: Edit CVS Root dialog (:local:)
+---------------------------------------------------------------------------------+ | Edit CVS Root | +---------------------------------------------------------------------------------+ | | | Access Method: |_local_______v_| | | | | Repository Path: |_________________________________________| | | | | | | [ OK ] [ Cancel ] | +---------------------------------------------------------------------------------+
Dialog: Proxy Configuration
In this dialog the user specifies proxy settings used with CVS actions. The proxy settings are persisted between IDE sessions and checkout wizard sessions.
Figure: Proxy Configuration dialog
+---------------------------------------------------------------------------------+ | Proxy Configuration | +---------------------------------------------------------------------------------+ | | | (o) Use System Proxy Settings | | ( ) No Proxy | | ( ) HTTP Proxy | | ( ) Socks 5 Proxy | | | | Proxy Host: |_______________________________________| Port: |___________| | | | | [ ] Proxy Server Requires Password | | Name: |_______________________________________| | | Password: |_______________________________________| | | | | [ OK ] [ Cancel ] | +---------------------------------------------------------------------------------+Components of this dialog are:
- Use System Proxy Settings radio button (U) - specifies that the proxy setting retrieved from the operating system should be used.
- No Proxy radio button (N) - specifies that no proxy should be used.
- HTTP Proxy radio button (H) - specifies that HTTP proxy should be used. Selecting the checkbox enables the host, port and other fields for specifying the proxy details.
- Socks 5 Proxy radio button (S) - specifies that HTTP proxy should be used. Selecting the checkbox enables the host, port and other fields for specifying the proxy details.
- Proxy Host text field (H) - specifies HTTP or Socks proxy host. Initially empty. Enabled only if HTTP Proxy or Socks 5 Proxy radio button is selected.
- Port text field (P) - specifies HTTP or Socks proxy host. Initially empty. Enabled only if HTTP Proxy or Socks 5 Proxy radio button is selected.
- Proxy Server Requires Password check box (S) - specifies that the name and password should be used when using the proxy server. Enabled only if HTTP Proxy or Socks 5 Proxy radio button is selected. Initially it is unselected.
- Name text field (m) - specifies the proxy account name. Initially empty. Enabled only if the Proxy Server Requires Password check box is selected.
- Password text field (w) - specifies the proxy password. Initially empty. Enabled only if the Proxy Server Requires Password check box is selected.
- OK button - Closes the dialog and sets up the proxy. Always enabled.
- Cancel button - Closes the dialog without setting up the proxy. Always enabled.
Step 2: Module to Checkout
This step asks the user to specify CVS modules or repository folders to checkout.
Figure: CVS Modules to Checkout wizard panel
+---------------------------------------------------------------------------------+ | Checkout | +---------------------------------------------------------------------------------+ | Module to Checkout | | ------------------------------------------------------------------------------- | | | | Specify the CVS module and branch to checkout from CVS repository. | | | | Module: |_______________________________________________________| [ Browse... ] | | (empty means all modules) | | Branch: |_______________________________________________________| | | | | | | Specify location of local folder to checkout modules into. | | | | Local Folder: |_________________________________________________| [ Browse... ] | | (local CVS working directory) | | | | | +---------------------------------------------------------------------------------+
Components of this wizard step are:
- Module text field (M) - specifies the module or alias to checkout from the repository.
- Browse (Modules) button (w) - opens up the Browse CVS Module dialog.
- Branch text field (B) - specifies the branch to checkout the modules from.
- Local Folder text field (L) - specifies the CVS working directory. This value is persisted between IDE and wizard sessions.
- Browse (Local Folder) button (s) - opens up a file chooser titled Browse Local Folder with OK and Cancel buttons and the Files of Type combo containing one value Folders.
Wizard buttons' behavior:
- Back button - always enabled.
- Next button - always disabled.
- Finish button - enabled if Local Folder contains a valid folder name.
Inline error messages:
- Local Folder isn't a valid folder name. - if the Local Folder contains invalid characters.
Dialog: Browse CVS Module
This dialog allows the user browsing the CVS repository and select an alias, folder or project folder to checkout. The project folder icons are badged with project icon badge. The multi-selection is allowed.
Figure: Browse CVS Module dialog
+-----------------------------------------+ | Browse CVS Module | +-----------------------------------------+ | Repository Contents: | | +-------------------------------------+ | | |[A] Aliases | | | | -- [a] all | | | | -- [a] standard | | | | -- [a] stable | | | |[F] /repository/path | | | | -- [f] petstore | | | | +- [p] petstore | | | | +- [p] petstorelib | | | | +- [p] petstorelib2 | | | | -- [f] sharedlib | | | | +- [p] parser | | | | +- [p] dbconnect | | | | | | | +-------------------------------------+ | | | | [ OK ] [ Cancel ] | +-----------------------------------------+ [A] - parent alias icon [a] - alias icon [F] - repository icon [f] - folder icon [p] - project folder iconComponents of this dialog are:
- Repository Contents tree (F) - shows module aliases and permits to browse for specific folder in CVS repository.
- OK button (S) - Closes the dialog and returns selected module. This is the default button. Enabled only if a folder or alias is selected in Repository Contents tree.
- Cancel button - Closes the dialog without returning a folder or alias. Always enabled.
Alert: Checkout Completed
This information alert shows up after the successful checkout offering the user to open a project or create a new one.
Figure: Checkout Completed alert (NetBeans project was found)
+-----------------------------------------------------------------------+ | Checkout Completed | +-----------------------------------------------------------------------+ | | | | <x> projects were checked out. | | | Do you want to open a checked out project? | | o | | | | | | [[ Open Project... ]] [ Close ] | +-----------------------------------------------------------------------+Figure: Checkout Completed alert (No NetBeans project was found)
+-----------------------------------------------------------------------+ | Checkout Completed | +-----------------------------------------------------------------------+ | | | | No project was found in checked out sources. | | | Do you want to create a new project from checked out sources? | | o | | | | | | [[ Create Project... ]] [ Close ] | +-----------------------------------------------------------------------+Components of this alerts are:
- Open Project button (O) - opens up the Open Project dialog.
- Create Project button (C) - opens up the New Project wizard.
- Close button (-) - closes the dialog.
Import into Repository Wizard
Step 1: CVS Root
Figure: CVS Root wizard panel
+---------------------------------------------------------------------------------+ | Import into Repository | +---------------------------------------------------------------------------------+ | CVS Root | | ------------------------------------------------------------------------------- | | | | Specify location of CVS repository defined by CVS Root. | | | | CVS Root: |_:pserver:annoncvs@cvs.netbeans.org:/cvs_____________v_| [ Edit... ] | | | | IDE directly supports following CVS root types: | | | | :pserver:username@hostname:/repository_path | | for connecting to CVS pserver repository | | :ext:username@hostname:/repository_path | | for connecting to CVS repository using SSH | | | | Following types require external cvs command: | | | | :fork:/repository_path | | for protocol access to local CVS repository | | :local:/repository_path | | for direct access to local CVS repository | | | | | +---------------------------------------------------------------------------------+
Behavior of this wizard step is identical to Checkout wizard.
Step 2: Folder to Import
In this step the user specifies local folder to import into repository and location of repository folder to import into.
Figure: Folder to Import wizard panel
+---------------------------------------------------------------------------------+ | Import into Repository | +---------------------------------------------------------------------------------+ | Folder to Import | | ------------------------------------------------------------------------------- | | | | Specify the local folder to import into CVS repository. | | | | Folder to Import: |____________________________________________| [ Browse... ] | | | | Vendor Tag: |_________________| | | Release Tag: |_________________| | | Import Message: +--------------------------------------------+ | | | | | | | | | | +--------------------------------------------+ | | | | | | Specify the repository folder to import the local folder into. | | | | Repository Folder: |_/__________________________________________| [ Browse... ] | | | | [x] Checkout after Import | | | +---------------------------------------------------------------------------------+
Components of this wizard step are:
- Folder to Import text field (I) - specifies the local folder to import into repository. Initial value is the current project folder. If there is no current project then the field is empty.
- Browse Folder to Import button (B) - opens up a file chooser titled Browse Folder to Import with OK and Cancel buttons and the Files of Type combo containing one value Folders. If the Folder to Import text field is empty then the file chooser open in the location where the user stores projects. If this location is not known yet, then it opens in user home.
- Vendor Tag text field (V) - required field.
- Release Tag text field (T) - required field.
- Import Message text field (M) - required field.
- Repository Folder text field (R) - specifies the repository folder to import the local folder into. Initial value is the repository root (/).
- Browse Repository Folder button (w) - opens up the Browse Repository Folder dialog.
- Checkout after Import check box (C) - if selected those files that will be imported are checked out from the repository to the same location.
Dialog: Browse Repository Folder
Figure: Browse Repository Folder dialog
+-----------------------------------------+ | Browse Repository Folder | +-----------------------------------------+ | Repository Folders: | | +-------------------------------------+ | | |[F] /repository/path | | | | -- [f] petstore | | | | +- [p] petstore | | | | +- [p] petstorelib | | | | +- [p] petstorelib2 | | | | -- [f] sharedlib | | | | +- [p] parser | | | | +- [p] dbconnect | | | | | | | +-------------------------------------+ | | | | [ OK ] [ Cancel ] | +-----------------------------------------+ [F] - repository icon [f] - folder icon [p] - project folder icon
Projects Window
The Projects window allows the user to perform versioning commands on versioned projects, folders (containers) and files. A project is versioned if at least one folder in the project is versioned. A folder is considered versioned if it contains CVS metadata or its parent is versioned. And file is versioned if its parent folder is versioned.
The Projects window shows the local status of files comparing against the repository. The local status means whether a file has changed locally since the last update or checkout. Files can be in four local states (up-to-date, new, ignored, containing conflict) which are indicated by different colors of node labels. The same colors are used in editor tab labels. Project and folder (or container) icons indicate that they are versioned and also the state of files underneath by versioning badge.
File name colors and corresponding states:
- Default color - file is up-to-date
- Green color - file not yet in the repository (Locally New)
- Blue color - file has been modified (Locally Modified)
- Red color - file contains a conflicting merge (Local Conflict)
- Gray color - file is ignored
Folder name colors and corresponding states:
- Default (black) color - folder is not ignored (can contain default, green, red and gray color files)
- Gray color - folder is ignored (all files and folders underneath this folder are ignored as well)
- No badge - project is not in CVS
- Black color badge - project is versioned and all files are up-to-date
- Blue color badge - project contains new or modified files (Locally New or Locally Modified)
- Red color badge - project contains at least one file with conflicting merge (Local Conflict)
Folder icon badge colors for versioned project and corresponding states:
- No badge - folder files are up-to-date
- Blue color badge - project contains new or modified files (Locally New or Locally Modified)
- Red color - folder contains at least one file with conflicting merge (Local Conflict)
Figure: VCS File Name Colors in Projects Window
+-------------------------------------------------+ | Projects | +-------------------------------------------------+ | [a] My Java App | | -- [j] Source Packages | | | -- [p] <default package> | | | | +- [c] MyClassInDefaultPackage.java | | | -- [e] com.mycompany.newpackage | | | -- [p] com.mycompany.petstore | | | | +- [b] Bundle.properties | (Ignored) | | | +- [c] Main.java | (Locally Modified) | | | +- [c] Petstore.java | (Up to Date) | | | +- [c] PetstoreApp.java | (Locally New) | | | +- [c] PetstoreData.java | (Local Conflict) | | +- [p] com.mycompany.petstore.api | | | +- [p] com.mycompany.petstore.lib | | | +- [p] com.mycompany.petstore.ui | | -- [t] Test Packages | | +- [p] com.mycompany.petstore | | +- [p] com.mycompany.petstore.api | | +- [p] com.mycompany.petstore.lib | | +- [p] com.mycompany.petstore.ui | | [a] My Java Lib | | +- [j] Source Packages | | +- [t] Test Packages | | | | | | | | | +-------------------------------------------------+ [a] - Versioned Project icon [j] - Source Packages logical folder icon [t] - Test Packages logical folder icon [p] - Java Package icon [e] - Java Package empty icon [j] - Java File icon [b] - Properties File icon
Figure: VCS Badges in Projects Window
Node: Project
Project node contextual menu:
... ---------------------------- CVS > Tools > ---------------------------- Properties
CVS submenu (project is in a repository or underneath a versioned folder):
CVS > Show Changes Diff Update Update with Dependencies Commit... ----------------------------- Tag... ----------------------------- Branch... Switch to Branch... Merge Changes from Branch... ----------------------------- Search History... ----------------------------- Revert Modifications Resolve Conflicts
CVS submenu (project is not in a repository nor underneath a versioned folder):
CVS > Import into Repository...
Node: Folder
Folder node contextual menu:
... ---------------------------- CVS > Tools > ---------------------------- Properties
CVS submenu:
CVS > Show Changes Diff Update Commit... ----------------------------- Tag... ----------------------------- Branch... Switch to Branch... Merge Changes from Branch... ----------------------------- Search History... ----------------------------- Revert Modifications Resolve Conflicts Ignore (Unignore)
Node: File
File node contextual menu:
... ---------------------------- CVS > Tools > ---------------------------- Properties
CVS submenu:
CVS > Diff Update Commit... ----------------------------- Tag... ----------------------------- Branch... Switch to Branch... Merge Changes from Branch... ----------------------------- Show Annotations Search History... ----------------------------- Revert Modifications Resolve Conflicts Ignore (Unignore)
Versioning Window
Versioning window initially appears docked at the position of Output window. It is open either from the Window menu or after Show Changes action invoked on projects, folders or files. If the window is invoked from the Window menu for the first time then it behaves like if it was invoked after Show All Changes action. Thus it shows the status of all open projects. If it is open from the window menu next time, it shows the status of previous objects (projects, folders, files).
The Versioning window shows the user a subset of project files that aren't up-to-date with the repository. It shows locally changed files, remotely changed files or both depending on the selected view. Individual files shown in the Versioning window can have local, remote or conflicting status. The local status represents local changes. The remote status represents remote changes. And the conflicting status represents compatible or incompatible changes made locally and remotely since the last updated on the same file.
The local status is shown with gray, green and blue color file names, the remote status with black and conflicting status with red color file names. follows the description of individual file states:
- Conflicting Status (red):
- Local Conflict - file already contains a conflict from a previous merge.
- Locally/Remotely Modified - file has been modified locally and also in the repository. The merge might cause conflict.
- Local Status:
- Locally Deleted (gray) - file is in the repository and will be removed from the repository during next commit.
- Locally New (green) - file is not in the repository.
- Locally Modified (blue) - file is in the repository and has been modified locally.
- Remote Status (black):
- Remotely Deleted - file has been removed from the repository since the last update.
- Remotely New - file is new in the repository since the last update.
- Remotely Modified - file has been modified in the repository.
Figure: Versioning window showing one project after invoking the Show Changes action on Petstore project ordered by Status
+--------------------------------------------------------------------------------------------------+ | Versioning - Petstore (10 minutes ago) | +--------------------------------------------------------------------------------------------------+ | [ All ] [ Local ] [ Remote ] | [ R ] [ D ] [ U ] [ C ] | |--------------------------------------------------------------------------------------------------| |______________File________________|_______Status______v_|________________Location_________________| | Bundle.properties | Local Conflict | petstore/src/com/mycompany/petstore | | MyClassInDefaultPackage.java | Local Conflict | petstore/src/com/mycompany | | Main.java | Locally/Remotely Mod| petstore/src/com/mycompany/petstore | | Project.properties | Locally/Remotely Mod| petstore/nbproject | | PetstoreApplicationForm.java | Locally Deleted | petstore/src/com/mycompany/petstore | | PetstoreApp.java | Locally New | petstore/src/com/mycompany/petstore | | PetstoreLib.java | Locally Modified | petstorelib/src/com/mycompany/petlib | | PetstoreApplication.java | Remotely Deleted | petstore/src/com/mycompany/petstore | | PetstoreData.java | Remotely New | petstore/src/com/mycompany/petstore | | PetstoreAppTest.java | Remotely Modified | petstore/test/com/mycompany/petstore | | | | | | | | | +--------------------------------------------------------------------------------------------------+
Figure: Versioning window on Windows Classic L&F
Components of this window are:
- Versioning title bar - shows the name of the objects (projects, folders, files) the Show Changes action was invoked on. The name pattern is Versioning - <object-name>. If the Show Changes action was invoked on multiple objects then the title bar shows the number of objects: Versioning - <x> Objects.
- All toggle button - if selected all files (local, remote and conflicting) are shown in the table. If no changes are available it shows No Local/Remote Changes label centered in the table. Tooltip: Shows remote and local changes since last update. Always enabled.
- Local toggle button - if selected only local and conflicting files are shown in the table. If no changes are available it shows No Local Changes label centered in the table. Tooltip: Shows local changes since last update. Always enabled.
- Remote toggle button - if selected only remote and conflicting files are shown in the table. If no changes are available it shows No Remote Changes label centered in the table. Tooltip: Shows remote changes since last update. Always enabled.
- R (Refresh Status) button - refreshes the status of versioned objects (projects, folders, files) shown in the Versioning window. Button tooltip is Refresh Status. Always enabled.
- D (Diff) button - opens the Diff window
in the editor. Depending on the selected toggle button (Local, Remote, All) it
show the following difference:
- All - shows what has changed in the repository and locally since the last update. Includes files in the local, remote and conflicting file state. For conflicting files which changed in the repository and locally, shows 2 diffs in the diff view.
- Local - shows what the user has changed locally since the last update (difference between the current local file state and the last updated file state). Includes files in the local and conflicting file state.
- Remote - shows what has changed in the repository since the last update (difference between the current remote file state and the last update file state). Includes files in the remote and conflicting file state.
- U (Update) button - invokes the update action on the versioned objects (projects, folders, files) shown in the Versioning window. Button tooltip is Update "<object-name>" where the object name is the same as object name shown in the title bar of versioning window. Always enabled.
- C (Commit) button - invokes the commit action on the files shown in the Versioning window. Button tooltip is Commit "<object-name>" where the object name is the same as object name shown in the title bar of versioning window. Always enabled.
- Changes table - shows the files that has changed in the
repository and locally since the last update.
- File table column - shows the icon and file name of files that aren't up-to-date with the repository or local copy. Label is in gray, red, green, blue or black color depending on the file state (see above).
- Status table column - shows the status of files in the table. The status is describe above.
- Location table column - shows the folder path of files in the table starting from the top level versioned folder
Contextual Menu: File Node
Open ------------------- Diff (default action) Update Commit... -------------------- Tag... Branch... -------------------- Show Annotations Search History... -------------------- Exclude from Commit (Include in Commit) Revert Modifications (Revert Delete)(Delete) Ignore (Unignore)
Diff Window
The diff window shows the difference between projects, folders or files.
Figure: Diff window showing the difference between the current remote revision of Main.java and last update copy
------------------- / Petstore [ Diff ] \ +------------------------------------------------------------------------------------------------+ | [ Remote vs Local ] [ Local ] [ Remote ] | |_Main.java______v_| [ N ] [ P ] [ R ] [ U ] [ C ] | |------------------------------------------------------------------------------------------------| |______Remotely Modified 1.8 (Based on 1.7)______|_________Locally Modified (Based on 1.7)_______| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | +------------------------------------------------------------------------------------------------+
Figure: Diff Window on WinXP L&F
Figure: File Combo Box on WinXP L&F
Components of this window are:
- Remote vs Local toggle button - if selected, all files (conflicting, local and remote) are shown in the file combo box. The diff component shows local modifications for locally changed files, remote modifications for remotely changed files and difference between remote and local files for files changed locally and/or remotely. Tooltip: Shows remote and local changes since last update. Always enabled.
- Local toggle button - if selected, only local changed files are shown in the file combo box. The diff component shows local modifications since the last update or checkout. Tooltip: Shows local changes since last update. Always enabled.
- Remote toggle button - if selected, only remote changed files are shown in the file combo box. The diff component shows remote modifications since the last update or checkout. Tooltip: Shows remote changes since last update. Always enabled.
- File combo box - contains the list of differing files. The list items depend on the selected toggle button.
- N (Next Difference) button - scrolls the diff view to the next difference (cycles over all files). Keyboard shortcut is F12. Always enabled.
- P (Previous Difference) button - scrolls the diff view to the previous difference (cycles over all files). Keyboard shortcuts is Shift-F12. Always enabled.
- R (Refresh Diff) button - refreshes the diff of all files shown in the Diff window. Button tooltip is Refresh Diff. Always enabled.
- U (Update) button - invokes the update action on the versioned objects (projects, folders, files) shown in the Diff window. Button tooltip is Update "<object-name>" where the object name is the same as object name shown in the title bar of diff window. Always enabled.
- C (Commit) button - invokes the commit action on the files shown in the Diff window. Button tooltip is Commit "<object-name>" where the object name is the same as object name shown in the title bar of diff window. Always enabled.
- Diff component - shows the actual difference between revisions. Titles of the diff view sides indicate specific versions that are compared. The following table shows the titles for different view type and file status:
View Type File Status Left View Title Right View Title Remote vs Local Locally/Remotely Modified Remotely Modified X.B (Based on X.A) Locally Modified (Based on X.A) Local Conflict Base (X.A) Local Conflict (Based on X.A) Locally New No Base Revision Locally New Locally Deleted Base (X.A) Locally Deleted Locally Modified Base (X.A) Locally Modified (Based on X.A) Remotely New No Base Revision Remotely New X.A Remotely Deleted Base (X.A) Remotely Deleted Remotely Modified Base (X.A) Remotely Modified X.B (Based on X.A) Local Locally/Remotely Modified Base (X.A) Locally Modified (Based on X.A) Local Conflict Base (X.A) Local Conflict (Based on X.A) Locally New No Base Revision Locally New Locally Deleted Base (X.A) Locally Deteted Locally Modified Base (X.A) Locally Modified (Based on X.A) Remote Locally/Remotely Modified Base (X.A) Remotely Modified X.B (Based on X.A) Remotely New No Base Revision Remotely New X.A Remotely Deleted Base (X.A) Remotely Deleted Remotely Modified Base (X.A) Remotely Modified X.B (Based on X.A)
Commit Dialog
In the Commit dialog the user specifies the commit message and selects the type of commit action for each file.
Figure: Commit dialog
+------------------------------------------------------------------------------------------------+ | Commit - Petstore | +------------------------------------------------------------------------------------------------+ | | | Commit Message: | | +--------------------------------------------------------------------------------------------+ | | | | | | | | | | | | | | | | | | +--------------------------------------------------------------------------------------------+ | | | | Files to Commit: | | |______________File____________|____Status_____v__|_Commit Action_|_________Location_________| | | | PetstoreApplicationForm.java | Locally Deleted | Remove | petstore/src.../petstore | | | | PetstoreApp.java | Locally New | Add as Text | petstore/src.../petstore | | | | PetstoreApp.jpg | Locally New | Add as Binary | petstore/src.../petstore | | | | Bundle.properties | Locally Modified | Commit | petstore/src.../petstore | | | | Main.java | Locally Modified | Commit | petstore/src.../petstore | | | | PetstoreLib.java | Locally Modified | Commit | petstorelib/nb.../petlib | | | | Project.properties | Locally Modified | Exclude from C| petstore/nbproject | | | | | | | | | | +--------------------------------------------------------------------------------------------+ | | | | [[ Commit ]] [ Cancel ] | +------------------------------------------------------------------------------------------------+
Components of this dialog are:
- Commit Message table (C) - specifies the commit message.
- Files to Commit table (F) - shows the files that has changed in the
repository and locally since the last update.
- File table column - shows the icon and file name of files that aren't up-to-date with the repository or local copy. Label is in gray, red, green or blue color depending on the file state (see above). The values are read-only.
- Status table column - shows the local status of file to commit. It can be one of following: Local New, Local Deleted, Local Modified. The values are read-only.
- Commit Action table column - specifies the commit action depending on the file status. It can be one of the following: Add as Text, Add as Binary, Remove, Commit, Exclude from Commit. The user can choose the commit action for each file using the inline combo box.
- Location table column - shows the parent folder of file.
- Commit button - performs the commit and closes the dialog. Enabled if a commit message isn't empty.
- Cancel button - closes the dialog without performing the commit.
Connection Alert
Figure: Connection Alert (:pserver:)
+------------------------------------------------------------------------------+ | <CVS-process-name> | +------------------------------------------------------------------------------+ | | | | Connection Failed! | | | Cannot connect to CVS repository using CVS root: | | o :pserver:user@host:/repository | | | | The following problem(s) occured: | | o No route to host | | | | Check password and proxy configuration. | | | | Password: |_____________________________| | | | | [ Proxy Configuration... ] | | | | | | [ Retry ] [ Cancel ] | +------------------------------------------------------------------------------+
Figure: Connection Alert (:ext:)
+------------------------------------------------------------------------------+ | <CVS-process-name> | +------------------------------------------------------------------------------+ | | | | Connection Failed! | | | Cannot connect to CVS repository using CVS root: | | o :ext:user@host:/repository | | | | The following problem(s) occured: | | o No route to host | | | | Check password and proxy configuration. | | | | (o) Use Internal SSH | | | | Password: |_________________________| [ ] Remember Password | | | | [ Proxy Configuration... ] | | | | ( ) Use External SSH | | | | SSH Command: |_________________________________| [ Browse... ] | | | | | | [ Retry ] [ Cancel ] | +------------------------------------------------------------------------------+
