recommended method to add a *single file* as a subrepo to a mercurial repository

Question

I have a mercurial repository myProject:

myProject
|- file1.js
|- file2.css
|- useful.js

Now useful.js is a file with a few useful classes in it. I use it in multiple projects and as such it has its own repository:

useful
|- useful.js
|- example.js
|- README

The idea is that other people can check out useful, have alook at the file and the example and readme, and if they like it, they copy useful.js into their own project and make use of it.

Since useful.js is used in a few of my projects, what is the recommended way to keep it in sync? There is a restriction that useful.js must live in the top-level folder myProject, i.e. can't be nested. This makes it tricky to use subrepositories (and in any case, then I'd get the other files like example.js and README).

The other thing to note is that the useful repo has a few branches: default, version1, and version2. My projects that use useful.js also have branches default, version1 and version2. I'd like to make sure that whenever I switch between branches in myProject, my useful.js switches branches too. If not for that I could probably live with a symbolic link.

This situation doesn't seem particularly uncommon; how do others handle it? Just write a hook on update to check if I'm switching branches and switch accordingly? Plus hooks on commit, push, pull ? (basically replicate subrepo behaviour for the single file)?

cheers.

Answer 1

It is impossible to add only a part of a repository as a subrepository with Mercurial. Thus you can't add only a single file from a repository.

Even if your other repository contained only one file, you could'nt add it at the root level either.

You will have to find another way to include your useful.js file. You're mentionning hooks to do that, but I can't see a way to do it honestly without some kind of manual work. Personnally, I'll go with "simplicity" and do everything "by hand".

Concerning the branch switch, there's no builtin mechanism in Mercurial, but as you said you should be able to do that with a hook on update.

Answer 2

Given your use case, it would seem that you might want to consider using Yeoman and more specifically the Twitter Bower Package Manager. This way, rather than keeping a copy of the external dependency in your repository, just identify it in the Bower config.

Answer 3

Follow-up @krtek

Yes, in any case you can't have linked (with subrepo) useful.js at the root of superrepo, it must be inside subbir.

But - no, with some tricks your can get some iteration to requested result (branch-dependent useful.js and adding single file instead of all).

In order to achieve this, you have to re-read subrepository documentation ("any supported by Mercurial URL can be used for defining external subrepo...") and hg help urls, namely

An optional identifier after # indicates a particular branch, tag, or changeset to use from the remote repository

and note mentioning of branch. I.e - if you'll have special branch(es) with known name(es) in repository of useful and have in this branches only single useful.js, you can define subrepo with these added data - branch with single file for branch in superrepo

This way you'll have different subrepo specification in each branch of superrepo, have to merge branches with accuracy (always save "my") or define special mergetool for .hgsub files