ClearCase::Wrapper::MGi - Support for an alternative to UCM.
This is an overlay module for ClearCase::Wrapper containing Marc Girod's non-standard extensions. See perldoc ClearCase::Wrapper (by David Boyce) for more details.
overlay module
perldoc ClearCase::Wrapper
The alternative to UCM consists in a novel branching model, and a concept of incremental types.
LSGENEALOGY
New command. LsGenealogy is an alternative way to display the version tree of an element. It will treat merge arrows on a par level with parenthood on a branch, and will navigate backwards from the version currently selected, to find what contributors took part in its state. This is thought as being particularly adapted to displaying the bush-like structure characteristic of version trees produced under the advocated branching strategy.
Flags:
Show 'uninteresting' versions, otherwise skipped:
Note that a different algorithm is used with and without the -all option. The latter uses lsvtree and may thus be slow on elements with a large version tree. The former is thus more scalable.
-all
lsvtree
Add obsoleted branches to the search.
Skip displaying labels and 'labelled' versions and do not report alternative paths or siblings.
Substitute to the default representation of every version (optionally including labels), the output of des -fmt 'format' version.
des -fmt 'format' version
The indentation is preserved, but all the verbose annotations (offspring, siblings, alternatives) are stripped (as in short mode).
Specify a maximum depth at which to stop displaying the genealogy of the element.
Print the offspring of the selected version (for every argument). Offspring are not restricted by the depth argument.
This option is compatible with -fmt.
CO/CHECKOUT
Supports the BranchOff feature, which you can set up via an attribute in the config spec. The rationale and the design are documented in:
http://www.cmcrossroads.com/cgi-bin/cmwiki/view/CM/BranchOffMain0
Instead of branching off the selected version, the strategy is to branch off the root of the version tree, copy-merging there from the former.
This allows to avoid both merging back to /main or to a delivery branch, and cascading branches indefinitely. The logical version tree is restituted by navigating the merge arrows, to find all the direct or indirect contributors.
The creation of cascading branches is preserved if specified by the config spec, unless in a BranchOff config spec, in which case it doesn't make sense.
Flag:
Ignored under a BranchOff config spec, but the version specified in the pname is anyway obeyed, as a branch may always be spawn.
MKBRANCH
Actually a special case of checkout.
Special case of reverting to the default behaviour, as this cannot reasonably be served in a new branch under BranchOff (no version to which to attach the Merge hyperlink).
DIFF
Evaluate the predecessor from the genealogy, i.e. take into account merges on an equal basis as parents on the same physical branch. In case there are multiple parents, consider the one on the same branch as 'more equal than the others' (least surprise principle).
Preserve the (Wrapper default) assumption of a -pred flag, if only one argument is given.
UNCHECKOUT
The wrapper implements the functionality commonly provided by a trigger, to remove the parent branch if it has no checkouts, no sub-branches, and no remaining versions, while unchecking out version number 0.
MKLBTYPE
Extension: families of types, with a chain of fixed types, linked in a succession, and one floating type, convenient for use in config specs. One application is incremental types, applied only to modified versions, allowing however to simulate full baselines. Such a functionality is implemented as part of UCM, for fixed types, and magic config specs. The wrapper offers thus something similar on base ClearCase.
This wrapper also includes a modified version of the extension for global types originally proposed in ClearCase::Wrapper::DSB. In the realm of an admin vob, types are created global by default. This implementation makes the feature configurable, via a $ClearCase::Wrapper::MGi::global variable set in .clearcase_profile.pl, so that a user is not forced to obey an injonction from (possibly other site) administrators.
ClearCase::Wrapper::DSB
$ClearCase::Wrapper::MGi::global
.clearcase_profile.pl
The current baseline is embodied with floating labels, which are moved over successive versions. The first pair of a floating and a fixed type is created with the -fam/ily flag. Further fixed types are created with the -inc/rement flag.
Types forming a family are related with hyperlinks of two types:
Equivalent incremental fixed type. A fixed (i.e. which by convention, will not been moved), sparse (i.e. applied only to changes) type. This helps to mark the history of application of the floating type, which is also a full one, for reproducibility purposes.
Previous incremental fixed type.
Attributes are created of a per label family type, and are used to mark the deletion of labels applied at a previous increment. The attribute type for family lbtype XXX is RmXXX, and the value is the numeric (treated as real) value of the increment.
Create two label types, linked with an EqInc hyperlink. The first, given as argument, will be considered as an alias for successive increments of the second. It is the family type. The name of the initial incremental type is this of the family type, with a suffix of _1.00.
Also create a RmLBTYPE attribute type to record removals of labels.
For lbtypes, if the floating type was previously archived (e.g. to deactivate config spec rules), then the command revives the type hidden as part of archiving (and not applied anywhere). The new equivalent fixed type is the one following the last equivalent type, which is however not set as its previous increment.
Create a new increment of an existing label type family, given as argument. This new type will take the place of the previous increment, as the destination of the EqInc hyperlink on the family type. It will have a PrevInc hyperlink pointing to the previous increment in the family.
For lbtypes, if the floating type was previously archived, then the behavior reverts to the -fam/ily one. This means that an archived label type may be incremented. This however amounts to a new creation and is only provided as a convenience (no need to remember the state of the family--whether it was rolled out and archived or not).
Rename the current type to an archive value (name as prefix, and a numeral suffix. Initial value: -001), create a new type, and make the archived one its predecessor, with a PrevInc hyperlink. Comments go to the type being archived.
The implementation is largely shared with mkbrtype.
For label types, the newly created type is hidden away (with a suffix of _0) and locked. It is being restored the next time mklbtype -fam is given for the same name.
mklbtype -fam
Support for global family types is preliminary.
Make or increment lbtypes in all vobs used by a config record.
When using a config record, exclude comma separated vobs for label type creation.
Create a new type, while is applied to all versions which bore labels of a floating type, at the time of a given increment.
The type is created and applied only in one vob, even if the original type was global.
This option is only compatible, among the extensions, with the -family flag (optional).
It is also incompatible with -replace (the implementation was not considered worth the while).
MKBRTYPE
Extension: archive a brtype away, in order to avoid having to modify config specs using it (rationale: config specs are not versioned, so they'd rather be stable). Also, starting new branches from the main one (whatever its real type) makes it easier to roll back changes if need-be, branch off an earlier version, and bring back again the changes rolled back at some later stage, after the problems have been fixed.
The implementation is largely shared with mklbtype. See its documentation for the PrevInc hyperlink type.
Global types (in an Admin vob or not) are currently not supported for archiving.
LOCK
New -allow and -deny flags. These work like -nuser but operate incrementally on an existing -nuser list rather than completely replacing it. When -allow or -deny are used, -replace is implied.
When -iflocked is used, no lock will be created where one didn't previously exist; the -nusers list will only be modified for existing locks.
In case of a family type, lock also the equivalent incremental type.
There may be an issue if the two types are not owned by the same account. You may overcome it by providing a module specification via the environment variable FORCELOCK. This module must export both a flocklt and a funlocklt (force lock and unlock label type) functions. The functions take an lbtype and a vob tag as input (flocklt optionally takes a replace flag and an nusers exception list). The two functions take the responsibility of printing the standard output (but not necessarily the errors), and return an error code: 0 for success, other for error. See the documentation for examples of implementation.
UNLOCK
In case of a family type, unlock also the equivalent incremental type.
There may be an issue if the two types are not owned by the same account. See the LOCK documentation for overcoming it with a FORCELOCK environment variable.
There is also the case of global types: then one ensures that the family type is usable locally, by copying in the equivalent incremental type.
MKLABEL
In case of a family type, apply also the equivalent incremental type. The meaning of -replace is affected: it concerns the equivalent fixed type, and is implicit for the floating type (the one given as argument).
Preserve the support for the -up flag from ClearCase::Wrapper::DSB and lift the restriction to using it only with -recurse.
Added a -force option which makes mostly sense in the case of applying incremental labels. Without it, applying the floating label type will be skipped if there has been errors while (incrementally) applying the equivalent fixed one. Forcing the application may make sense if the errors come from multiple application e.g. due to links, or in order to retry the application after a first failure. It may also be used to apply labels upwards even if recursive application produced errors.
-config: adapted for incremental types. This requires that the label types have been created previously with mklbtype -config. It will not use admin vobs!
The script will skip, and report, vobs in which the types have not been copied/linked to.
With incremental types, the -replace flag is implicit in conjunction with -config.
Extension: -over takes either a label or a branch type. In either case, the labels will be applied over the result of a find command run on the unique version argument, and looking for versions matching respectively lbtype(xxx) or <version(.../xxx/LATEST)> queries, and !lbtype(lb) (with xxx the -over, and lb the main label type parameter. Internally -over performs a find. This one depends by default on the current config spec, with the result that it is not guaranteed to reach all the versions specified, at least in the first pass. One may thus use an -all option which will be passed to the find. The -over option doesn't require an element argument (default: current directory). With the -all option, it uses one if given, as a filter. When using a branch type to apply labels, it links the types with a StBr hyperlink. This is in preparation for an eventual rollout of the label type: this one will then archive the branch type (away) in addition to the label type, if they are used in the config spec, so that rules based on neither would hide the updated baseline.
CI/CHECKIN
Extended to handle the -dir/-rec/-all/-avobs flags. These are fairly self-explanatory but for the record -dir checks in all checkouts in the current directory, -rec does the same but recursively down from the current directory, -all operates on all checkouts in the current VOB, and -avobs on all checkouts in any VOB.
Extended to allow symbolic links to be checked in (by operating on the target of the link instead).
Extended to implement a -diff flag, which runs a diff -pred command before each checkin so the user can review his/her changes before typing the comment.
Implements a new -revert flag. This causes identical (unchanged) elements to be unchecked-out instead of being checked in.
Since checkin is such a common operation, a special feature is supported to save typing: an unadorned ci cmd is promoted to ci -dir -me -diff -revert. In other words typing ct ci will step through each file checked out by you in the current directory and view, automatically undoing the checkout if no changes have been made and showing diffs followed by a checkin-comment prompt otherwise.
promoted
[ From David Boyce's ClearCase::Wrapper. Adapted to user interactions preempting. ]
RMBRANCH
No semantic change. This implementation is only needed to handle the optional interactive dialog in the context of the ipc mode of the underlying ClearCase::Argv.
RMLABEL
For family types, remove both types, and add a RmLBTYPE attribute mentioning the increment of the removal of the LBTYPE label, for use in config specs based on sparse fixed types equivalent to a given state of the floating type.
RMTYPE
For family label types, 3 cases:
mklbtype -fam LBTYPE
Note that removing directly an incremental fixed type is left unchanged for low level purposes, and thus may corrupt the whole hierarchy: you need to restore links and take care of possible RmLBTYPE attributes.
CPTYPE
For family types: copy both the "family" (floating) type and its equivalent fixed incremental type (and all the hierarchy?).
For global types, create the hyperlinks.
SETCS
From the version in DSB.pm 1.14--retaining its additions:
Adds a -clone flag which lets you specify another view from which to copy the config spec.
Adds a -sync flag. This is similar to -current except that it analyzes the CS dependencies and only flushes the view cache if the compiled_spec file is out of date with respect to the config_spec source file or any file it includes. In other words: setcs -sync is to setcs -current as make foo.o is to cc -c foo.c.
Adds a -needed flag. This is similar to -sync above but it doesn't recompile the config spec. Instead, it simply indicates with its return code whether a recompile is in order.
Adds a -expand flag, which "flattens out" the config spec by inlining the contents of any include files.
Add support for incremental label type families, via an ##:IncrementalLabels: attribute in the config spec: generate a config spec fragment equivalent to the type specified, and include it. An optional clause of -nocheckout will be propagated to the generated rules.
-nocheckout
DESCRIBE
From DSB.pm
Enhancement. Adds the -parents flag, which takes an integer argument N and runs the describe command on the version N predecessors deep instead of the currently-selected version. into temp files and diffs them. If only one view is specified, compares against the current working view's config spec.
The parents take the genealogy of contributions into account.
Every version may thus have several parents. In fact, at a given generation level, the same contributors might occur several times: the command will show them only once.
Two enhancements to the formats supported by the -fmt flag:
-fmt
%PVn
%PSn
%[...]l
MKVIEW
Enhancement. Clone, equivalent fixed config spec. Works only for dynamic views, as I don't know how to get the snapshot view directory
ROLLOUT
New command. Deliver by applying labels of the base line family (applying the fixed increment and moving the floating).
Without the -force option, will perform a prior find to verify that no home merge (rebase) is needed.
As part of the rollout, the type identifying the development (label type or branch type) will be archived away if it is used in the current config spec. This is to ensure that the config spec will select the new baseline after the rollout. Note that branch types associated with a family label (used previously with a mklabel -over) will be archived as well.
Note that the rollout concerns a type at the vob level (or across several vobs). It is however dependent on the view used, which is assumed to be a development view selecting the versions being rolled-out.
The baseline type must be a family type.
The intention is to eventually support global types. This is disabled for now. The problem lies in applying labels in multiple vobs, which may be too slow to be practical.
If the type being delivered (or eventually any branch type it carries changes from) is global, the rollout will affect all the vobs concerned. This is a consequence of the fact that the types will get archived. The baseline type scope will have to match.
ROLLBACK
New command. Roll back to a previous increment.
This is in effect a new rollout, and will result in a new increment of the baseline family label type.
The change set required as argument is a fixed incremental label type.
ARCHIVE
New command. Synonymous to alternatively mkbrtype or mklbtype -arc
This command assigns the comment in a more intuitive way than its alternative with mkbrtype: the comment goes to the type being archived, instead of to the new type being created.
The non-intuitive behaviour is justified by the consistency with the behaviour of mklbtype -arc, for which no user visible type is created.
Another advantage of this syntax over the alternative is the possibility to archive in a single command both a lbtype and a brtype associated, as happens with the rollout command.
Label types and branch types are grouped and processed in this order.
LSTYPE
This function is provided to work around a bug in ClearCase which IBM does not admit as a bug.
lstype will issue errors (not warnings) in two scenarios related to GlobalDefinition hyperlinks. In one case, it will abort, i.e. return an incomplete list of types.
The wrapper function will convert the errors into warnings in case no admin vob is concerned, i.e. when the issue detected has in fact a lighter impact than the effect of aborting lstype.
The condition under which lstype would abort on error related to MultiSite synchronization, and cannot be avoided. The resulting behaviour will thus appear to happen randomly, and for transient periods of time.
The behaviour of lstype is thus both inconsistent and unpredictable.
The fix offers an informative warning instead of an error. It is restricted to lbtypes, and skipped in presence of admin vobs.
Note: the result is significantly (~5x) slower, when the standard command works.
ANNOTATE
This implementation serves two purposes:
The default behaviour assumes that related changes all took place within the same line of descent (i.e. physical branch hierarchy).
This assumption is defeated in the case of the BranchOff strategy, with which ancestors are typically merged from branches outside this line of descent.
The -all flag allows to examine changes beyond the line of descent, but results in spurious UNRELATED annotations (Merge arrows are ignored at large, although they clearly relate changes...)
UNRELATED
Merge
In the context of the source container layout fixing, the assumption results in spurious errors, when the version referenced is outside the line of descent, even if otherwise perfectly valid.
The wrapper forces the injection of the -all flag for files, and resorts to lshistory for directories.
As Merge arrows are ignored, the reference version for a new branch spawned off the root of the tree is systematically empty (unless fixing the layout of source containers).
This is the reference towards which changes are reported. It results that the same lines are reported as added multiple times.
Better fixing of the problems described above is only provided in the context of the additional options below.
The default behaviour of annotate is file oriented. The file produced is of a verbose format, which would contain long lines. These ones are thus truncated.
annotate
This defeats most of the usefulness of the tool.
One offers two alternative new flags to produce line oriented output:
SYNCTREE
This function offers an alternative interface, somewhat simplified, with different flags and default options, to the standalone synctree script from ClearCase::SyncTree.
The implementation is however imported from the module.
This is used to update a directory tree or a list of colocated elements.
To create a tree in place, use preferably mkelem -rec.
mkelem -rec
The supported flags are:
The default options used are (with respect to the standalone script):
Typically, you need to fix the cause of the problem, possibly checkin recursively with the -revert option, remove any remaining view private files, and restart to continue.
The default is changed from the original synctree because the reuse option tends to bring in hidden directories which may have wrong protections. Such errors are thus not infrequent, and the cleanup makes them cumbersome to fix.
Copyright (c) 2007 IONA Technologies PLC (until v0.05), 2008-2012 Marc Girod (marc.girod@gmail.com) for later versions. All rights reserved. This Perl program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.
perl(1), ClearCase::Wrapper, ClearCase::Wrapper::DSB, ClearCase::Argv, ClearCase::SyncTree
To install ClearCase::Wrapper::MGi, copy and paste the appropriate command in to your terminal.
cpanm
cpanm ClearCase::Wrapper::MGi
CPAN shell
perl -MCPAN -e shell install ClearCase::Wrapper::MGi
For more information on module installation, please visit the detailed CPAN module installation guide.