rebase
Changes the configuration of
a stream
SYNOPSIS
- Begin
a rebase operation using the graphical user interface:
- rebase –gr·aphical [ –vie·w rebase-view-tag ]
- [ –str·eam stream-selector ]
[ –q·uery | –qal·l ]
- Cancel
or check the status of a rebase operation:
- rebase { –can·cel | –sta·tus [–l·ong ] }
- [ –vie·w rebase-view-tag ]
[ –str·eam stream-selector ]
- Preview
a rebase operation:
- rebase –pre·view [ –s·hort | –l·ong ] [ –vie·w rebase-view-tag ]
- [ –str·eam stream-selector ]
{ –rec·ommended |
{ –bas·eline baseline-selector[,...]
–dba·seline baseline-selector[,...]
} }
- Begin
a rebase operation:
- rebase { –rec·ommended |
{ –bas·eline baseline-selector[,...]
- –dba·seline baseline-selector[,...]
} }
[ –vie·w rebase-view-tag ]
[ –str·eam stream-selector ]
[ –com·plete ] [ –gm ·erge | –ok ]
[ –q·uery | –abo·rt | –qal·l ] [ –ser·ial ]
- Resume
or complete a rebase operation:
- rebase { –res·ume | –com·plete } [ –vie·w rebase-view-tag ]
- [ –str·eam stream-selector ]
[ –gm·erge | –ok ]
[ –q·uery | –abo·rt | –qal·l ] [ –ser·ial ] [–f· orce ]
DESCRIPTION
The rebase command reconfigures
a stream by adding, dropping, or replacing one or more of the stream's foundation
baselines. The file and directory versions selected by those new baselines
(and thus their associated activities) then become visible in the stream's
views.
Only labeled baselines can serve as foundation
baselines.
Any changes made in the stream before a rebase
operation are preserved during the rebase. For any file modified in the stream, rebase merges
any changes that are present in versions of that file in the new foundation
baselines into the latest version of that file in the stream, thereby creating
a new version. All such merged versions are captured in the change set of
an integration activity that rebase creates. This integration
activity becomes the view's current activity until the rebase operation is
completed or canceled.
You must perform a rebase operation in a
view belonging to the stream that is being rebased. Before starting the rebase
operation, check in all files in that view. By default, the rebase operation
stops when it encounters a checkout conflict. However, for single stream project
only, rebase skips the checked-out file and continue with
other files.
If you want to recommend a baseline after
rebasing to it, you must add it to the list of recommended baselines with chstream –recommended.
As a rule, you should rebase development
streams often to pick up changes in the project's recommended baselines. By
doing so, you can find integration problems early, when they are easier to
fix. In addition, rebasing just before performing a deliver operation reduces
or eliminates the need for manual merging during the delivery.
You cannot rebase when a deliver operation
is in progress.
Rules for Rebasing a Stream
A stream can be rebased to a baseline that meets the following criteria:
- The baseline is not from
the stream that is being rebased.
- The baseline is labeled.
Baselines created by deliver operations are not labeled by default. For information
about how to change a baseline's labeling status, see the chbl reference
page.
Additional rules apply to integration streams and development streams
in selecting a baseline:
- An integration stream can
be rebased only to a baseline created in another project or to an imported
or initial baseline of that project.
- A development stream can
be rebased to a baseline that meets one of the following criteria:
- The baseline was created
in its parent stream.
- The baseline is in its parent
stream's foundation.
- The baseline was created
in a stream other than its parent stream and is contained in its parent stream.
A baseline is contained in another baseline if all changes in the first baseline
are included in the second baseline.
Note: Read-Only streams and nonmodifiable components in a development
stream are exempt from the above rules. However, if the component's modifiability
changes in the future, the development stream may or may not be able to modify
the component at the baseline it is configured with. It may if the baseline
is contained in its parent stream for this component. Otherwise it may not
until the baseline is rebased to a compatible baseline for that component.
Rebase is typically used to advance a stream's configuration, that is,
to replace its current foundation baselines with more recent ones. However,
under certain conditions, rebase can be used to revert a baseline, and to
add or drop a component in a stream's configuration. It can also switch to
a baseline that is neither an ancestor nor a descendant of the current foundation.
The rules explained above are general rules for all rebase operations. You
need to satisfy only the general rules when adding a component to a stream.
When you advance, revert, drop, or switch a baseline, you need to satisfy
the general rules and some additional ones.
- To advance a stream's configuration,
the new baseline must contain the current foundation baseline.
- To revert or drop a baseline
for a component in a stream, one of the following conditions must be met:
- The component is nonmodifiable.
- The component is modifiable
but has not been modified in the stream, and the component is not in the
configuration of any child streams.
- To switch to a baseline
that is neither an ancestor nor a descendant of the current foundation, one
of the following conditions must be met:
- The component is nonmodifiable.
- The component is modifiable
but has not been modified in the stream, and the component is not in the
configuration of any child streams.
- The component has been modified
but the new baseline contains the current foundation baseline, and the component
is not in the configuration of any child streams.
These rules ensure that any changes made in a stream are not lost when
the configuration changes.
Handling of Elements of Nondefault Merge Types
In a rebase 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.
Rebase and deliver operations handle elements
of user or never merge types
in much the same way. For more information, see this topic in deliver.
RESTRICTIONS
Identities
No
special identity required.
Locks
An
error occurs if one or more of these objects are locked: the project VOB,
the development stream.
Mastership
(Replicated
VOBs only) Your current replica must master the development stream.
OPTIONS AND ARGUMENTS
Invoking the Graphical User Interface
- Default
- Command-line interface.
- –gr·aphical
- Starts the graphical user interface for the
rebase operation.
Specifying the Rebase View
- Default
- If a stream is specified, the view attached
to the stream (provided that only one view is attached to the stream; if multiple
views are attached, a view must be specified.) If a stream is not specified,
the current working UCM view.
- –vie·w rebase-view_tag
- Specifies the view in which to execute the rebase command.
The view must be associated with a stream that is the stream to be rebased.
Specifying the Stream to Be Rebased
- Default
- If a view is specified, the stream attached
to the view. If a view is not specified, the stream attached to the current
UCM view.
- –str·eam stream-selector
- Specifies the stream to be rebased.
Specifying the stream alone is sufficient
for canceling, previewing, resuming, completing, and checking status of a
rebase operation. A view is not required. When beginning a new rebase operation,
a view is required if it cannot be uniquely determined.
stream-selector is
of the form [stream:]stream-name[@vob-selector],
where vob-selector specifies the stream's project
VOB.
Canceling a Rebase Operation
- –can·cel
- Cancels a rebase operation and restores the
stream's previous configuration. The option deletes the integration activity
and any versions created by the rebase operation that are not yet checked
in.
If any new versions have been checked in,
the cancellation process is halted, and you are informed of completed merges
and any checked in versions that resulted from the rebase activity. After
undoing the merges and checkins, you must issue the rebase –cancel command
again to cancel the rebase operation.
Obtaining the Status of a Rebase Operation
- –sta·tus
- Displays the status of a rebase operation.
You are informed whether a rebase operation is in progress in the specified
stream; and if so, this option displays the new foundation baselines and the
list of new activities being brought into the stream.
Previewing the Results of a Rebase Operation
- –pre·view
- Shows which baselines would change and which
new activities would be brought into the stream if a rebase operation were
to be executed. –preview fails if a rebase operation
is in progress.
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,
displays a list of activities and change sets and a list of elements that
will require merging, in addition to the default information displayed by –status.
As a modifier of –preview,
displays a list of versions that potentially require merging, in addition
to the default information displayed by –preview.
- –s·hort
- Modifies the –preview option.
Displays only a list of the activities.
Specifying Baselines
- Default
- None.
- –rec·ommended
- Specifies that a development stream is to
be rebased to its parent stream's recommended baselines. Using this option
clears the existing foundation baselines and replaces them with the recommended
ones.
- –bas·eline baseline-selector[,...]
- Specifies one or more baselines to use as
new foundation baselines for the stream. See “Rules for Rebasing a Stream” for criteria for specifying baselines. Using this option replaces
only the baselines in the components for which a newer baseline is explicitly
specified.
If your project has composite baselines,
you can rebase to your parent stream's composite baseline. Therefore, you
need not specify multiple baselines separately. Any additions to the composite
baseline dependencies are propagated through subsequent rebase operations.
Note: Depending
on whether –recommended or –baseline is
used, the result of rebasing to a composite baseline may be different. For
example, the foundation baseline for a development stream is composite baseline
X1, which selects member baselines A1, B1 and C1. New baselines A2 and A3
are created in the parent stream and picked up by the development stream through
rebase operations. Now the foundation baselines for the development stream
are X1 and A3. Then a new composite baseline, X2, is made and recommended
in the parent stream, which selects A2, B2, and C2. If you rebase to the recommended
baseline, A2 overrides A3 in the development stream. The new foundation baselines
for the development stream is X2. However, if you rebase to X2 by using the –baseline
option, A2 does not override A3 because A3 is explicitly present
in the foundation. The new foundation baselines for the development stream,
in this case, is X2 and A3.
baseline-selector is
of the form [baseline:]baseline-name[@vob-selector],
where vob-selector specifies the baseline's project
VOB.
- –dba·seline baseline-selector[,...]
- Specifies one or more baselines to remove
from the stream's configuration. Files in those baseline's components are
subsequently no longer visible or modifiable in the stream. See “Rules for Rebasing a Stream” for criteria for specifying baselines.
baseline-selector is
of the form [baseline:]baseline-name[@vob-selector],
where vob-selector specifies the baseline's project
VOB.
Resuming a Rebase Operation
- Default
- None.
- –res·ume
- Restarts a rebase operation from the point
at which it has been suspended. A rebase operation can be interrupted (as
with CTRL+C) or when it encounters an external error or condition
that requires more information. To continue the operation, reissue the rebase command
with the –resume option. However, you cannot resume
a rebase operation that has been successfully halted with the –cancel option.
Completing a Rebase Operation
- Default
- None.
- –com·plete
- Completes a rebase operation. Checking in
merged versions in the development view does not complete the rebase operation;
you must use –complete to complete a rebase operation.
You can use this option after a rebase has been suspended—for example,
to resolve file conflicts. It resumes the rebase operation, verifies that
needed merges were made, checks in any versions that are checked out, and
records changes in the change set for the rebase activity.
Merge Options
- Default
- Works as automatically as possible, prompting
you to make a choice in cases where two or more contributors differ from the
base contributor. For general information, see the findmerge reference
page.
- -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 rebase operation is interrupted.
- –gm ·erge
- Performs a graphical merge for each element
that requires it. This option does not remain in effect after a rebase operation
is interrupted.
- –q·uery
- Turns off automated merging for nontrivial
merges and prompts you to proceed with every change in the from-versions.
Changes in the to-version are accepted unless a conflict exists. This option
does not remain in effect after a rebase operation is interrupted.
- –abo·rt
- Cancels a merge if it is not completely automatic.
This option does not remain in effect after a rebase operation is interrupted.
- –qal·l
- Turns off all automated merging. Prompts
you to specify whether to proceed with each change. This option does not remain
in effect after a rebase operation is interrupted.
- –ser·ial
- Reports differences with each line containing
output from one contributor, instead of in a side-by-side format. This option
does not remain in effect after a rebase operation is interrupted.
Controlling Command-Line Prompts
- Default
- Prompt for user input.
- –f·orce
- Suppresses prompting for user input during
the course of a rebase operation. The –force option
does not remain in effect if the rebase is interrupted; you must respecify
it when you restart the rebase operation with –resume or –complete.
The merge options to the rebase command are not affected by the –force option.
EXAMPLES
The UNIX examples in this section are written for use in csh.
If you use another shell, you may 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 may 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 shell or Windows command interpreter prompt, followed by the cleartool command.
In cleartool interactive mode, cmd-context represents
the interactive cleartool prompt.
- Start
a rebase operation.
- Complete
a rebase operation.