The AccuRev provider implements Maven's generic SCM API for the AccuRev SCM system.
Use Cases
The provider must handle a number of different use cases:
- Label a source tree and check out that label to a temp directory (the release plugin)
- Provide a changelog between dates/revisions and checkout code to a directory (Continuum et al)
- Map a number of commands designed for CVS/SVN onto the semantics provided by AccuRev (the scm plugin)
Details
The main semantic issue faced by the provider is CVS/SVN's concept of a working copy versus AccuRev's concept of a workspace.
CVS/SVN allow the user to checkout any repository location to any local directory at will and tracks this by keeping metadata in a CVS/.svn directory. AccuRev uses a "workspace" concept whereby it keeps track of the physical filesystem locations within the server. This necessarily creates restrictions on where projects may be checked out to, in that overlapping workspaces are not allowed.
The other major constraint is the uniqueness of workspace and tag names which cannot be reused. It is up to the user to implement some namespace standards to manage this.
URLS
scm:accurev:[user/pass[@host[:port]]][:streamName][:?key=value&key=value...][:/project/path]
- user/pass See login below.
- @host:port Specify the accurev server to connect to. If used all accurev commands will include a -H host:port argument.
- streamName provide a "version" for initial checkouts. Only really required for HEAD/trunk type checkouts such as done by the tck tests.
- ?prop=value various properties
- accurevExe Path to the accuRev executable
- tagFormat Maps branch/tag/version names to AccuRev stream names and vice-versa. See the "tag" command below. If provided all streams are expected to conform to this naming standard.
The above can also be referenced as system properties - "maven.scm.accurev.propertyname"
- /project/path is the relative path of your project within AccuRev. Note that AccuRev has no concept of checking out a sub-directory so checkouts always create this physical path under the working directory.
NOTE: There is no specification of depot as it can be derived from the working directory or stream names.
SCM Commands
Login
The recommended method is to run accurev login externally. For automated SCM operations (e.g. Continuum), suggest using accurev login -n to create a persistent login that won't expire in the middle of your build.
If you really want to embed this information in URLS and config files, read on.
Username and password can either come from the URL, or from a <server> section in a settings.xml file.
If supplied then we will login to the server with accurev login <user> -A . This returns an authentication token to the process which is used in subsequent command invocations by passing
-A <authtoken> to the accurev cli.
- Warning this method will expose your accurev session token to anyone snooping command lines (eg via ps) and will be exposed in debug output
- Warning under Windows the user's password is passed on the command line, and will be exposed in debug output
- Note We never logout. AccuRev returns the same session id for a user anyway, and unused sessions will expire.
Checkout
- Persistent checkout (isPersistCheckout() == true)
The basic premise is to end up with a workspace rooted at the checkout directory with contents as at the specified version.
Versions are of the form [basisStream/[tranid|timestamp]]. If a version is not supplied, the streamName from the url is used as the basisStream for the workspace.
A non-empty checkout directory is not allowed. It will be created if it does not exist.
If the checkout directory is a subdirectory of an existing workspace other than the /project/path specified in the URL then the checkout will be aborted.
If a workspace exists at the checkout location then it will be reused. If necessary the basisStream of the workspace will be reparented with accurev chws -b.
If the checkout location is not an existing workspace then a new one is created with accurev mkws
Workspace names are generated by concatenating the basis stream and the base name of the checkout directory unless the basis stream contains the base name or vice versa, in which case the longer one is used.
If the generated workspace name already exists as stream name elsewhere in AccuRev then the checkout will fail.
The final step is to update the workspace to the tranid/timestamp specified in the supplied version (or "highest" if not specified). Note that workspaces cannot go backwards, even when reparented or repopulated and you will get "transaction out of range" errors if you try. Since you can't update a workspace to a transaction less than one used to create it, any transaction information supplied for an initial checkout will be silently ignored.
- Non persistent checkout
If the persistCheckout flag is false, the provider redirects the checkout to the export command as below.
Export
A populate outside of a workspace accurev pop -V -l If the checkout directory exists within a subdirectory of a workspace AccuRev would normally generate an error. To work around this restriction the existing workspace is temporarily deactivated during the export.
For AccuRev 4.9.x the provider supports export to a specific tranid/timestamp.
Tag
Creates a snapshot accurev mksnap for the basis stream of the workspace specified by the working directory.
A system property "maven.scm.accurev.tagFormat" can be used to specify a java.util.Formatter string used to convert from a maven scm tag name to an accurev stream name for the snapshot.
Useful for the release plugin in cases where you have a certain stream naming convention enforced by an AccuRev admin trigger.
Update
Equivalent to accurev update. The working directory must be in a workspace (or reftree) and that whole workspace is updated. here has been the option to populate to a specific transaction id. A version of the form basisStream/timeSpec can be supplied (tag/branch/revision). If the basis stream of this version is different to the current basis of the workspace, then a accurev chws is performed. The timespec component is passed as the -t option to the update command. If not supplied the timespec is set to "highest".
Changelog with update is supported. If no start_date for the changelog is supplied, then we start from the transaction id of the workspace before the update. The end version for the changelog is the supplied version as above (defaulting to "now").
If the start and end versions refer to the same basis stream, then a changelog is performed using the changelog command described below. If the streams are different, then a dummy changeset is synthesised to simply list the updated files.
Status
Runs a series of accurev stat calls to identify various types of modifications.
- accurev stat -D defunct files => "DELETED" status
- accurev stat -k kept files
- accurev stat -m modified files
- accurev stat -b to find state of kept and modified files in the backing stream to determine whether their Maven ScmFileStatus is "ADDED" or "MODIFIED". An unintended change in stat -b output for AccuRev 4.9.0 breaks this distinction.
- accurev stat -M missing files => "MISSING" status
- accurev stat -x external files => "UNKNOWN" status
Changelog
List the changes promoted into a stream between times/transaction ids.
accurev hist -s stream -t T1-T2
For AccuRev > 4.7.2 also issues
diff -v stream -V stream -t T1-T2
to synthesise a changeset representing files that have changed upstream.
If the version specifies a workspace stream the history of the workspace is merged with the above hist/diff performed on the workspace's basis stream
Diff
Not yet implemented
Diff between versions. If only a base directory supplied in the fileset will diff the whole workspace.
If both version specified * accurev diff -v <start> -V <end>
If only one version specified then comparison is against workspace filesystem * accurev diff -v <start|end>
If no versions specified and stream is in URL, then compare workspace to that stream * accurev diff -v <urlStream>
If no versions specified and no stream in URL, then compare workspace to basis stream * accurev diff -b