From to-do to commit

Hypergrass is a utility for planning your future Mercurial commit messages and for organizing your to-do tasks. This command line tool detects the to-do tasks that you've marked as done, and performs commits using the done tasks as the message.

Personally, I always use a detailed to-do file to guide my development. Often these to-do tasks are small programming tasks that last about 1 or 2 hours to complete. Most programmers that use a DVCS like Mercurial or Git have often felt unsure about what to write in the commit message, reflecting what they have done. They ask themselves "what was it that I just programmed?" then write a couple of imprecise words, and that becomes the commit message. Over time the revision log gets several confusing messages.

With Hypergrass, you avoid maintaining to-do tasks and commit messages as separate things. Normally we have a clear idea what we should program next, and that can be easily written down as a to-do task. You don't need to mentally retrospect to discover what was done. Just mark that task as done and call hypergrass.

It works like this.

1. Make a special file in your repository, the TODO file, 
which should be added to your repository. For detecting your done tasks, Hypergrass requires that the TODO file follows a simple syntax:
+ DONE this is a task that has been completed
- TODO this is a task yet to be done ## this is a comment
- this is a task to be done but not to appear in the commit
>>> 1.1.0 ## 1.1.0 is a version tag
In a nutshell, + or - shows whether the task is completed or not; 'DONE' indicates that the task is shown in the commit message; 'TODO' are tasks that should be eventually marked 'DONE'.

2. Set the Hypergrass TODO file in hgrc
Edit your hgrc to include the following option:
todofile = TODO
The value for todofile is the path to the file relative to the root directory of your repository. So if your repository is located at /home/me/myrepo/ and your TODO file is located at /home/me/myrepo/src/TODO, then todofile in hgrc should be set to src/TODO.

3. Edit the TODO file while you develop your code
Keep your TODO file organized, and as soon as a task is done, just mark it with "+ DONE", and save the TODO file.

4. Call Hypergrass
In the terminal, in your repository's directory, just type
~/myrepo$ hypergrass
and your repository will be committed with the done tasks as the commit message.

You can also use the shorter alias, hyg, to do the same.

Hypergrass has a preview option: hypergrass -p
This will show what the commit message will look like, but will not yet commit.

I have been using Hypergrass in my own projects and it has proved to be a good tool to organize tasks, releases, and sprint backlogs. Has worked fine also in Windows command line.

It is currently in alpha, though, so there are no install instructions yet. But these shall come. Take a look at the Bitbucket repository, if you wish!

No comments:

Post a Comment