Transitioning from TeamWare to Mercurial (hg)

Contents Transitioning from TeamWare to Mercurial (hg) Introduction Terminology: Differences changesets no sccs no partial bringovers Command walkthrough help Bringing over (creating) a repository Working with files Editing files Adding files throwing away your local changes Printing status What files have local changes? Examining differences printing history history of one file show which lines in a file were touched by which revisions Working with parents printing the parent Syncing up with the parent Commiting a set of file changes in your local repository. Merging changes from your parent Putting back the changes to the parent repository hg Resources TeamWare to mercurial resources OS/Net Mercurial Transition Notes

Introduction

Teamware and Mercurial are both members of a group of Source Code Management (SCM) systems called Distributed SCMs (DSCM). This group also includes other SCMs like git, darcs, arch and others. The distributed nature of Teamware has always been one of its strongest
advantages over centralized systems, and so transitioning from Teamware to another DSCM lets us keep the ideas of parent and child like we've always enjoyed. But the two layer nature of Teamware is not needed anymore. So where you used to check files in and out of SCCS while working in your Teamware workspace, in most other DSCMs (including mercurial) that's not needed.

At the moment there are a lot of projects at Sun in the process of converting from Teamware to Mercurial, and the OpenSolaris team has a good help page to help people transition, but that page is fairly specific to the OpenSolaris project. I'll try to dig up all the resources I can for this page that are generic to helping any Teamware user to learn mercurial.

Terminology:

Working Directory : In mercurial, the term working directory refers to the source tree that's currently inside your repository. It's distinct from the database part of your repository. Some mercurial commands operate on the working directory, some operate on the database and some access or update both at the same time.

Differences

I'll try to list the major differences that will affect your daily life:

changesets

In Teamware, once you put back a group of files into a parent workspace, they go into an ocean of SCCS files. If you made a bugfix that touched two files, there's no way of associating those two files together again (other than their identifying SCCS comments), once they are put back. Mercurial groups related file changes into changesets. The changeset becomes an immutable part of the history of your repository.

no sccs

You can't use sccs info to see what files have local changes, and you can't look at the files to see if they are writable. You just edit the files you want. This takes some getting used to. To see which files have been changed, use the hg status command. Get used to using it instead of sccs tell or sccs info or whatever you're used to using now with teamware.

no partial bringovers

Because mercurial tracks changesets across all the sources, its local database inside your repository clone needs to include information about all the source files in the repository. That doesn't mean your working directory has to have all the sources in it. You can remove the sources from your working directory, as long as you restrict your hg commit and hg status operations to only the subdirectories you're working in.

Command walkthrough

I'll start by stealing from the opensolaris page and removing the osol-specific stuff about using OpenSolaris repositories and bundle files, and comparing hg subcommands with the wx script. After that, hopefully I'll be able to add more value after that.

The Mercurial program is named hg (the chemical symbol for Mercury). Every Mercurial command starts with hg, followed by the command name, followed by any relevant options and arguments.

help

Just running hg on the command line displays a list of commands.

$ hg
Mercurial Distributed SCM

basic commands (use "hg help" for the full list or option "-v" for details):

add        add the specified files on the next commit
annotate   show changeset information per file line
clone      make a copy of an existing repository
commit     commit the specified files or all outstanding changes
...

The help command can be used to get more information about any command.

$ hg help diff
hg diff [-a] [-I] [-X] [-r REV1 [-r REV2]] [FILE]...

diff repository (or selected files)
...

Bringing over (creating) a repository

The equivalent of the TeamWare bringover command is the clone command which make a clone of a given repository.

hg clone /ws/onnv-clone onnv      # like bringover -p /ws/onnv-clone -w onnv .

Unlike TeamWare, Mercurial supports cloning and syncing repositories over HTTP and SSH.

hg clone ssh://anon@hg.opensolaris.org/hg/onnv/onnv-gate
hg clone http://hg.genunix.org/on.hg

Like TeamWare, each Mercurial repository is self-contained. When you clone a repository, the new repository becomes an exact copy of the existing one at the time of the clone.

Note: Mercurial does not support partial bringovers right now.

Working with files

Editing files

There is no equivalent of the sccs edit. Mercurial automatically keeps track of modified files.

Adding files

The equivalent of the sccs create command to add files to the workspace is the add command.

hg add <file1.c> ...    # like sccs create

These files will be added to the repository on the next commit.

throwing away your local changes

hg revert file.c   # like sccs unedit

Printing status

What files have local changes?

To see what files have been changed, use the status command.

hg status    # like putback -n .

Examining differences

The equivalent of the sccs diffs command is the hg diff command.

hg diff      # like sccs diffs for all modified files

Without any arguments, hg diff will print out the differences between all modified files in the repository.

Differences between files are shown using the unified diff format.

printing history

history of one file

To show which revisions in the history affected one specific file, use the hg log command.

hg log file.c    # like sccs prs file.c

show which lines in a file were touched by which revisions

hg annotate -n file.c    # like sccs print file.c

Working with parents

printing the parent

hg paths     # like workspace parent

Syncing up with the parent

