Version-control Concepts

AbaPerls supports multiple version-control systems. OK, so it only supports Team Foundation Server and Visual SourceSafe, but two version-control systems is sufficiently many for AbaPerls to adapt an abstract view. This page discusses concepts in AbaPerls that are common to all version-control systems. There are also pages that discuss peculiarities for each supported version-control system.

Contents:
   Supported Version-control Systems
   Labels and Version Specifications
   The VC-path

Supported Version-control Systems

AbaPerls supports two version-control systems, Visual SourceSafe and Team Foundation Server. The architecture is such that it would be relative easy to add support for a third and fourth version-control system. Not that this is planned to happen any time soon. And there is a caveat: different version-control systems tend to have quite different mindsets. This certainly applies to SourceSafe and TFS. AbaPerls has its origins with SourceSafe, and was SourceSafe-only for many years.

Some things in AbaPerls are designed to work the same, no matter the version-control systems, for other things AbaPerls attempts to adapt to the mindset of the version-control system. And not the least adapt to the capabilities and limitations of the version-control system.

AbaPerls permits you to use multiple version-control systems in parallel, but reasonably you would only use two systems if you are in a transitional stage, for instance on a migration path from SourceSafe to TFS.

If there are differences in concepts between SourceSafe and TFS that affects a certain command, this is noted the page for that command. There is also one page that discusses specific SourceSafe concepts and one page for TFS-specific concepts.

Three concepts are universal in AbaPerls:

The first point is described in detail on the page The AbaPerls Subsystem Structure. Here just a short recap: AbaPerls mandates a certain structure how to organise different versions of subsystems, and within each version how SQL files should be organised based on object type and file extension.

Labels and Version Specifications

There are several places in AbaPerls where you provide a version specification. With the commands ABASQL, DBBUILD and DBUPDGEN you provide the version specification with the ‑label option. As the name indicates, most of the time your version specification is also a label in your version-control system. The version specification can also be a date or an explicit version number.

The exact interpretation of the version specification depends on the version-control system in question. Follow these links to see the rules for SourceSafe and TFS.

AbaPerls has a standard label format, LetterMajor.Middle.Minor which it uses to determine for instance, whether an update script is ahead, behind or in sync with a database. This format is further detailed in the section Label Conventions on the page The AbaPerls Subsystem Structure.

The VC-path

To access an item – file or a directory – under version control you need a VC-path. You use the VC-path in system-definition files, in config-files and most of all on the command-line as the argument with the options ‑VC and ‑config. If you are using TFS, AbaPerls is able to map your working folder to a VC-path, as discussed on the TFS page. This ability is not available with SourceSafe.

A complete VC-path consists of three components:

  1. A VC-system designator followed by a double colon.
  2. A repository.
  3. A path within the repository, with a leading dollar character.

The general format for this is:

VCsys::Repository[/]$/directory-path[/file]

VCsys is one of TFS or VSS.

The format of Repository depends on the version-control system. For SourceSafe a complete repository specification is the path to the DATA directory, for instance F:\Development\Our-db\Data. It can also be a UNC-path as in \\SSBOX\SourceSafeDB\Data. For TFS it is an URL with port number and virtual directory for the team project collection, for instance http://TFSRV:8080/tfs/DeaultCollection. Repository may have a trailing /. It is not compulsory, but very much recommended.

Within the repository, the path to an object – a file or a directory – always starts with a $ character, and directories in the hierarchy are always separated by a forward slash, /. Very conveniently, both SourceSafe and TFS use this format internally.

If the VC-path includes characters special to the command-line environment, such as space, you need to enclose the path in double quotes (")

AbaPerls goes head over heels to save you from having to specify the VC-system and a complete repository specification, and many examples in the AbaPerls manual use an abbreviated VC-path.

Below follow the rules from two different angles. First how much you need to specify if you want to use SourceSafe or TFS. Then there is a list of the steps, AbaPerls take internally. But first a non-rule. AbaPerls does not check whether you have SourceSafe or TFS installed. Thus, even if you don't use TFS at all, you may still get an error message relating to TFS because AbaPerls made an incorrect guess. In the same vein, if you only use TFS you may still get an error message related to SourceSafe.

If you want to use SourceSafe:

  1. You can leave out Repository entirely if you have defined the environment variable SSDIR and it refers to the SourceSafe database you want to access. SSDIR should be the path to the directory where SrcSafe.ini for the database resides.
  2. If the SourceSafe database resides directly under S:, you only have to specify only the directory name. That is, if there is a SourceSafe database S:\AbaSec, you can specify a VC-path like AbaSec/$/MyProject.
  3. If neither of the first two points is applicable, you need to specify the full path name, either with drive letter or a UNC path. You can always leave out the final \Data. You can use both backslashes and forward slashes as path delimiter.

If you want to use TFS:

  1. You can leave out Repository if you have exactly one workspace defined (and you have not defined SSDIR). AbaPerls will then deduce which TFS server and team-project collection to connect to from this singe workspace. You can use the command TF WORKSPACES to review which workspaces you have. You can use the command TF WORKSPACE to delete a workspace you don't need. (The TF command is the command-line utility for Team Foundation Server, and not part of AbaPerls.)
  2. You can give a single name for Repository. AbaPerls then assumes that is the server, and fills in the rest with defaults. That is, protocol http:, port 8080, virtual directory TFS and a team-project collection named DefaultCollection. That is, if you specify a repository TFSSRV, AbaPerls will attempt to connect to http://TFSSRV:8080/tfs/DefaultCollection.
  3. If you specify a Repository that includes a slash, this is interpreted as Server/Collection. That is, if you specify TFSSRV/MyCollection, this is expanded to http://TFSSRV:8080/tfs/MyCollection.
  4. You should rarely have to specify the protocol, port number or virtual directory (the "tfs" part). This would only be required if the TFS administrator has installed Team Foundation Server in a non-standard way. But if you feel like it, you can says things like TFSSRV:8080 and get away with it.

These are the steps that AbaPerls take to guess, eh, determine whether you want to use SourceSafe or TFS:

  1. If you did not specify Repository, and SSDIR is defined, it's SourceSafe.
  2. Else if you left out Repository and SSDIR is not defined, AbaPerls settles for TFS.
  3. If you specify a single name for Repository and there is a directory S:\ Name\Data, AbaPerls assumes you mean SourceSafe.
  4. Else if you specify a single name for Repository and there is no matching directory under S:, AbaPerls assumes that you are referring to a TFS
  5. If Repository includes a backslash (\) anywhere, AbaPerls assumes that you are talking SourceSafe, since it cannot be a legal URL for TFS.
  6. If the VC-path includes a colon (:) followed by a digit, the VC-path must be a TFS URL, since this is not legal in a directory path.

Note that if AbaPerls would add support for a third version-control system, it is likely that these rules would be modified, and the number of shortcuts would be reduced.

Copyright © 1996-2012, Erland Sommarskog SQL-Konsult AB.
All rights reserved. AbaPerls is available under Perl Artistic License
This page last updated 12-06-13 9:49