# Friday, June 08, 2012

This is the eighth and final post in this series.   


With tagging you can more easily go back to a point in time or specific version of your code.  While tagging is not required for this, it makes it much easier.  Without labeling, a developer would have to read through logs and possibly source control changes to ascertain what version they need to go back to.  Instead, tag.  Make it easy on yourself or anyone coming behind you. 

When is it a good time to tag.  Every commit? I prescribe to substantial events in the code. At the very least, every time you release to production.  That way if a release goes bad you can go back to the old codebase very easily. Other times to consider tagging would be:

  • Large updates. 
  • Logical updates such as Feature A, Feature B, Bug A, Bug B. 
  • Anytime you believe going back to the current code may be of use.

Tagging could be seen as a tool to document the code but good commit messages are better for that in general.  Tagging serves as a great way to document the timeline of important events of your codebase.

Further Reading

Tutorials and guides:

http://hgbook.red-bean.com/read/a-tour-of-mercurial-the-basics.html (the whole book is good)http://mercurial.selenic.com/quickstart/
http://tekpub.com/view/dotnet-oss/7 (Free video on Mercurial with CodePlex)

Command cheat sheets:


Bitbucket Basics


Release management techniques with Mercurial:


And one last link....

25 tips for intermediate mercurial users has some nice information to add to your arsenal when your ready.

Wrap Up

I hope you found this series helpful.  I enjoyed putting it together and learned a few things along the way.  Mercurial is lesser known than Git but still a great tool.  Hopefully, you’ll find that using Mercurial is very easy.  Give it a shot. 

Happy Coding! Smile

Posted 06.08.2012  #    Comments [0]  | 

This is the seventh post in this series.  In the third post we discussed the various branching scenarios and some ideas as to when to branch.  We settled on branch as needed approach as our default work process but now we are going to show how to branch when you decide you need to.

When should I branch?

With Mercurial and Git this isn’t nearly as painful as non-dvcs systems and can be /encouraged to be used more often now.

Here’s my choices of when to branch.

1. When a feature / bug fix is big enough (subjective). 

This makes it easier to clean up if you decide the code is getting too unwieldy or you can't seem to get it working.

2. When you may need to work on a feature that could take some time to develop. 

This makes sure that if something needs to be done in default without your changes than they could be done.  Think, hotfix or a quick update.

3. When you know there may be other work going on with code that you will be working on as well.

This allows them to work on the code without you or them worrying about your work.  Worry is not exactly the best choice.  You will have to worry about it when you need to merge.

4. When you need to ensure the work you are doing does not effect the default line in anyway until you are absolutely ready.

5. If you are really unsure of your work ahead or you want to try/spike some code that you may not keep.

You can get rid of a branch but you might also want to consider doing the Branch with a Clone method.

What is shown below is the named branch scenario.  This article on task based development does a nice job of describing the commands for named branching.

Named branch scenario

First, as usual we'll check the state of our repo with hg stat and clean up anything we need to.

Create the branch by typing hg branch "BranchName".


After creating the branch, run hg branches to list out the branches that are currently open.  Interesting,
our branch doesn't show up? That's because it hasn't been committed yet. Commit it.

Now run hg branches again and it will show:


To see what branch you are currently in run hg branch:

Now that you are in the correct branch you can develop as usual.  Committing as you go until you are satisfied you are ready to close the branch and merge it back in to the main branch/line (default).

The repo remembers what branch you are in between sessions but it's always a good idea to check what branch you are in by running hg branch before working just like it is running hg stat to ensure everything is the way you expected it.

Closing the loop

After you have completed all your work on this branch, you’ll need to close out the branch.

Always check your status and what branch your in:


Now close out the branch by committing it with the --close-branch option. Type hg commit --close-branch '-m "Your message".

If you were to run hg branches (lists all active branches) now, you’ll see your branch is gone.  If you type hg branch again though you might be a bit confused.  It still shows your in the branch you just closed?

You need to move back into the default / main branch with the hg update command.

Now running hg branch will show you in the right branch.

Your almost done.  You’ve closed the branch and move back into default but if you were to look at default you won’t find your code from your closed branch.  That’s because you haven’t brought in your work from it.  We’ll do this now with the hg merge "Branch name to merge" command.


The merge command will give you statistics for the merge.  As with other steps you need to commit the merge to finalize it.  The merge even warns you to not forget to commit.

If you look at the repository in the Hg Workbench (Tortoise) you'll see graphically the branch & merge.


You can use the hg glog extension to visualize this at the command line as well.

