Say you have your data in a SVN tree with a layout like

/Trunk/ProjectA

/Trunk/ProjectB

/Branches/ProjectA

/Branches/ProjectB

/Tags/ProjectA

/Tags/ProjectB

What’s the best way to organize your code in the Mercurial/Kiln model?

In Subversion, storing lots of different projects in a single repository is commonplace. In Mercurial (and other DVCSes), storing one project per repository, and having lots of repositories, makes far more sense. That’s why Kiln’s repository interface is optimized to make it easy for you to organize your repositories in a meaningful way by project, group, and repo. So, at a base level, a normal Kiln install corresponding to your existing Subversion repositories would have at least two repositories, ProjectA and ProjectB.

There are several different ways to do branching in Mercurial, but the one we like best, and have put the most effort into supporting for Kiln 1.0, is to use one repository per branch. In this scenario, you would end up with four repositories in the example: ProjectA and ProjectABranch, and ProjectB and ProjectBBranch.

In general, we’ve found that making Kiln projects correspond to FogBugz projects is the right way to go, but we have exceptions in our own install in both directions (Kiln projects lacking a corresponding FogBugz project and FogBugz projects lacking Kiln ones). So it’s likely you’d have two Kiln projects, each with two repositories, in your example. We’ve even made it so that you can link Kiln Projects to FogBugz projects, which sets the default project for code reviews on that repo.


Now, if you have an existing monolithic Subversion repository you converted, and you’ve decided that you want to break that into several smaller Mercurial repositories, there’s good news and bad news. The bad news is that our importer tool cannot currently help you with that, so you’re going to need to use the Mercurial command-line converter; and that the converted repositories will be “different” from the original, meaning that you’ll need to re-create them in Kiln and re-clone them locally once the split is complete. The good news is you’ll need to do that at most once, it’s fast, it’s pretty easy, and it’ll make your life much better down the road.

To do it:

  1. Figure out how you want to split your repository. Hopefully, you have two or more directories, called (e.g.) foo/bar/ProjectA and foo/bar/ProjectB, that correspond to the projects you want to split out.
  2. Make a file called filemap-projecta.txt and put the following into it:
    include foo/bar/ProjectA
    rename foo/bar/ProjectA.

    Note that you should use Unix paths, even if you’re doing this on a Windows system.

  3. On a clone of the repository that I’ll assume is called OriginalRepo, run
    hg convert --filemap filemap-projecta.txt OriginalRepoProjectA
  4. Go into the newly-created ProjectA repository, run hg up, and check the result. With luck, you should find that everything under foo/bar/ProjectA is there, and is now in the root of the repository.
  5. Repeat for other projects you want to split out, changing the lines in filemap-projecta.txt appropriately.
  6. Create repos in Kiln for each of the converted repositories.
  7. Push your new repositories into Kiln.