mercurial tasks extension March 9, 2009

Mercurial bookmarks offer a way to work on separate short-lived tasks in the same repo without having to create a separate clone.

For me bookmarks lack two features: tracking all changesets belonging to a particular task, and being able to push completed tasks easily while ensuring that incomplete tasks are not pushed.

I decided to try to extend the bookmarks extension into something different.  I call it ‘tasks’ and use it as my todo list.  It’s amateur python/hg and I would love some help/feedback on it.  You can see it here:

Below is a similar workflow to my other post about bookmarks, except it allows me to safely push changes from one completed task while keeping my incomplete task local.

You might start off your day by looking at issues in your project tracker and creating a todo list of what issues you want to tackle. Instead of writing them on a post-it, let’s use tasks:

$ hg task issue11
$ hg task issue12
$ hg tasks
    issue11      >2:b8df77fa20d7
    issue12      >2:b8df77fa20d7

You’ll notice none of them appear “active” even though they point to the current changeset which matches our working copy. hgtasks-01

Let’s start hacking on issue11:

$ hg up issue11
0 files updated, 0 files merged, 0 files removed, 0 files unresolved
current task: issue11
$ hg tasks
  * issue11      >2:b8df77fa20d7
    issue12      >2:b8df77fa20d7

Now that issue11 is marked as current, future commits will be applied to this task:

*hack* *hack*
$ hg ci -m"fixing issue11"
*hack* *hack*
$ hg ci -m"still fixing 11"
$ hg tasks
  * issue11       4:6c8236430e56 (2 csets)
    issue12      >2:b8df77fa20d7
$ hg task issue11 --info
task:            issue11
parent:          2:2ed12f44801b
state:           active
changesets (2):  4:31f77916d497

We see that we have two changesets assigned to this task.hgtasks-02 Our work on issue11 is still not finished, but issue12 has just been bumped up to high priority and we want to work on it right away leaving issue11 half done.

$ hg up -C issue12
1 files updated, 0 files merged, 0 files removed, 0 files unresolved
current task: issue12
*hack* *hack*
$ hg ci -m"fixing issue12"
created new head
*hack* *hack*
$ hg ci -m"done fixing 12"
$ hg tasks
    issue11       4:6c8236430e56 (2 csets)
  * issue12       6:8672b6e96787 (2 csets)

Let’s mark issue12 as complete:

$ hg task issue12 -c
$ hg tasks
    issue11       4:6c8236430e56 (2 csets)
$ hg tasks --all
    issue11       4:6c8236430e56 (2 csets)
    issue12       6:8672b6e96787 (2 csets - complete)

By default, the task list will only include incomplete tasks unless we use the –all option.

We want to push this fix right away as it is high priority:

$ hg push
pushing to /some/other/repo
abort: pushing incomplete tasks
(use --all-tasks to force or --completed-tasks to prune)
$ hg push --completed-tasks
pushing to /some/other/repo
searching for completed tasks
searching for changes
adding changesets
adding manifests
adding file changes
added 2 changesets with 2 changes to 1 files

Notice that push will warn you that incomplete tasks would be pushed (this is even before the standard warning of creating additional heads on the remote repo).  So we can choose to use –all-tasks option to push everything (at which point we would be told to use –force if we really want to create new heads) or we can do what makes more sense, only push completed tasks with the –completed-tasks option. Now we can go back to working on issue11:

$ hg up -C issue11
0 files updated, 0 files merged, 0 files removed, 0 files unresolved
current task: issue11
*hack* *hack*
$ hg ci -m"done fixing 11"
$ hg task -c issue11

Merge in changes from issue12:

