Author: johnmark

Matching Commands

add –	Used as the way to identify local working copy files to be added to the repository with a commit. The key difference is that the operation is performed offline.
annotate –	Used to show the who changed what line in what revision for each line in a specific ASCII file revision. Subversion generally calls this command “blame,” but “annotate” is an alternate name.
checkout –	Used as a way to create your local working copy from the repository. Subversion’s command is basically a straight match, with the differences being in the structure and composition of the working copy itself.
commit –	Used as the way to publish local working copy changes to the repository. The key difference is again in the execution rather than the command itself. Subversion guarantees an atomic commit of all the modifications associated with the execution of this command, thus creating a changeset. Subversion also assigns each commit/changeset a global revision number rather than applying revision numbers on a per-file per-branch basis. That means each revision number is a unique identifier of a snapshot of the repository after the change set was applied.
diff –	Used to examine changes between two revisions of the same file. The biggest difference here with Subversion is the operation can be used offline to compare changes made in the working copy to the revision originally checked out. Additionally, CVS offers some of these commands as prefixed with an ‘r’ (as in “remote”), such as: cvs rlog, cvs rdiff, or cvs rtag. These are used to perform commands directly on CVS repository paths when no working copy is available. Subversion provides similar functionality, but through the use of remote repository URLs instead of working copy paths with its subcommands, such as: svn log URL or svn diff URL1 URL2.
export –	Used to create a project tree that does not have the CVS administration directories and files. Subversion’s implementation is basically equivalent, with the exception that a local working copy can also be used as the source of an export. In this case, export is an offline operation.
import –	Used to add and commit new files and directories en masse to the repository, CVS’ implementation required two tags to mark the work and supported a particular workflow it related to “vendor branches.” Subversion’s import functions in like manner, but the target can be the trunk and no tags are used. Subversion can support the “vendor branches” workflow, but allows for many other uses of import. Neither tool updates a local working copy, but instead writes directly to the repository.
log –	Used as the most common way to access the change history for an object (for example, the log messages associated with each commit/revision). Subversion’s implementation is the same, with the obvious exception that revisions reflect atomic commits so the log message has a larger context.
merge –	Used to apply the differences in two sources to a working copy path, marking conflicts that require human resolution, and implemented in CVS as an option to the update command. At this point, Subversion’s implementation is much the same, though merge tracking is on the horizon. The key difference is that Subversion tries to help the user avoid committing files where the conflicts have not been resolved. This is accomplished by adding the ‘svn resolved’ command. That command is required notification to Subversion that conflicts have been resolved. At that point, the file can be committed.
remove –	Used to delete files moving forward in history, but not remove all historical references to them. In Subversion, this operation is done offline and also can be used on directories. Additionally, CVS provided a way for administrators to permanently delete files, but Subversion currently takes a strict stance on version control and provides no ability to do such deletions short of a dump, modify, and load of the repository itself.
revert –	A command found only in Subversion used to remove all local changes, thereby returning the local working copy to the revision last retrieved from the repository.
status –	Used to show any local modifications in the working copy and to show what files are out of date with the repository. Many found the output to be difficult to read so they tended to use ‘cvs update’ to see their changes. Subversion has tried to make the output of this command easier to read and parse. It also defaults to being executed offline, thus only showing working copy changes. However, it can be invoked with a switch (–show-updates) to see what files in the working copy are out of date with the repository.
update –	Used as the way to merge changes committed to the repository by others into your local working copy, this command also reported on local working copy changes. Subversion has changed the command to be totally focused on merging the repository committed changes to the working copy leaving the reporting on local modifications to the status command.

Indirectly Matched Commands

edit/watch –	Used as a way to notify users that a file was being edited by another and to attempt to guide singular write access to the file. Subversion has implemented the more rigid lock/unlock approach, which guarantees that a single user can change a file that has locking enabled.
history –	Used as a way to report operational (for example: checkouts, commits, exports, tags, tags, updates, and releases) history for files matching substrings as executed by you, a specific user(s), or everyone, in a fairly difficult format. With Subversion, using Apache, such information is logged in the Apache logs and operational logging (a feature added in Subversion 1.3) must be enabled to get good information in those logs.
tag –	Used to put a human name on a distinct snapshot in time of the full repository or some portion of it, it is a distinct type of meta data in CVS. Subversion implements this concept as just a user’s specific and purposeful execution of the ‘svn copy’ command, which means it is not a type of meta data, but rather a unique path/directory in the repository. Subversion’s implementation provides a cheap and consistent operation that will not slow as the repository grows. Community best practices suggest a top level directory in the repository or in each project contained in the repository for tags (for example, /tags).

