deliver

Delivers changes in a source stream to the target stream within or across projects

Applicability

Product

Command type

ClearCase®

cleartool subcommand

ClearCase Remote Client

rcleartool subcommand

Platform

UNIX

Linux

Windows

Synopsis

Note: If the environment variable CCASE_USE_GUI is set, the options –query and –qall are not supported.
  • ClearCase: deliver changes in the source stream using the graphical user interface:
    deliver –g/raphical [ –str/eam stream-selector ]
    [ –to integration-view-tag ]

    [ –tar/get stream-selector ] [ –q/uery | –qal/l]

  • ClearCase: obtain the status of a deliver operation in progress:
    deliver –sta/tus [ –l/ong ] [ –str/eam stream-selector ]
  • ClearCase: cancel a deliver operation in progress:
    delivercancel [ –str/eam stream-selector ]
    [ –reset –to new-integration-view-tag [ –rmviewref ] ]
  • ClearCase: preview a deliver operation:
    deliver –pre/view [ –s/hort | –l/ong ] [ –str/eam stream-selector ]
    [ –to integration-view-tag] [ –tar/get stream-selector ]

    [ –cac/t | –act/ivities activity-selector ...

    | –bas/elines baseline-selector ... ]

  • ClearCase: deliver changes in the source stream:
    deliver [ –str/eam stream-selector ] [ –to integration-view-tag]
    [ –tar/get stream-selector ]

    [ –cac/t | –act/ivities activity-selector ...

    | –bas/elines baseline-selector ... ]

    [ –com/plete ] [ –gm/erge | –ok ]

    [–q/uery | –abo/rt | –qal/l | –qnt/rivial ] [ –ser/ial ] [–f/orce ]

  • ClearCase: resume or complete work on a deliver operation:
    deliver { –res/ume |–com/plete } [–str/ eam stream-selector ]
    [ –resetto new-integration-view-tag [ –rmviewref ] ]
    [ –gm/ erge | –ok ] [–q/ uery | –ab/ort | –qal/l | –qnt/rivial ] [ –ser/ial ]

    [ –f/orce ]

  • ClearCase Remote Client: deliver changes in the source stream:
    deliver [ –str/eam stream-selector ] [ –to integration-view-tag]
    [ –tar/get stream-selector ]

    [ –cac/t | –act/ivities activity-selector ...

    | –bas/elines baseline-selector ... ]

    [ –com/plete ] [ –gm/erge | –ok ]

    [–q/uery | –abo/rt | –qal/l | –qnt/rivial ] [–f/orce ]

  • ClearCase Remote Client: resume or complete work on a deliver operation:
    deliver { –res/ume |–com/plete } [–str/ eam stream-selector ]
    [ –gm/ erge | –ok ] [–q/ uery | –ab/ort | –qal/l | –qnt/rivial ]

    [ –f/orce ]

  • ClearCase Remote Client: cancel a deliver operation in progress:
    delivercancel [ –str/eam stream-selector ]

Description

The deliver command lets you deliver work from a source stream to a target stream in the same or a different project. There may be several steps to delivering work:

  • Previewing the changes to be delivered
  • Identifying the activities, stream, or baselines you want to deliver
  • Resolving merge conflicts
  • Testing and building work in the target stream
  • Completing a deliver operation, which checks in new versions and records other information

If a deliver operation is interrupted through a system interrupt or user action, you must explicitly resume or cancel it.

In general, it is good practice to check in all work to your source stream before beginning a deliver operation.

You may not deliver when a rebase operation is in progress.

The integration activity

The deliver operation creates a UCM activity called the integration activity, which records a change set for the deliver operation. The activity name is of the form deliver.stream-name.date-stamp. When the deliver operation begins, the integration activity becomes the current activity for the integration view in use.

One-step deliver operation

You can deliver your work in one step by specifying the –complete and –force options. The –force option suppresses prompting for user input during the deliver operation. The –complete option causes the deliver operation to continue to completion after the merge phase. Use this feature carefully to avoid the possibility of delivering merged files that may not compile.

Handling of elements of nondefault merge types

In a deliver operation, automatic merging is the default behavior for elements, unless user or never merge types were set for the elements. For information about setting merge behavior for an element type, see mkeltype.

For elements of the user merge type, you must invoke your own tool to merge from the source stream version to the integration view. The deliver operation checks out the elements, but you are responsible for merging and drawing merge arrows. Until merge arrows are drawn, the deliver operation will not proceed to the completion phase.

A deliver operation ignores versions from the source stream for elements of the never merge type. If all other versions are properly merged, the deliver operation can proceed to the completion phase. No merging or merge arrows are required.