$ hg merge issue12
merging file
0 files updated, 1 files merged, 0 files removed, 0 files unresolved
(branch merge, don't forget to commit)
$ hg ci -m"merge"

We can leave completed tasks around but if you have no reason to keep them around, might as well delete them:

$ hg task -d issue11
$ hg task -d issue12


To see more features of this extension and details on how it was implemented, check out:

Willie April 8th, 2009

This is a amazing extension!! 😀

Bradford April 10th, 2009

I posted this question in the mailing list, but I wasn’t sure if you subscribed or not.

This Tasks extension looks awesome. In a previous thread I read that
Bill Barry has a centralized repository for his attic changes. Would
it be possible to have a centralized repository for the tasks and task
stashes? This would allow people to see the current tasks I’m working
on and provide me with a way to easily backup my tasks in the event
that my computer blows up or is stolen. If so, this would make for
one heck of a workflow.

Or is this not going to be possible until you can push bookmarks over the wire?


alu April 10th, 2009

Hi Bradford,
Yes, the plan is to eventually have task information pushable/pullable. I know that there are some plans to have bookmarks sent over the wire and I was counting on using the same mechanism.

I have some ideas about having tasks information live in their own separate repo inside .hg/tasks. There might be some complicated merging that needs to be done when two people work on the same task. I never thought about sharing stashes though.

The centralized repo for tasks and task stashes that you suggest, would that simply be for allowing others to view incompleted task work (and backup)? And not necessarily allow two people to work on the same task?

I will look at how the attic extension uses a centralized repo for attic changes.


Merwok April 10th, 2009

One gets quickly lost amidst named branches, bookmarks, pbranches, topic branches and tasks. However, the workflow you describe seems handy and intuitive. Are there any plans to get one official way to have this functionality in core Mercurial?

Cheers, Merwok

alu April 10th, 2009

Hi Merwok,
By “core Mercurial” you mean without use of an extension? I don’t think will happen anytime soon.
I think there is an effort to merge the functionality of shelve, attic, mq and pbranch, into one extension (
I think bookmarks/tasks are a bit different, even though tasks shares minimal overlap with attic with the “auto.stash” feature.

Excelsior » Mercurial tasks April 20th, 2009

[…] mercurial tasks extension […]

João Marcus April 30th, 2009

I use hg mainly to have a personal VCS on top of a main CVS repo. I use the one branch per feature/bugfix approach, and this is exactly what I was looking for.
Bookmarks were close, but this extension was a perfect match for my needs. Thanks a lot!

Aaron May 1st, 2009

Thanks for the writeup! I had read your previous post about bookmarks and found it handy. I like bookmarks, but what I wanted was more like git branches, which is what the tasks seem to do. This matches my personal workflow almost exactly. Thanks again!

Sander Smits May 11th, 2009

This is exactly what kept me from switching from Git to Mercurial! Git’s cheap local branches are the killer feature for me and your tasks extension seems to provide the same functionality. Great! I sure hope this ends up in the core.

Dilip October 23rd, 2009

Great! This will prevent me pushing all incomplete tasks!

Dilip November 3rd, 2009

A great extension. But won;t work on windows

D:\repos\hgoff>hg task
*** failed to import extension tasks from “D:\repos\hgoff\.hg\”: [Errno 22] Invali
d argument
hg: unknown command ‘task’
Mercurial Distributed SCM

Dilip November 27th, 2009

Just explored mq! the same stuff can be done using it.if we think each task as a patch! 🙂

Ryan April 6th, 2010

So the main difference from the bookmarks extension is that this protects you from pushing incomplete tasks?

Ryan April 9th, 2010

Let me expand my question: this looks very similar to Mercurial’s bookmarks extension. Can you highlight the differences?

alu April 11th, 2010

Hi Ryan,
For me, this highlights the differences:

“For me bookmarks lack two features: tracking all changesets belonging to a particular task, and being able to push completed tasks easily while ensuring that incomplete tasks are not pushed.”

Dilip, yes mq can do a lot of the same things (and a lot more!), but I wanted something that worked by adding some metadata on a regular hg repo instead of a stack of patches.


Bob W July 1st, 2010

So…tasks, then, are basically like bookmarks that record every changeset that has been a part of them (instead of only the tip), and that provide you with an extra filter in front of the multiple-head-catch, which (depending on your workflow) may be more convenient than always pushing with -r?

I’m going to have to look into this; it sounds really interesting. Two things that have me curious are what happens if you DO push with -r, and what happens if you try to rebase a task.

Mark August 16th, 2010

Couldn’t you make tasks just be a frontend for bookmarks — where you have two bookmarks per task (e.g. a “taskname:begin” bookmark, and a “taskname” bookmark)? Then it would be possible to use the already available bookmark-pushing capabilities of mercurial.

Bob W August 27th, 2010

That would produce some really odd behavior if you accidentally activated the taskname:begin bookmark and started committing (after you’d already made some commits to advance the taskname bookmark), wouldn’t it?

…On the other hand…what if you had a tag for the beginning, and a bookmark for the progress…hmm. I think you’d still have more potential for accidentally losing that “what commits have to do with this task” bit. I’d have to look in greater detail to figure out if I’m right.

Since I’m mostly using hg as an svn superclient to trunk-at-root repositories at the moment, trying out use cases for me is a little contrived.

Josh October 14th, 2010

Hey Alu! Your ‘hg tasks’ is broken on hg 1.5.x and hg 1.6.x. People have submitted bug reports and others and submitted patch files. You should evaluate the patches and push up fixes so those of us on newer mercurials can use your extension. Feel free to reject patches and give reasons if you feel something wasn’t fixed properly.

There’s been no activity from you on bitbucket in a year, but you’re here discussing your extension. At least comment on bugs so we know you haven’t abandoned the project.

alu October 19th, 2010

Hi Josh,
Yes I haven’t kept up hgtasks lately, I’m sorry about that.

I will try to do a better job of maintaining it. I have some ideas I would like to implement and I will try to keep active on the bitbucket page as well.


Leave a Reply