How to properly use hg share extension?

Question

Say I have cloned a repo to a directory called ~/trunk and I want to share a branch named my-new-branch to the directory ~/my-new-branch. How would I do that with the hg share extension?

This is what I've been doing:

cd ~
hg share trunk my-new-branch

But then when I cd into the new directory I have to hg up to the branch?

Confused.

Answer 1

IMO share is a very useful command which has some great advantages over clone in some cases. But I think it is unfortunately overlooked in many instances.

What share does is to re-use the 'store' of Mercurial version control information between more than one local repository. (It has nothing directly to do with branching.)

_{The 'store' is a bunch of files which represents all the history Mercurial saves for you. You don't interact with it directly. Its a black box 99.99% of the time.}

share differs from the more commonly-used clone command in that clone would copy the information store, taking longer to run and using potentially a lot more disk space.

The "side effect" of using share rather than clone is that you will instantly see all the same commits in every shared repository. It is as if push/pull were to happen automatically among all the shared repos. This would not be true with clone, you'd have to explicitly push/pull first. This is quite useful but something to be mindful of in your workflow because it may surprise you the first time you use it if you are only used to clone.

---

If you want to work in multiple branches (named or unnamed) of your project simultaneously, either clone or share will work fine. Once you have created the second repository, yes you need to update it to whatever changeset you want to begin working on.

Concrete example using share:

hg clone path\to\source\repo working1   # Create local repo working1 cloned from somewhere
cd working1
hg up branchname1  

cd ..

hg share working1 working2  # shares the 'store' already used for working1 with working2
cd working2
hg up branchname2  # some other branch or point to start working from

As soon as you commit something in working1 that commit will be visible in the history of working2. But since they are not on the same branch this has no real immediate effect on working2.

working2 will retain path\to\source\repo as its default push/pull location, just like working1.

---

My own practice has been to create numerous locally shared repositories (quick, easy, saves space) and work in various branches. Often I'll even have a few of them on the same named branch but set to different points in history, for various reasons. I no longer find much need to actually clone locally (on the same PC).

---

A caveat -- I would avoid using share across a network connection - like to a repo on a network drive. I think that could suffer some performance or even reliability issues. In fact, I wouldn't work off a network drive with a Mercurial repo (if avoidable) in any circumstance. Cloning locally would be safer.

Secondly -- I would read the docs, there are a few weird scenarios you might encounter; but I think these are not likely just based on my own experience.

---

Final note: although share is implemented as an "extension" to Mercurial, it has been effectively a part of it since forever. So there is nothing new or experimental about it, don't let the "extension" deal put you off.