Setting policies

UCM includes policies that you can set to affect the deliver operation. You can set policies at project or stream creation with mkproject or mkstream or at a later time with chproject or chstream. For information about project and stream policies, see the reference pages for mkproject and mkstream.

Delivering changes with MultiSite

The deliver command determines whether the target stream and source stream are mastered at different replicas. If they are, a remote deliver operation is put into effect. The source stream is assigned a posted status.

In a remote deliver operation, the source stream must be a development stream. If you want to deliver changes from an integration stream, you can do so by delivering to a development stream on the same replica, and then delivering from the development stream to the remotely mastered stream.

After the stream is in the posted state, the deliver operation can be continued only by someone working at the target stream's replica. Generally, this is the team's project integrator. Also, after it is posted, the deliver operation can be canceled only by a user at the replica where the target stream resides.

The option –to integration-view-tag is not accepted when starting a remote deliver operation. The remote post goes to the default target stream or an alternative target stream, if specified. The deliver –status command reports on any remote deliver operation in progress for the specified stream. The project integrator can then cancel or continue the deliver operation, using the –cancel option to halt it, or the –resume or –complete options to continue it. The project integrator must specify the integration view for the deliver operation.

While the remote deliver is in progress, you can create activities and perform checkins and checkouts for your source stream, but you cannot perform any of these operations:

  • Add, remove, or create baselines
  • Add or remove components
  • Rebase the source stream
  • Post another deliver operation
  • Receive changes (as the target stream of a local deliver operation) from a development stream

Delivering selected activities to a nondefault target

Delivering selected activities to a nondefault target is subject to the following restrictions:

  • If the full set of activities in the stream violates one of the policy settings, you will not be allowed to proceed with the selected activity delivery, even if the selected activities would not violate the policies.
  • If the full set of activities in the stream contains changes from a foundation baseline, you will not be allowed to deliver selected activities from this stream, regardless of the deliver policy settings.
  • If the set of activities you want to deliver contain versions in components that are not visible in the target stream or are not modifiable by the target stream, you will not be allowed to deliver the set of activities. Delivering an activity requires that you deliver all versions in all components in the change set. You can move the versions of the missing or nonmodifiable components into another activity.

Restrictions

Identities

No special identity required.

Locks

An error occurs if one or more of these objects are locked: the source stream, the target stream, the UCM project VOB.

Mastership

(Replicated VOBs only) Your current replica must master the source stream.

Options and arguments

Starting the graphical user interface

Default
Command line interface.
–graphical
Starts the graphical user interface for deliver.

Specifying the source and destination for the deliver operation

Default
The default source is the stream attached to the current view. The default destination is the parent stream of the source stream. For an integration stream, the default destination is the default deliver target (if one is set), using either a view attached to the parent stream owned by the current user, or the view used by the last default deliver operation performed on the source stream.
–stre/am stream-selector
Specifies a stream that is the source for the deliver operation. The source stream cannot be a read-only stream.

stream-selector is of the form [stream:]stream-name[@vob-selector], where vob-selector specifies the stream's project VOB.

–to integration-view-tag
Specifies a view attached to the deliver target stream in the same project or in a different project. This option is not accepted for a remote-post deliver operation.
–to new-integration-view-tag
Resets the target view to a new integration view. Use this option should the target view become inaccessible.
–rmviewref
Removes references to the inaccessible view from every VOB in which the view is registered. This is equivalent to rmview –uuid. Errors result when you attempt to remove view references from VOBs that are inaccessible. However, if the command returns OK status, you can safely ignore such errors. Be cautious when using this option to avoid stranding checked out files.

Specifying an alternative deliver target

Default
For development streams, the parent stream of the source stream. For integration streams, the default deliver stream set by mkstream or chstream.
–tar/get stream-selector
Specifies the deliver target stream in the same or a different project. The target stream cannot be a read-only stream.

Using –to integration-view-tag alone is sufficient to start a deliver operation to the target stream. If –to and –target are used together, the view must be attached to the stream. If one default view is attached to the target stream and owned by the user, using –target stream-selector alone can start a deliver operation. Otherwise, an integration view must be specified.

stream-selector is of the form [stream:]stream-name[@vob-selector], where vob-selector specifies the stream's project VOB.

Obtaining the status of a deliver operation

Default
None.
–sta/tus
Displays the status of a deliver operation. You are informed whether a deliver operation for the specified stream is in progress, whether the delivery is to a local stream or a remote stream, and, in the case of a remote deliver, whether the posted changes have been merged with the target stream.

Canceling a deliver operation