Alternatively Implemented Functionality

branch –	Used to establish a distinct line of development (for example, bugfix vs. development vs. developer), it is a specific type of tag in CVS. Subversion implements this concept as just a user’s specific and purposeful execution of the ‘svn copy’ command, which means a branch is just a unique path/directory in the repository. Subversion’s implementation provides a cheap and consistent operation that will not slow as the repository grows. Community best practices suggest a top-level directory in the repository or in each project contained in the repository for branches (for example, /branches).
keyword substitution –	Keyword substitution (the ability to substitute dynamic information about a file into the file itself) was controlled by parameters related to the file or working copy and carried an extensive list of keywords reflective of the underlying tool, RCS. Subversion implements keyword substitution through a Subversion-defined property, svn-keywords, (drops support of some RCS-specific keywords) and gives you more control over enabling specific ones versus all.
binary file handling –	CVS determined that a file was a binary by either the cvswrappers file (defaulting by file extensions) or when the file was added by a command parameter. It was operationally used to suppress line-end conversions and determine storage. Binary files were stored as whole files, so transmissions from client to server or vice versa always required the full file. The Subversion server does not concern itself with whether a file is a binary or a text/ASCII file, but rather uses the same binary delta differencing algorithm for both storage and transmissions from client to server or server to client. It leaves any concern with whether the file is binary to the client for purposes of ignoring line ending conversions.

This comparison is not intended to cover all the different nuances of using Subversion commands, but rather to give you a high-level overview of the similarities CVS commands have with their Subversion counterparts. It is not a substitute for Subversion training and command usage should be determined using the online help, as well as a good online or printed reference book.

Whether the goal is to bring in particular snapshots from other version control tools or to add a local directory structure to your existing Subversion repository, the ‘svn import’ command is a useful and easy to execute tool.

Command Name

svn import – Add and commit an unversioned file or directory structure to an existing Subversion repository.

General Syntax

svn import [PATH] URL

Command Description

Recursively add and commit a copy of PATH to URL. If PATH is not present, then the current directory is assumed. Parent directories are created in the repository as necessary.

Scope of Changes

Directly modifies the repository itself, but not a working copy. Working copies must use the ‘svn update’ command to reflect the changes made to the repository by this command in the local working copy(ies).

Online or Offline Operation

This command requires online access to the repository server and cannot be executed in offline mode.

Applicable Switches

–message (-m)	TEXT Indicates the commit log message you want associated with this command’s execution
–file (-F) FILE	The file listed should be used for the arguments in the execution of this command
–quiet (-q)	Only essential information should be output during the execution of this command
–non-recursive (-N)	Do not recurse beyond the directory that is the target of this command (default is recursive)
–username USER	User’s login account
–password PASS	User’s login password
–no-auth-cache	Tells Subversion not to cache the username and password in its administrative directories
–non-interactive	Do not prompt for username and/or password
–force-log	Tells Subversion to accept a suspicious parameter passed to the message or file switches as valid rather than to produce an error
–editor-cmd	EDITOR Tells Subversion to use an external editor to enter the commit log message
–encoding ENC	Tells Subversion that your commit log message is encoded in the characterset indicated
–config-dir DIR	Informs Subversion to read configuration from the specified directory rather than the default location
–auto-props	Enables auto-props (overriding what is set in config file)
–no-auto-props	Disables auto-props (overriding what is set in config file)
–ignore-externals	Tells Subversion to ignore any defined externals when executing this command

Examples

Import the local myproj directory into the root of the repository:
$ svn import -m “New import” myproj http://svn.open.collab.net/repos/projects/trunk
Adding myproj/sample.txt
–
Transmitting file data …………
Committed revision 16.
Import the local myproj directory into the trunk/misc directory (which does not need to exist in the repository prior to executing this command as the command will create the directory).
$ svn import -m “New import” myproj http://svn.open.collab.net/repos/projects/trunk/misc
Adding myproj/sample.txt
–
Transmitting file data …………
Committed revision 19.

