Question

So I’m using mercurial for a project of mine, I’m the only developer.
I usually use the default branch for actual developing, I use some short lived branches for new-features, and that’s fine: I create them, write the new feature and if it works good enough, I merge that branch in the default branch and never use it again.
But I’d like to write documentation in a different branch, since I don’t really want to “pollute” the default branch with docs commits.

After I have written enough documentation for the stuff I have in the default branch I merge the docs branch in the main one. BUT after a while I’d like to use the docs branch again, and I have to pull the changes from the main one, or create another new branch.

What’s the best workflow to deal with this? Is my approach entirely wrong?

Answer 1

Placing documents in source control is a little bit strange. If the documents are binary (.doc/.docx/.xlsx), Hg will not be able to merge them. If you’re storing .html, .xml, or some plain text format then it will do a slightly better job. There are a few open source systems that will allow you to use Hg and provide separate document management (Redmine, for one)

Assuming you’ve just merged docs into default you can continue using the docs branch by doing this:

> hg update docs   # update to the docs branch
> hg merge default # merge default into docs branch
(do some work)
> hg commit -m "adding new things to docs branch"
(merge into default when ready)

By merging default into docs, you’re making sure that docs has all changes that existed on default. Performing a subsequent commit on docs will effectively allow you to continue working on that branch. Another way to say this is that merging is directional in Hg – if you want docs to be up to date with default, you’ve got to perform that merge explicitly.