Default
None.
–can/cel
Halts a deliver operation in progress, returning the source and destination streams to their states before the deliver operation began. However, this option cannot undo a deliver operation after the completion phase has begun.

You can also use –cancel to cancel a delivery following an interrupt (as by Ctrl+C) or whenever the operation encounters an unexpected problem that would be easier to resolve by starting over.

–resetto integration-view-tag
You must not remove the developer view when a deliver operation is in progress. However, if the integration view is lost during a deliver operation, you can use the –resetto option to reset a new integration view so you would be able to cancel the operation. You can also use this option with –resume and –complete. Before you can reset a new integration view, the view-related records of the old integration view must be removed. UCM checks to see if the old view has any checkouts and if it has none, unsets the integration activity set in the view.

Previewing the results of a deliver operation

Default
For each activity to be delivered, displays the owner and activity-selector. For each baseline to be delivered, displays the owner and baseline-selector.
–pre/view
Shows activities or baselines that would be delivered if you were to execute the deliver operation for the specified stream. These are any activities or baselines that have changed since the last deliver operation from this stream. Use –preview only when no deliver operation is in progress for the stream.

Controlling output verbosity

Default
Varies according to the kind of output that the options described here modify. See the descriptions of –status and –preview.
–l/ong
As a modifier of –status or –preview, displays a list of versions that may require merging, in addition to the default information displayed by –status or –preview.
–s/hort
Modifies the –preview option. (This option does not modify the default –preview output.)

Delivering the current activity

Default
Delivers all activities in the stream that have changed since the last deliver operation from the stream.
–cac/t
Delivers the activity currently set in the view. The operation fails if you are not in a view, have not set your view to an activity or the activity depends on the inclusion of any unspecified activities. For an explanation of activity dependence, see the section Selecting activities to deliver.

Selecting activities to deliver

Default
Delivers all activities in the stream that have changed since the last deliver operation from the stream.
–act/ivities activity-selector, ...
Specifies a list of activities to deliver. The list must be self-consistent: the activities specified must not depend on the inclusion of any unspecified activities. For example, activity A2 is dependent on activity A1 if both contain versions of the same element and A2 contains a later version than does A1.

In addition, any activities that have been included in baselines but not delivered must also be delivered if changes for that component are in the specified activities. If the list of activities you specify is incomplete, the operation fails and lists the additional required activities.

activity-selector is of the form [activity:]activity-name[@vob-selector] where vob-selector specifies the activity's project VOB.

Selecting baselines to deliver

Default
Delivers all activities in the stream that have changed since the last deliver operation from the stream.
–bas/elines baseline-selector, ...
Specifies a list of baselines to deliver. The baselines must be created in the source stream or from the source stream's foundation. A development stream can deliver activities or baselines, but an integration stream can deliver only baselines.

Resuming a deliver operation

Default
None.
–res/ume
Resumes a deliver operation from the point at which it was suspended.

Completing a deliver operation

Default
None.
–com/plete
Completes a deliver operation. Verifies that changes being delivered have been merged with versions in the deliver target stream and that merge conflicts have been resolved. Checks in resulting new versions to the target stream and records that the deliver operation has been made. If merge conflicts exist, the deliver operation is suspended.

Use this option to complete a deliver operation or to resume a suspended deliver operation. To complete a deliver operation, you must specify this option; checking in merged versions to the integration view alone does not complete the deliver operation.

When used for a deliver operation in progress, this option implies the –resume option; that is, deliver –complete reports any merges that are still required and attempts to resolve them.

Merging

Default
Merging works as automatically as possible, prompting you to make a choice when two or more contributors differ from the base contributor. For general information, see the findmerge reference page.
–gm/erge
Performs a graphical merge for each element that requires it. This option does not remain in effect after a deliver operation is interrupted.
–ok
Pauses for verification on each element to be merged, allowing you to process some elements and skip others. This option does not remain in effect after a deliver operation is interrupted.
–q/uery
Prompts you for confirmation before proceeding with each change in the from-versions. Changes in the to-version are automatically accepted unless a conflict exists. This option does not remain in effect after a deliver operation is interrupted.
–abo/rt
Cancels a merge if it is not completely automatic. This option does not remain in effect after a deliver operation is interrupted.
–qal/l
Turns off all automated merging. Prompts you for confirmation before proceeding with each change. This option does not remain in effect after a deliver operation is interrupted.
–qnt/rivial
Turns off automated merging and prompts you to determine whether you want to proceed except in the case where a trivial merge would be done. This option does not remain in effect after a deliver operation is interrupted.
–ser/ial
Uses a serial format to report differences among files. Differences are presented in a line-by-line comparison with each line from one contributor, instead of in a side-by-side format. This option does not remain in effect after a deliver operation is interrupted.

