Kwxsync

The kwxsync command synchronizes issue status updates and comments, along with the ID of the user who made the changes, among projects that you specify. All of the updates are merged, so that identical issues in multiple projects have an identical history.

This is useful when projects share source code, as in the case of branches. Developers need to cite detected issues only once for each source file; kwxsync can then apply their changes to other projects that contain the same source file. You can also use the --storage option to run kwxsync incrementally; for more information, see the example below.

Note: We do not recommend using the --storage and --last-sync options together, as it may result in citing not synchronizing as expected.

The projects can be in different projects_root directories, as well as on different servers. A server is defined as a distinct combination of a machine name and a port number.

If you are using Working with streams, you can run kwxsync between an individual project and a base project in order to sync your defect citing, which syncs all the defects of the base project's streams as well.

Prerequisites

When you attempt to perform the synchronization, kwxsync proceeds only if the user has the permissions to do so on each of the specified machines. If the user does not have the proper permissions, the system will log a list of each of the machines on which it did not pass along with the user name that did not have the proper permissions, and the kwxsync process will exit.

When connecting to a machine that does not have an access control method in place, and where there is no entry for the target machine in the ltoken file, the name of the user that is logged into the machine that is running kwxsync will be used. Each project referenced in the kwxsync command-line has either an explicit URL (http://jsmith:8080/project_A) or an implicit URL (project_B). If a project has an implicit URL, its server and port are assumed to be the same server and port specified by the value of the --url parameter.

See Synchronizing status changes and comments across projects for how-to information.

Resolving status conflicts by using a status priority file

Between synchronizations, it is possible for multiple users to set different statuses on a single defect. This is more common in organizations that synchronize many projects and have a large number of users, but it can occur in any organization. Klocwork enables organizations to elegantly resolve status conflicts during synchronization by referencing a status priority file. Normally, during synchronization, the system uses the timestamps of each comment and status change to create a shared chronological history among the projects. The status with the most recent timestamp is the status applied across all projects. When you use the status priority option, if an issue has had multiple statuses set since the last synchronization, the system compares each of the statuses with the priorities specified in the file and if needed, applies the highest priority to the issue. Here's how it works:

1. A system administrator creates a status priority file that defines a numbered, or ranked, list of all issue statuses. This is the file that the system will use to resolve conflicts.
2. The build process or a system administrator runs the kwxsync command and includes the --status-priority file option. This command points to the location of the status priority file.
3. On a per-project basis, the system merges the status histories into a common history. If multiple statuses were applied to an issue after the last synchronization, the system logs each status and any associated comments based on their timestamps.
4. The system validates whether the last status applied has the highest priority as defined in the status priority file.
5. If the last status applied has the highest priority, the system does nothing. If the last status applied is lower than one of the other statuses it is resolving, the system changes the status of the issue so that the issue is tagged with the highest priority. The system then generates another entry and inserts it into the timeline. The timestamp of the system-generated entry is the timestamp of the previous status plus one second.
6. The system merges subsequent projects in the same manner until all projects are synchronized.

Within the status priority file, the lowest priority issue status has the lowest number and the highest priority issue status has the highest number. The status priority file must be a UTF-8 text file that

• contains no spaces or comments
• contains the name of the status in all-caps, followed by the equals sign and then the number, one status on each line
• assigns a unique number to each issue status, from 1 to 8

For example, if you create a file that contains the following syntax, the system will apply Fix as the final status when resolving a conflict with any other status:

FIX=8
FIX_IN_LATER_RELEASE=7
FIX_IN_NEXT_RELEASE=6
DEFER=5
FILTER=4
IGNORE=3
NOT_A_PROBLEM=2
ANALYZE=1

The following image shows the status history of an issue that was updated from "Defer" to "Fix" by kwxsync. Each time the system changes an issue status, it adds an entry to the history that includes "<kwxsync>" so that it is clear that the system changed the status during synchronization.

Usage

kwxsync [<options>] <project_name_1>|<project_URL_1> <project_name_2>|<project_URL_2> [...]

where <options> are any of the options from the table below

Specify a space-separated list of projects that you want to synchronize. All of the updates in all of the projects you specify will be merged, so that identical issues in all projects will have an identical history.

You can specify project names or project URLs. The project URL has the following format: http(s)://<klocwork_server_host>:<klocwork_server_port>/<project>

Use https:// if a secure Klocwork Server connection has been configured.

Example 1: Synchronizing projects on the same server

kwxsync Project1 Project2 --last-sync "03-04-2015 18:31:00"

In this example, only two projects are specified. The projects share a Klocwork Server that is running on the default host and port (localhost:8080), so we only need to specify the project names. kwxsync will find all issue status updates and comments applied since April 3, 2015 at 6:31 p.m. in Project1, and copy them to Project2; it will also do the same from Project 2 to Project 1.

Example 2: Synchronizing projects on multiple servers

kwxsync http://server01.acme.com:8080/Project1 http://server01.acme.com:8080/Project2 http://serverxyz.acme.com:8080/Project3 

In this example, we want to synchronize three projects, located on two Klocwork Servers. The easiest way to specify these projects is with the project URL, which clearly identifies the host, port and project name for each. kwxsync synchronizes the three projects, so that all identical issues in the projects share the same history. To perform the synchronization when authentication is enabled, the user running the command must be authenticated on all affected servers and must have the 'Perform cross-project synchronization' permission. The person executing the kwxsync command must have a local ltoken file which contains the authentication data for each affected server. To gain proper authentication, the user must run kwauth for each relevant server; kwauth then stores a token in the user's home directory.

Example 3: Using the --storage option to synchronize projects incrementally

kwxsync --storage my_storage_file http://host:8080/zlib http://host:8080/zlib2 http://host2:8082/zlib

In this example, you specify a file in which to persistently store synchronization information as well as synchronizing three projects. The first time you run the command, the system will synchronize the history of all issue status updates and comments, along with the ID of the user who made the changes. When you run the command subsequently, only the most recent set of status updates and comments are synchronized, which saves a substantial amount of time. By using the --storage option, you can run the tool frequently and ensure that each developer sees an up-to-date list of issues.

Example 4: Using the --status-priority option to resolve status conflicts during synchronization

kwxsync --status-priority status-priority-file http://host:8080/zlib http://host:8080/zlib2 http://host2:8082/zlib

In this example, you point to a status priority file that enables the system to resolve status conflicts during synchronization by referring to a ranked list of statuses.

Options

--copy "srcproj" "destproj1" ["destproj2" ...]

kwxsync --storage my_storage http://host:8080/zlib
 http://host:8080/zlib2 http://host2:8082/zlib  

Exit codes

When you run the kwxsync command, the system generates an exit code. In release 11.0, the exit codes changed. See the table below for more information.