CrossWorks has a source control integration capability that can be used on the files of a CrossWorks project. The capability is implemented by a number of different source control providers, however the set of functions that are provided by CrossWorks aim to be provider independent. The source control integration capability provides:
- Connecting to the source control database (sometimes called a repository) and mapping files in the project to those in source control.
- Showing the source control status of files in the project.
- Adding files in the project to source control. This operation is called Add To Source Control.
- Fetching files in the project from source control. This operation is called Get Latest Version.
- Locking and unlocking files in the project for editing. The lock operation is called Check Out. The unlock operation is called Undo Check Out. These operations are optional for some source control providers.
- Comparing a file in the project with the latest version in source control. This operation is called Show Differences.
- Merging a file in the project with the latest version in source control with reference to the original version. This operation is called Merge and requires an external three-way merge tool.
- Committing changes made to files in the project into source control. This operation is called Check In.
Configuring the source control system
The source control system you are using must be enabled using:
- Select Tools | Options menu item.
- Selecting the Source Control category in the options dialog.
- Setting Source Control Provider to the appropriate provider.
- Setting the source control provider specific options.
- Setting Enable Source Code Control Integration to Yes.
The source control provider information is stored in the CrossWorks global environment, so you can only use one provider for all of your CrossWorks projects.
Connecting to the source control system
You must connect to the source control system for each different CrossWorks project you have. To connect to the source control system, do the following:
- From the Project menu, click Source Control then Connect...
This displays a source control system login dialog that enables you to specify your username, password and select the source control database to connect to. These details will be saved in the session file (the password is enciphered) so that you don't need to repeat this information each time the project is loaded.
To map files in the project to those in the source control system, you need to specify a local root directory and the corresponding directory in source control (called the remote root). Once you have provided this information the files in your project that are within the local root directory are considered to be in (or can be added to) source control.
After the login dialog has completed you will be presented with a dialog that you use to specify the local and remote roots. The local root can be selected using a directory browser and the remote root can be selected using the source control explorer. With both browsers you can create new directories if you are starting a new project or you don't have an existing project in source control.
Opening a project from source control
To fetch a project that is already in source control to a local directory:
- From the Project menu, click Source Control then Open Solution From... This will show the login dialog and then the source control explorer.
- You should select a CrossWorks project file .hzp using the files list of the source control explorer.
- The mappings dialog will then be shown and you should use this to specify the local root directory i.e. where you want the project to go.
- A dialog showing the list of files to get from source control will be shown and then after confirmation these files are fetched and the project file is loaded into CrossWorks.
Source control status
Determining the source control status of a file can be an expensive operation. CrossWorks will do this when:
- A file node is selected by the project explorer.
- The source control status is displayed in the project explorer and the file node is visible in the project explorer.
- Before a recursive source control operation is used.
- After a source control operation has been used.
A file can be in one of the following states:
- Controlled - the file is in source control.
- Not Controlled - the file is not in source control.
- Checked Out - the file is checked out.
- Old - the file is older than the latest version in source control.
- Checked Out and Old - both of the above.
When the status is displayed in the project explorer if the file has been modified then the status is displayed in red. Note that if a file is not under the local root then it will not have a source control status.
You can reset any stored source control file status using the Project | Source Control | Refresh Status operation.
Source control operations
Source control operations can be performed on single files or recursively on multiple files in the project explorer hierarchy. Single file operations are available using the Source Control toolbar and also the right click menu of the text editor. All operations are available using the menu at Project | Source Control and on the Project Explorer right click menu. The operations are described in terms of the Project Explorer right click menu.
Adding files to source control
You can add a file in the project that is not in source control using:
- In the Project Explorer, right click on a file node.
- From the menu, click Source Control then Add To Source Control.
- Add a comment and select okay for the dialog box.
To add multiple files to the source control system do the following:
- In the Project Explorer, right click on a solution, project or folder.
- From the menu, click Source Control then Add To Source Control(Recursive).
- The dialog box will show the list of files that can be added i.e. ones that have a status of Not Controlled.
- In the dialog you can uncheck the ones you don't want to add to source control, add a comment and okay the dialog box.
Checking files out
To check out a file in the project from source control, do the following:
- In the Project Explorer, right click on a file node.
- From the menu, click Source Control then Check Out.
- Add a comment and select okay for the dialog box.
To check out multiple files in the project from source control, do the following:
- In the Project Explorer, right click on a solution, project or folder.
- From the menu, click Source Control then Check Out(Recursive).
- The dialog box will show the list of files that can be checked out i.e. ones that have a status of Controlled.
- In the dialog you can uncheck the ones you don't want to check out, add a comment and select okay for the dialog box.
Checking files in
To check in files in the project to source control, do the following:
- In the Project Explorer, right click on a file node.
- From the menu, click Source Control then Check In.
- Add a comment and select okay for the dialog box.
To check in multiple files in the project from source control, do the following:
- In the Project Explorer, right click on a solution, project or folder.
- From the menu, click Source Control then Check In(Recursive).
- The dialog box will show the list of files that can be checked in.
- In the dialog you can uncheck the ones you don't want to check in, add a comment and select okay for the dialog box.
Undoing Check Outs
To undo a check out of a file in the project, do the following:
- In the Project Explorer, right click on a file node.
- From the menu, click Source Control then Undo Check Out.
To undo check out of multiple files in the project, do the following:
- In the Project Explorer, right click on a solution, project or folder.
- From the menu, click Source Control then Undo Check Out(Recursive).
- The dialog box will show the list of files that can have undo check out in i.e. ones that have a status of Checked Out.
- In the dialog you can uncheck the ones you don't want to undo and select okay for the dialog box.
Get Latest Version
To get the latest version of a file in the project, do the following:
- In the Project Explorer, right click on a file node.
- From the menu, click Source Control then Get Latest Version.
To get the latest version of multiple files in the project, do the following:
- In the Project Explorer, right click on a solution, project or folder.
- From the menu, click Source Control then Get Latest Version(Recursive).
- The dialog box will show the list of files that can have undo check out in i.e. ones that have a status of Controlled, Checked Out or Old.
- In the dialog you can uncheck the ones you don't want to get and select okay for the dialog box.
Showing the differences between files
To show the differences between the file in the project and the version checked into source control, do the following:
- In the Project Explorer, right click on a file node.
- From the menu, click Source Control then Show Differences.
You can use an external diff tool if you have one installed in preference to the built-in CrossWorks diff tool. You define the diff command line CrossWorks generates using Tools | Options | Source Control | Diff Command Line - note that command line is defined as a list of strings to avoid problems with spaces in arguments. The diff command line can contain the following macros:
- $(localfile) The filename containing the file in the project.
- $(remotefile) The filename containing the latest version of the file in source control.
- $(localname) A display name for $(localfile).
- $(remotename) A display name for $(remotefile).
Merging files
To use merging you must have a merge tool installed. You define the merge command line CrossWorks generates using Tools | Options | Source Control | Merge Command Line - note that command line is defined as a list of strings to avoid problems with spaces in arguments. The merge command line can contain the following macros:
- $(localfile) The filename containing the file in the project.
- $(remotefile) The filename containing the latest version of the file in source control.
- $(commonfile) The filename containing the version of the file that you originally edited and the file which will be produced by the merge tool.
- $(localname) A display name for $(localfile).
- $(remotename) A display name for $(remotefile).
- $(commonname) A display name for $(commonfile).
To merge the file in the project and the version checked into source control, do the following:
- In the Project Explorer, right click the file node.
- From the menu, click Source Control then Merge.
- When the external tool has finished if $(commonfile) has been modified then you will be asked if you want to overwrite the file in the project with $(commonfile).
Source control explorer
By selecting the Project | Source Control | Show Explorer.. menu a dialog is displayed that lists the directories and files that are in source control. This dialog is used for selecting the remote root directory and when Project | Source Control | Open Solution From.. is selected.
You can use the directory side of the dialog to create new directories and to refresh the list if this is required by the source control provider.
Source control properties
When a file in the project is in source control, the Properties window shows the following properties in the Source Control Options group:
- Checked Out
- If Yes, the file is checked out by you to the project location; if No, the file is not checked out.
- Different
- If Yes, the checked out file differs from the one held in the source control system; if No, they are identical.
- File Path
- The file path of the file in the source control system.
- Local Revision
- The revision number/name of the local file.
- Old Version
- If Yes, the file in the project location is an old version compared to the latest version in the source control system.
- Provider Status
- The source control provider status of the file.
- Remote Revision
- The revision number/name of the most recent version in source control.
- Status
- The source control status of the file.