Keep in mind that while these examples added directories and files to the repository, they did not create or update a working copy to reflect those changes. You need to either update an existing working copy or do a checkout to create a new one.

Overall Migration Approach

Needs Analysis

The first step in a project’s migration process is to evaluate the costs and benefits of migrating existing project data to Subversion. It is important that project stakeholders:

• Acknowledge the monetary and productivity costs associated with migrations
• Define the need and business / technical value of having the data migrated

CollabNet has found that the majority of projects do not experience value that is significant enough to justify the associated costs:

• Leaving legacy project data available in a slimmed down legacy SCM system is sufficient to satisfy the need for the occasional review of history.
• In other cases, taking a small set of revisions provides the right balance of value.
• In a limited set of cases, a full migration is justified.

During the needs analysis, it is also important to identify the scope of the data (revisions and associated metadata) to be migrated. It is not realistic to assume that a project needs full migration of all revisions and metadata. A change in version-control systems provides a perfect opportunity to review the contents of the project repository, and this clean up should be a significant aspect of identifying the scope of the data to be migrated.

Environment Assessment

In conjunction with the Needs Analysis, the potential technical limitations of a migration between two SCM systems need to be investigated. For pure version-control tools, the migration may not have any significant technical limitations, but for more advanced SCM tools, significant technical issues and limitations will arise and must be considered.

For example, several tools have implemented approaches to merge tracking, while the current version of Subversion does not support this feature. Should this data be ignored and result in lost “history” or should it be stored somewhere within Subversion, possibly with limited accessibility?

The difference in implementations of functionality may have important consequences on the scope and method of data migration. For example, many tools and project teams implement tagging or labeling liberally. Subversion implements tags as directories, so while tag creation is a “cheap” operation, it could result in a huge conglomeration of branches that add more confusion than value.

Configuration Management Planning

Every SCM tool has a unique set of benefits and features that a good configuration plan needs to utilize appropriately. Migration plans that fail to address changes to the project’s ongoing configuration management needs will provide limited value. Significant value and project satisfaction can be achieved with Subversion by modifying the configuration management plan to take advantage of Subversion’s unique benefits. For example, many configuration management plans limit tagging operations because the legacy SCM tool had performance limitations as the repository grew. Since Subversion’s tagging operation is cheap and consistent, there will likely be further uses for tagging that can provide value to the project. Alternatively, Subversion’s use of a single revision number across the repository to mark a snapshot in time could be used instead of tagging.

CollabNet can provide invaluable insight during the configuration management process, due to our unique and extensive expertise gained from developing, using, and supporting Subversion. CollabNet provides various consulting services to help teams recalibrate their development and configuration management processes before adopting Subversion (rather than transplanting current concrete approaches that worked well on the legacy system into Subversion).

Migration Planning

Once the project lead makes the initial project migration strategy assessment, CollabNet has found that an investment in proper upfront planning will result in a faster and easier migration. Strategies such as whether development might continue along in conjunction with some of the migration process versus a full shutdown of development while migration is executed may vary based on numerous factors.

It is also important that several practice migrations are executed, which use a snapshot (or a representative portion) of the project repository in an effort to anticipate any data migration issues prior to the execution of the real migration. Practice migrations significantly reduce potential final migration issues.

Concise information regarding the migration should be communicated to the entire project team. Team members should:

• Receive notification that the migration effort is in the planning stage so that they can offer relevant input.
• Understand the approach to the scope and migration method, so they can clearly understand how to access historical project data after the migration is complete.
• Familiarize themselves with Subversion usage, as well as changes to the current configuration management plan to take advantage of Subversion functionality.
• Know the actual migration timeframes to prepare and minimize its productivity impact.

Finally, project members should be notified when the migration is complete so they can begin to interact with Subversion on a full-time basis.

Subversion Training

Success with Subversion is not based solely on migrating project artifacts, but more importantly, on enabling users to be successful using Subversion. To that end, it is important that administrators and users receive the appropriate training and coaching that help them become productive in a short period of time. CollabNet offers deep Subversion training for both developers and administrators, which can be customized to meet the needs of specific projects and teams. We can also “train the trainer” when that approach is deemed more appropriate.

Migration Execution

The migration team must understand the impact of not having access to the project’s repository, and work with the project lead to limit that downtime, as well as to clearly communicate when the migration starts and finishes. CollabNet has executed numerous strategies around migration and has strong experience in a wide range of migration execution options.