Tuesday, January 16, 2007

Features of the Subclipse Commit Dialog

This is a post I have been wanting to write since I started my blog. In this post, I am going to cover some features that exist in the Commit dialog within Subclipse. It is very likely that you will not know at least about one of these features.

Might as well start with a screen shot that shows the dialog and some of these features:

Integration with Issue Tracking Systems
I decided this topic was too big for this post, so I first wrote up a post on how to Integrate Subversion with Your Issue Tracking System. Refer to that post for the details.

Message Width Marker
Look closely at the right hand side of the commit message. See the feint line drawn through the edit control? That lets me see where a specified column of text resides so that I can format messages according to whatever guidelines might exist for the project I am working on. The Subversion commit message is just a blob of text that is stored the way you enter it, including (or not) any line feeds. A lot of people might have routines that parse or reuse the messages and often it is desired that the messages fit nicely within someone's terminal window.

This feature first appeared in TortoiseSVN, and we added the same feature in Subclipse. To turn it on, you need to define an SVN property named "tsvn:logwidthmarker" with a numeric value that indicates the column where you want the line to appear, such as "79". Since most Eclipse users will be checking out Eclipse projects, you should only need to set this property on the project root folder. Otherwise, just set it on all folders. This rule applies to all of the subsequent features I will describe that involve SVN properties.

Handling Unversioned/Missing Files
The commit dialog will show any unversioned or missing files that appear beneath the folder you selected when you took the option. By default, unversioned files are not selected in the dialog, but you can change this in the Eclipse preferences under Team -> SVN. Missing files are never selected automatically. If you select these files, when you click OK, Subclipse will execute the svn add/delete command prior to running the svn commit command so that the items are properly included in the commit process.

Remember Previous Messages
There is a combo box in the middle of the dialog that shows previous commit messages you entered, including the text you entered before you hit the Cancel button. This can be useful if you write the commit message and then suddenly realize you left some debug code in that you want to remove before committing.

Message Templates
Subclipse supports two kinds of message templates. The first one comes from TortoiseSVN, and that is to set an SVN property named "tsvn:logtemplate" where the value of the property contains the template text. If this property is set, the dialog will come up with the text of the template already filled in. The second template system is an Eclipse feature first introduced by the CVS plug-in. This features lets you setup any number of templates in the Eclipse preferences. These templates are all then available in the drop-down combo that shows previous messages that were entered.

Require a Message
This feature also comes from TortoiseSVN. You can set an SVN property named "tsvn:logminsize" where the value is a number. When this property is set, the OK button will not be enabled on the commit dialog until the number of characters entered in the message is equal to or greater than the value of this property. So you can set this to a value like "10" and that would require the user to enter at least 10 characters. If for no other reason, entering a value of at least "1" can save a user from accidentally clicking OK without entering a message.

Internal Resizing
All of the sections of the dialog can be resized. So if you like a large area to enter comments, with just a couple of files showing, you can arrange the dialog that way. Likewise the opposite is true if you would prefer to be able to see more files.

Show Differences
This one is my favorite, and one that a lot of user's do not seem to know exists. You can double-click on any file in the list and see the differences in that file. This can really help in writing proper commit messages.

The only negative to this compare feature is that the dialogs are all modal so you cannot look at the compare while you are typing the commit message. I'd like to enhance the commit dialog someday so that the compare results showed in a new section of the dialog, but I am not sure if that would work well from a screen real estate point of view. There is also the question as to whether the Eclipse compare UI can be embedded in a dialog like that. I suspect it can.

The commit dialog in Subclipse contains a number of features that are designed to make the process of working with Subversion easier and more usable for you. Hopefully there were one or two features described in this post that interest you and that you did not already know about. Most of these features were first developed and included in TortoiseSVN, so I would like to just conclude this post with a thank you to the TortoiseSVN developers for paving the way. Thank you.


Anonymous said...

My number one annoyance with the commit dialog is that it is modal. I often want to look up something in the code while typing the commit message. It's nice that my partial message is remembered when I cancel the commit, but I still have to reselect the correct files.

Can't the commit dialog be made a non-modal window?

Daniel Serodio said...

I agree, my main (off the the top of my head, the only) complaint I have about the commit dialog is that it's modal. I have to resort to a Notepad window to compose the commit message while comparing files.

Mark Phippard said...

I do not think it would be impossible to make the dialog modal, although off the top of my head I cannot think of any dialogs in Eclipse that are modal. I assume the Eclipse API has support for them regardless. Generally, if something is going to made modal, making it a View is another option to consider.

Making it modal would definitely require a re-think of a lot of the code involved in the commit process and the dialog/view would definitely have to have a listener attached to it so that if other changes are made in the working copy they are reflected in the dialog.

If you just want to lookup something, the compare feature I mentioned can be used for that. Also, I think if there was some way to attach the compare results to the dialog it would eliminate most of the need for making the dialog non-modal.

Unknown said...

Does the commit template functionality support use of properties/variables to insert
values that are not typed literally into the dialog?

Mark Phippard said...

No, the templates do not currently support the use of any variables.

Petar said...

pleeeeeassee put back the checkboxes.... or make a field in the configuration on the Subclipse "Use check boxes instead of the boring right-click remove from view"

Anonymous said...

If the commit message templates do not support any sort of variables, then how is it a template? The usage of "template" is misleading here...

Also, what good are these templates? Just a short-cut instead of opening up a static text document and copy/pasting the same message as before?

This is a crap implementation of a potentially good feature, I'm sorry to say.

Mark Phippard said...

The template feature is defined by TortoiseSVN and Eclipse (as there are two options). If they enhance what their templates can do we will look into supporting those features.

Unknown said...

If the commit message templates do not support any sort of variables, then how is it a template? The usage of "template" is misleading here...