Commit Comments: A Conversation with your Future Self

I frequently find myself searching subversion commit logs trying to find hints as to why certain "features/bugs" where introduced and why. Usually this results in wasting several hours and almost every time I get frustrated with a lack of dialogue in commit comments. I can't stress enough the importance of this often over looked feature when committing changes. A lot of developers look at it like a 30 second burden that's preventing them from taking lunch earlier. What they really should be doing is pretending it's a conversation with their future self. Six months from now you're most likely going to be seeing those comments, or lack of, wondering why you made that change. It's in that moment I'd rather have a very descriptive summary of what changed and why verses diff'in every version known to man.

I'm not asking for a Kevin Costner script, just be a little more specific. On average, my comments are 1-3 sentences. For the important changes, I've used paragraphs before. Comments with fewer than 5 words drive me nuts, and I have seen a lot of them.

Ever seen a movie where campers make a trail using something like marshmallows so they can find their way back? Think of your commit comments like marshmallows helping you unravel the mystery of an issue and start developing the habit of providing more descriptive commit comments.

Other Useful Tools
One of the tools I have grown fond of is the Jira subversion plugin. Our team uses Jira as our issue tracking system. Nothing gets committed without a Jira number. This is enforced using a subversion pre-commit hook, so every developer has to start their comment with a Jira number. Then in Jira, there is a Subversion Commits link at the bottom to where anyone can view the files changes and their comments.

Using the subversion pre-commit hook has another added bonus, which is using the Hudson Jira Plugin. After a successful build, hudson will extract the Jira number(s) from the commit comments and add a comment to the Jira stating it was integrated at a specific build # and includes a link.

Find when a branch was created in svn

If you merge between branches and HEAD in subversion, you most likely need to know at what revision the branch was created at. Assuming you don't have the luxury of the new merging features in subversion 1.5, here is a trick I learned from the svn docs.

svn log --stop-on-copy http://server/svn/myapp/branches/myapp-1.0

This will stop once it hits the revision the branch was created at, verses continuing on until r1. Previously I would log the entire branch, and do a grep for the comments I inserted when I created the branch. Not ideal but it worked. Now I use the --stop-on-copy option and I know real quick the revision the branch was created at. Giving me the revision I need to use in the merge.

svn merge -r 546:767 http://server/svn/myapp/trunk

Can't wait until we upgrade to subversion 1.5 or a DVCS.

Favorite svn commands

Recently I switched from Windows to Linux, or more specifically Ubuntu 7.0.4. With a couple of minor issues, everything is working great so far. One of the main reasons for changing was to be faster and better at what I do, and I think linux can help me achieve some that.
One common thing I feel makes linux developers faster is knowing commands and not requiring GUIs. GUIs take a long time to load and refresh compared to just opening a file in vi or vim. On windows I loved SmartSVN and would recommend it to anyone; in fact I have had to install it on linux until I have been converted. At the same time I have enjoyed learning the svn commands, which by the way are 100 times easier than cvs commands. Most cvs commands require options to be effective (cvs update -Pd). Not so with svn.

Here is a list of favorite svn commands I have come to love. Also included are recommendations from friends.

1. svn help . For example svn help update
   
2. svn status. List modified or uncommitted files
3. svn update. Get the latest code and update your modified files
4. svn commit filename -m "Commit Message". Commit the file. filename is optional
5. svn diff. Do a diff on locally modified files.
6. svn diff -r M:N. Performs a diff on the revisions M and N
7. svn merge -r M:N. Revert back to a previous version
8. svn log -v. Gives you a verbose log of everything that has happened
9. svn st | grep "?" | awk '{print $2}' | xargs svn add. Handy command for those who go days without committing and need an easy way to commit uncommitted files.
10. svn propedit svn:ignore. Tells subversion to ignore certain files or directories.
11. svn revert filename. Takes the filename out of source control. Handy when commnd #9 adds files you didn't intend to add.
    

Also there are shortcuts to most of these subcommands. For example svn status is also svn stat or svn st. Just run svn help to get a list of shortcuts.

Finally, don't be disappointed if you are a windows developer. You can use svn in cygwin the same way.