h1. Transitioning from TeamWare to Mercurial (hg)
{info:title=Contents}
{toc}
{info}
{anchor:introduction}
h2. 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.
{anchor:terminology}
h2. Terminology:
||Teamware|| ||Mercurial||
|workspace| {{-->}} |repository|
|delta| {{-->}} |changeset/revision|
|putback| {{-->}} |push|
|bringover| {{-->}} |pull|
|delget| {{-->}} |commit|
|Codemgr_wsdata| {{-->}} |.hg|
*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.
----
{anchor:differences}
h2. Differences
I'll try to list the major differences that will affect your daily life:
h3. (*b) 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.
h3. (*b) 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.
h3. (*b) 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.
----
{anchor:commands}
h2. 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.
h3. help
Just running hg on the command line displays a list of commands.
{noformat}
$ 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
...
{noformat}
The help command can be used to get more information about any command.
{noformat}
$ hg help diff
hg diff [-a] [-I] [-X] [-r REV1 [-r REV2]] [FILE]...
diff repository (or selected files)
...
{noformat}
h3. Bringing over (creating) a repository
The equivalent of the TeamWare bringover command is the clone command which make a clone of a given repository.
{noformat}
hg clone /ws/onnv-clone onnv # like bringover -p /ws/onnv-clone -w onnv .
{noformat}
Unlike TeamWare, Mercurial supports cloning and syncing repositories over HTTP and SSH.
{noformat}
hg clone ssh://anon@hg.opensolaris.org/hg/onnv/onnv-gate
hg clone http://hg.genunix.org/on.hg
{noformat}
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.
h3. Working with files
h4. Editing files
There is no equivalent of the sccs edit. Mercurial automatically keeps track of modified files.
h4. Adding files
The equivalent of the sccs create command to add files to the workspace is the add command.
{noformat}
hg add <file1.c> ... # like sccs create
{noformat}
These files will be added to the repository on the next commit.
h4. throwing away your local changes
{noformat}
hg revert file.c # like sccs unedit
{noformat}
h3. Printing status
h4. What files have local changes?
To see what files have been changed, use the status command.
{noformat}
hg status # like putback -n .
{noformat}
h4. Examining differences
The equivalent of the {{sccs diffs}} command is the {{hg diff}} command.
{noformat}
hg diff # like sccs diffs for all modified files
{noformat}
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.
h3. printing history
h4. history of one file
To show which revisions in the history affected one specific file, use the {{hg log}} command.
{noformat}
hg log file.c # like sccs prs file.c
{noformat}
h4. show which lines in a file were touched by which revisions
{noformat}
hg annotate -n file.c # like sccs print file.c
{noformat}
h3. Working with parents
h4. printing the parent
{noformat}
hg paths # like workspace parent
{noformat}
h4. Syncing up with the parent
The pull and update commands are used to sync up the workspace with the parent.
{noformat}
hg pull # bringover latest changesets
hg update # update working source to the latest changeset
{noformat}
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.
{noformat}
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
{noformat}
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.
{noformat}
hg incoming
hg incoming ssh://anon@hg.opensolaris.org/hg/onnv/onnv-gate
{noformat}
h4. 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.
{noformat}
hg commit
{noformat}
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.
h4. 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.
h4. 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.
{noformat}
hg push /ws/onnv-gate
hg push ssh://anon@hg.opensolaris.org/hg/onnv/onnv-gate
hg push http://hg.genunix.org/on.hg
{noformat}
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.
{noformat}
hg outgoing
hg outgoing ssh://anon@hg.opensolaris.org/hg/onnv/onnv-gate
{noformat}
----
{anchor:resources}
h2. hg Resources
(y) 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
h2. 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
h2. OS/Net Mercurial Transition Notes
* A Heads-up collection from Mark Nelson: [Summary|OSNet Mercurial Transition Summary]
* OSol transition guide : http://www.opensolaris.org/os/community/tools/scm/hg_teamware_transition/
{info:title=Contents}
{toc}
{info}
{anchor:introduction}
h2. 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.
{anchor:terminology}
h2. Terminology:
||Teamware|| ||Mercurial||
|workspace| {{-->}} |repository|
|delta| {{-->}} |changeset/revision|
|putback| {{-->}} |push|
|bringover| {{-->}} |pull|
|delget| {{-->}} |commit|
|Codemgr_wsdata| {{-->}} |.hg|
*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.
----
{anchor:differences}
h2. Differences
I'll try to list the major differences that will affect your daily life:
h3. (*b) 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.
h3. (*b) 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.
h3. (*b) 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.
----
{anchor:commands}
h2. 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.
h3. help
Just running hg on the command line displays a list of commands.
{noformat}
$ 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
...
{noformat}
The help command can be used to get more information about any command.
{noformat}
$ hg help diff
hg diff [-a] [-I] [-X] [-r REV1 [-r REV2]] [FILE]...
diff repository (or selected files)
...
{noformat}
h3. Bringing over (creating) a repository
The equivalent of the TeamWare bringover command is the clone command which make a clone of a given repository.
{noformat}
hg clone /ws/onnv-clone onnv # like bringover -p /ws/onnv-clone -w onnv .
{noformat}
Unlike TeamWare, Mercurial supports cloning and syncing repositories over HTTP and SSH.
{noformat}
hg clone ssh://anon@hg.opensolaris.org/hg/onnv/onnv-gate
hg clone http://hg.genunix.org/on.hg
{noformat}
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.
h3. Working with files
h4. Editing files
There is no equivalent of the sccs edit. Mercurial automatically keeps track of modified files.
h4. Adding files
The equivalent of the sccs create command to add files to the workspace is the add command.
{noformat}
hg add <file1.c> ... # like sccs create
{noformat}
These files will be added to the repository on the next commit.
h4. throwing away your local changes
{noformat}
hg revert file.c # like sccs unedit
{noformat}
h3. Printing status
h4. What files have local changes?
To see what files have been changed, use the status command.
{noformat}
hg status # like putback -n .
{noformat}
h4. Examining differences
The equivalent of the {{sccs diffs}} command is the {{hg diff}} command.
{noformat}
hg diff # like sccs diffs for all modified files
{noformat}
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.
h3. printing history
h4. history of one file
To show which revisions in the history affected one specific file, use the {{hg log}} command.
{noformat}
hg log file.c # like sccs prs file.c
{noformat}
h4. show which lines in a file were touched by which revisions
{noformat}
hg annotate -n file.c # like sccs print file.c
{noformat}
h3. Working with parents
h4. printing the parent
{noformat}
hg paths # like workspace parent
{noformat}
h4. Syncing up with the parent
The pull and update commands are used to sync up the workspace with the parent.
{noformat}
hg pull # bringover latest changesets
hg update # update working source to the latest changeset
{noformat}
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.
{noformat}
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
{noformat}
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.
{noformat}
hg incoming
hg incoming ssh://anon@hg.opensolaris.org/hg/onnv/onnv-gate
{noformat}
h4. 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.
{noformat}
hg commit
{noformat}
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.
h4. 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.
h4. 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.
{noformat}
hg push /ws/onnv-gate
hg push ssh://anon@hg.opensolaris.org/hg/onnv/onnv-gate
hg push http://hg.genunix.org/on.hg
{noformat}
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.
{noformat}
hg outgoing
hg outgoing ssh://anon@hg.opensolaris.org/hg/onnv/onnv-gate
{noformat}
----
{anchor:resources}
h2. hg Resources
(y) 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
h2. 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
h2. OS/Net Mercurial Transition Notes
* A Heads-up collection from Mark Nelson: [Summary|OSNet Mercurial Transition Summary]
* OSol transition guide : http://www.opensolaris.org/os/community/tools/scm/hg_teamware_transition/