The pull and update commands are used to sync up the workspace with the parent.

hg pull      # bringover latest changesets
hg update    # update working source to the latest changeset

The pull command pulls changes from the parent repository but does not actually make any changes to the files in the repository. The hg update command is used to actually update the files in the repository.

Note: These two commands can be combined into a single hg pull --update command.

A repository location could be passed to the pull command to sync the repository with a different parent.

hg pull --update /ws/onnv-gate
hg pull --update ssh://anon@hg.opensolaris.org/hg/onnv/onnv-gate
hg pull --update http://hg.genunix.org/on.hg

The equivalent of the bringover -n command (used to check what changes would be carried out without actually modifying the workspace) is the incoming command.

hg incoming
hg incoming ssh://anon@hg.opensolaris.org/hg/onnv/onnv-gate

Commiting a set of file changes in your local repository.

The equivalent of the sccs delget command is the commit command. This is only roughly similar because the {sccs delget}} command only creates a one-file delta. The hg commit command creates a changeset.

hg commit

This command drops us into an editor (configured using the EDITOR and HGEDITOR environment variables) where we can add the putback comments. Once we save the changes and quit the editor, the changes are committed to the repository.

Merging changes from your parent

In teamware you bringover, (which creates file conflicts), then you use the resolve command to merge your changes. Teamware has the filemerge tool to support merging.

In Mercurial, you use "hg pull", (which creates a repository with two heads), then you use "hg merge" to merge the two heads together. Mercurial can be hooked up to multiple file-merging tools, and some people have hooked it up to the filemerge program from teamware. KDiff3 is also nice. This can be customized both at a site level, and at the individual level.

Putting back the changes to the parent repository

In teamware, the tools prevent you from putting back if it will result in conflicts in the parent workspace.
In Mercurial, putting back a divergent branch is not prohibited by the tools. But it's easy to get confused about which branch you're working on. So almost everyone has rules against putting back changesets without first merging them with the tip of the parent repository. This means you should use the same rule as teamware: always bringover and merge in your own workspace, before putting back.

All changes up to this point have been in the working clone repository. The changes can be put back to the parent repository using the push command.

hg push /ws/onnv-gate
hg push ssh://anon@hg.opensolaris.org/hg/onnv/onnv-gate
hg push http://hg.genunix.org/on.hg

This command is the equivalent of the "workspace parent -p /ws/onnv-gate" and "putback" TeamWare commands.

It is not mandatory to provide the path to the repository to push the changes to. If no repository is specified, the changes will be pushed to the repository we cloned from.

The equivalent of the "putback -n" command is Mercurial's "outgoing" command.

hg outgoing
hg outgoing ssh://anon@hg.opensolaris.org/hg/onnv/onnv-gate

hg Resources

NEW: Training slides for NetBeans Mercurial conversion project

• http://wiki.netbeans.org/wiki/attach/HgTrainingMaterials/preso.xhtml#(1)

First of all, there are a lot of good pages on selenic.com:

• http://www.selenic.com/mercurial/wiki/index.cgi/UnderstandingMercurial
• http://www.selenic.com/mercurial/wiki/index.cgi/Tutorial
• http://www.selenic.com/mercurial/wiki/index.cgi/QuickStart

A good reference:

• http://hgbook.red-bean.com/hgbook.html

A comparison of source management systems:

• http://better-scm.berlios.de/comparison/comparison.html#main

A good blog entry with a command comparison table:

• http://blogs.sun.com/martin/entry/mercurial_for_teamware_users

CVS to HG transition page for NetBeans

• http://wiki.netbeans.org/wiki/view/HgMigration

Forest is an extension to handle nested repositories:

• http://www.selenic.com/mercurial/wiki/index.cgi/ForestExtension

TeamWare to mercurial resources

• genunix.org has several pages related to the Open Solaris effort to transition to hg
  • Issues with rename enumerated as part of the opensolaris transition:
  • http://www.genunix.org/wiki/index.php/Hg_rename_issues
  • The OpenSolaris getting started page for teamware users is also good:
  • http://www.genunix.org/wiki/index.php/Mercurial
  • The opensolaris transition project:
  • http://www.genunix.org/wiki/index.php/SCMVolunteers

Another Wiki with more nitty gritty details and open issues:

• Teamware to Mercurial Implementation

• Kelly O'Hair has been working on the Java transition:
  • I didn't see this blog entry from Kelly until after I finished the above. More stuff to steal:
  • http://blogs.sun.com/kto/entry/transitioning_from_teamware_to_mercurial
  • An earlier list of gotchas
  • http://blogs.sun.com/kto/entry/the_mercurial_transitions

There is a simple python work-alike for the teamware "filemerge" utility.

• http://www.genunix.org/wiki/index.php/gPyFm

A tool written by the OpenSolaris transition team to bridge between OS/Net TW and hg repos.

• http://www.genunix.org/wiki/index.php/MercurialBridge

OS/Net Mercurial Transition Notes

• A Heads-up collection from Mark Nelson: Summary
• OSol transition guide : http://www.opensolaris.org/os/community/tools/scm/hg_teamware_transition/