Confirmation step

Default
Prompts for user input.
–f/orce
Suppresses prompting for user input during the course of a deliver operation. The –force option does not remain in effect if the deliver operation is interrupted. You must include it again on the command line when you restart the deliver operation with –resume or –complete. The merge options for deliver are not affected by the –force option.

Examples

The UNIX system and Linux examples in this section are written for use in csh. If you use another shell, you might need to use different quoting and escaping conventions.

The Windows examples that include wildcards or quoting are written for use in cleartool interactive mode. If you use cleartool single-command mode, you might need to change the wildcards and quoting to make your command interpreter process the command appropriately.

In cleartool single-command mode, cmd-context represents the UNIX system and Linux shells or Windows command interpreter prompt, followed by the cleartool command. In cleartool interactive mode, cmd-context represents the interactive cleartool prompt.

  • Start a deliver operation using command defaults.
    cmd-context deliver -to webo_integ
    Changes to be DELIVERED:
    FROM: stream "chris_webo_dev"
    TO: stream "integration"
    Using integration view: "webo_integ".
    Do you wish to continue with this deliver operation?  [no]yes
    Needs Merge "/view/webo_integ/vobs/webo_modeler/design/foo" [(automatic) 
    to /main/integration/1 from /main/integration/chris_webo_dev/1 (base also 
    /main/integration/1)]
    Checked out "/view/webo_integ/vobs/webo_modeler/design/foo" from version 
    "/main/integration/1".
    
    Attached activities:
    activity:deliver.chris_webo_dev.20000606.160519@/vobs/webo_pvob  "deliver
    chris_webo_dev on 06/06/00 16:05:19."
    
    Needs Merge "/view/webo_integ/vobs/webo_modeler/design/foo" [to 
    /main/integration/CHECKEDOUT from /main/integration/chris_webo_dev/1 base 
    /main/integration/1]
    
    Trivial merge: "/view/webo_integ/vobs/webo_modeler/design/foo" is same as
     base "/view/webo_integ/vobs/webo_modeler/design/foo@@/main/integration/1".
    
    Copying 
    "/view/webo_integ/vobs/webo_modeler/design/foo@@/main/integration/chris_webo
    _dev/1" to output file.
    Moved contributor "/view/webo_integ/vobs/webo_modeler/design/foo" to
    "/view/webo_integ/vobs/webo_modeler/design/foo.contrib".
    Output of merge is in "/view/webo_integ/vobs/webo_modeler/design/foo".
    Recorded merge of "/view/webo_integ/vobs/webo_modeler/design/foo".
    
    Deliver has merged
    FROM: stream "chris_webo_dev"
    TO: stream "integration"
    Using integration view: "webo_integ".
    Build and test are necessary in integration view "webo_integ"
    to ensure that the merges were completed correctly.  When build and
    test are confirmed, run "cleartool deliver -complete".
  • Complete a deliver operation that is in progress.

    cmd-context deliver –complete
    Resume deliver
         FROM: stream "chris_webo_dev"
         TO: stream "integration"
    Using integration view: "webo_integ".
    Do you wish to continue with this deliver operation?  [no]
    yes
    Are you sure you want to complete this deliver operation?  [no] yes
    Deliver has completed
         FROM: stream "chris_webo_dev"
         TO: stream "integration"
    Using integration view: "webo_integ".

  • Check the status of a deliver operation.
    cmd-context deliver –status
    Deliver operation in progress on stream "stream:chris_webo_dev@\webo_pvob"
         Started by "ktessier" on "2007-06-14T16:07:46"
         Using integration activity "deliver.chris_webo_dev.20000614.160746".
         Using view "webo_integ".
         Activities will be delivered to stream "stream:integration@\webo_pvob".
    Development Stream Baselines:
    baseline:deliverbl.chris_webo_dev.20000614.160746.129@\webo_pvob
    Activities:
    activity:fix_copyright@\webo_pvob
    activity:update_date@\webo_pvob
    activity:fix_defect_215@\webo_pvob
  • Cancel a deliver operation that is in progress.

    cmd-context deliver –cancel
    Cancel deliver
         FROM: stream "chris_webo_dev"
         TO: stream "integration"
    Using integration view: "webo_integ".
    Are you sure you want to cancel this deliver operation?  [no]
    yes
    Private version of "/view/webo_integ/vobs/webo_modeler/design/add_proc"
    saved in "/view/webo_integ/vobs/webo_modeler/design/add_proc.keep".
    Deliver of stream "chris_webo_dev" canceled.