NAME

ClearCase::Wrapper::MGi - Support for an alternative to UCM.

SYNOPSIS

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.

The alternative to UCM consists in a novel branching model, and a concept of incremental types.

CLEARTOOL EXTENSIONS

• 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:

  -all

  Show 'uninteresting' versions, otherwise skipped:

  - bearing no label

  - not at a chain boundary.

  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.

  -obsolete

  Add obsoleted branches to the search.

  -short

  Skip displaying labels and 'labelled' versions and do not report alternative paths or siblings.

  -fmt

  Substitute to the default representation of every version (optionally including labels), the output of des -fmt 'format' version.

  The indentation is preserved, but all the verbose annotations (offspring, siblings, alternatives) are stripped (as in short mode).

  -depth

  Specify a maximum depth at which to stop displaying the genealogy of the element.

  -offspring

  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:

  -ver/sion

  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.

  Flag:

  -nco

  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.

  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:

  EqInc

  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.

  PrevInc

  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.

  Flags:

  -fam/ily

  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.

  -inc/rement

  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).

  -arc/hive

  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.

  -glo/bal

  Support for global family types is preliminary.

  -con/fig

  Make or increment lbtypes in all vobs used by a config record.

  -exc/lude

  When using a config record, exclude comma separated vobs for label type creation.

  -full/copy

  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.

  -arc/hive

  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.

  -glo/bal

  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.

  [ 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:

  -fam: remove all types in the family, as well as the RmLBTYPE attribute type. This is a rare and destructive situation, unless the equivalent type is LBTYPE_1.00 (the family was just created). The types actually affected ought of course to be unlocked.

  -inc: remove the current increment, and move back the family type onto the previous one. Note: RmLBTYPE attributes ... may be left behind (for now...)

  default (no flag): remove the family (floating) type and the current increment, storing the information about the previous one into the "hidden" LBTYPE_0 type, from which it may be recovered with a later 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.

• 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:

  - %PVn and %PSn take the genealogy into consideration

  - %[...]l accepts a regexp to filter the labels to be displayed

• 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:

  - fix some errors resulting from our breaking a tool assumption

  - provide a greppable standard output

  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...)

  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.

  This defeats most of the usefulness of the tool.

  One offers two alternative new flags to produce line oriented output:

  -line: line oriented output suitable for grepping, with no truncation

  -grep: use Perl to grep the output of annotate

• 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.

  The supported flags are:

  -from

  -lab/el

  -sum/mary

  -c/omment

  -quiet

  -force: mutually exclusive with rollback

  -rollback: this restores the default behaviour of the original synctree. See below: stop

  The default options used are (with respect to the standalone script):

  ci/checkin

  yes: no preview option, no prompting for confirmation

  rmname, if only one argument, and a directory

  rellinks: turn absolute symlinks within sbase into relative ones

  reuse: attempt to avoid creating evil twins

  vreuse, if label: do not create identical versions if can label old ones

  cr: config records are respected -- using "checkin -from"

  stop: abort in case of error.

  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 AND LICENSE

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.

SEE ALSO

perl(1), ClearCase::Wrapper, ClearCase::Wrapper::DSB, ClearCase::Argv, ClearCase::SyncTree