The basic workflow of working on a named branch:
  1. hg stat
  2. hg branch "BranchName"
    1. hg branches - now will not show your new branch as it hasn't been commited yet.
  3. hg commit -m "Initial commit for branch"
    1. hg branches - now shows your branch.
  4. hg branch - confirm you are in your new branch.
  5. Work as normal.  Committing as you need/desire.
  6. hg commit --close-branch -m "Finished Branch"
    1. hg branches - won't show your branch in the list
    2. hg branch - still show you are in the branch
  7. hg update default - go back
  8. hg merge "Branch Name To Merge"
  9. hg commit -m "Commit Message"

It can get more complicated than this but for a small team or one person operation this will be the majority.

Switching branches

In case you need to switch around and work in other branches, run hg update "branch name" to move between branches.

Updating branch with new code from default

The second most common scenario even for a small team is needing to update a branch with code from another branch. 

Let's say you have been working on a new feature for quite some time on a branch.  In the middle of this a nasty bug is found in the currently live system.

You can't fix it in the branch you are on as it's not ready.  What do you do? Switch to the main line/default branch and fix the bug.  Deploy the update and everyone's happy.

In this case, you could just keep developing and merge as usual when you are ready BUT let's say for this situation you want to bring in the fix from main to your branch to make sure everything will continue to work fine and if not, fix it now instead of later.

In your branch run:

  1. hg incoming - tells you if you will get anything from the main repository.*
  2. If you have anything incoming then run hg pull. *
  3. hg merge
  4. hg commit -m "Merge in from default"

* - In a one man team operation this is likely not needed since your local repo is highly likely up to date.  However, for safety and for a small team your teammates will have to pull.  Pulling won't hurt you if there isn't anything to get so it's a good habit to at least check.

The setting up for a team tutorial and task based development have good examples of working with others to get their changes.

Next we'll wrap up with tagging and further reading.

Posted 06.08.2012  #    Comments [0]  | 

This is the sixth post in this series.  Need to delete undo a commit?  Want to throw away your work and start over. It happens to all of us.  With Mercurial this is a breeze.

Undo changes before a commit

So your working on a file and realize for whatever reason you need to scrap your work. 

Typing hg stat, shows you haven’t committed your work yet.


Great, to undo our work let’s move into the directory where the file is just to make our task a little easier.

Next, we'll type hg revert <filename.extension>.  In my particular case, hg revert Index.cshtml.

You don’t get any message but now if you take a look at what you have in your directory you’ll see two files.  Not perhaps what one would expect.  Mercurial doesn’t delete or overwrite the file with what is in the repository.  Instead it adds the .orig extension to the file you don’t want.


This is just for extra safety.  However, you can override this by adding --no-backup to the command (hg revert --no-backup Index.cshtml).

If you do this in Tortoise Hg, it automatically runs with the --no-backup option. You can change that by unchecking the checkbox "do not save backup files" in the lower left hand corner.

To finish up you can delete the Index.cshtml.org and run hg stat to see that your back in order.


If you edited this in Visual Studio, you’ll get prompted by VS to reload the project.


Selecting yes, you’ll see your changes gone and back to what it is in the repository.

To review, the steps to revert a file that hasn’t been committed yet are:

1. hg stat (to view your current state)
2. hg revert <filename.extension>
3. Delete the .orig file (if you don’t use --no-backup)
4. hg stat (to make sure everything is taken care of)

Undoing a commit

Already committed your work?  Let’s undo this mishap now.  Now being the keyword.  With hg rollback you can roll back the last commit in the repository.

Going back to our above sample, let’s make a change to a file and commit it.


I ran hg stat, after my commit just to make sure we are clear of any other changes.  I also ran a new command called hg tip to show that my last commit is indeed the one I’m targeting to revert.

If we are confident this is the commit we want to revert we are ready to rollback.

Type hg rollback


It gives a message back that the tip has been rolled back and the working directory is back to our revision number for the last commit.  However, we are not done.  If you type hg stat you’ll notice our file is in a modified state.


The file is in the state we left it with our changes before we committed it.  We’ll need to revert our work.


This time I used the --no-backup option on the revert to avoid having to delete the .orig file.

As always run hg stat to ensure everything looks right.

To review the steps to undo the last commit:

1. hg stat
2. hg tip
3. hg rollback
4. hg stat
5. hg revert --no-backup <filename.extension>
6. hg stat

Undo an older Commit?

So what if you have to undo a commit that is more than one revision back.  Well, that’s a more advanced topic than what I’m covering.  Take a look at Chapter 9. Finding and fixing mistakes in Mercurial: The Definitive Guide.

In the next post we’re going to go over branching

Posted 06.08.2012  #    Comments [0]  |