NAME
ClearCase::Wrapper::MGi - Marc Girod's contributed cleartool wrapper functions
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.
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:
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.cmwiki.com/BranchOffMain0Instead 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 to cascade branches indefinitely. The logical version tree is restituted by navigating the merge arrows, to find all the direct or indirect contributors.
Flag:
MKBRANCH
Actually a special case of checkout.
Flag:
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, is 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. This is implemented as part of UCM, for fixed types, and magic config specs. The wrapper offers thus a similar functionality on base ClearCase.
The current baseline is embodied with floating labels, which are moved over successive versions. This floating type is however not mandatory. It is created with the -fam/ily flag. Families with no such floating type are just chains, and can still be used 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.
One attribute:
- DelInc
-
Deleted from increment. This functionality is not implemented yet.
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.
- -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.
- -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.
- -glo/bal
-
Global types (in an Admin vob or not) are incompatible with the family property.
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.
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.
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.
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
promotedto 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, to work around a bug in cleartool status.
COPYRIGHT AND LICENSE
Copyright (c) 2007 IONA Technologies PLC (until v0.05), 2008-2009 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