It is not unusual that I’ve come upon the situation where I’m working over a local Subversion working copy and I wanted to commit bits of what I’ve already baked and ready to go. Odds are that there’s just one file not belonging to such changeset but usually it involves many files scattered around.
This situation, I learned, can be managed with a lot more flexibility and fun.
svn changelist is a nice tool for such situations. svn changelist allows you to create a list of “files I want to do something with” meaning that you can use the changelist on your usual svn operations, read commit, remove, etc.
Using svn changelist
Let’s suppose you start with a project myapp, which is the next killer app. Then you start creating three files A, B and C.
dragon% touch A B C dragon% ls -lh total 0 -rw-r--r-- 1 rudy rudy 0 Jul 13 20:16 A -rw-r--r-- 1 rudy rudy 0 Jul 13 20:16 B -rw-r--r-- 1 rudy rudy 0 Jul 13 20:16 C
You want to use version control for those files, of course, so:
dragon% svn add A B C A A A B A C
dragon% svn ci "first commit of A, B and C" . Adding A Adding B Adding C Transmitting file data ... Committed revision 1.
Now you want to edit A and add few pieces of text. Then you will edit B next.
dragon% echo "This file looks empty, so let's put some text inside it" > A dragon% dragon% echo "I'm afraid this one also is empty. Just in case" >> B
Let’s say you need to work on the file C and that implies touching B too. You don’t want to commit the changes you’ve just made since you haven’t made up your mind about them.
dragon% echo "C is a nice name for a source file, but this one doesn't look like one does it?" > C dragon% echo "I'm going to add few lines to B too" >> B
dragon% svn st M A M B M C
So, let’s suppose you are ready to hit the enter key and commit the 2nd revision but you are not done with A, so you want to commit just B and C the way they are at this point. Here svn changelist enters the arena.
Creating a changelist
svn changelist can be used to create a list for the two files and do several tasks related to them. Let’s see. Let’s start adding both B and C to our new changelist called mylist.
dragon% svn changelist mylist B C Path 'B' is now a member of changelist 'mylist'. Path 'C' is now a member of changelist 'mylist'.
Now you have a changelist named mylist that you can do operations with. For instance:
dragon% svn st M A --- Changelist 'mylist': M B M C
dragon% svn diff --changelist mylist Index: B =================================================================== --- B (revision 1) +++ B (working copy) @@ -0,0 +1,2 @@ +I'm afraid this one also is empty. Just in case +I'm going to add few lines to B too Index: C =================================================================== --- C (revision 1) +++ C (working copy) @@ -0,0 +1 @@ +C is a nice name for a source file, but this one doesn't look like one does it?
Now let’s commit the list.
dragon% svn ci -m "Comitting files from the mylist changelist" --changelist mylist Sending B Sending C Transmitting file data .. Committed revision 2.
dragon% svn st M A
Now that you’ve checked in the files, the changelist mylist vanishes from your working copy. You cannot do further operations with it since it does not exists anymore.
Wrapping up
Changelists are a great tool to group certain files and do operations with them. You can think of them as a sort of alias for a set of file. When using changelists you have to consider a few things. Changelists are created as a one-time list, that means you cannot add another file to an existing list. If you type svn changelist mylist A it will define the changelist mylist to have just one member, A. It will not add A to any existing list and has no connection with the other files, B and C. On the other hand, you are free to remove any file from an existing changelist using svn changelist mylist --remove. For our previous example it could be: svn changelist mylist --remove B. Such command will make the changelist shrink to just have one element, C. You can also have as many changelists as you want, and member files can be associated to each one of them. Use case for that could be a diff over a set of specific files.
Probably for the project we’ve setup to walk you through this feature it basically makes no difference to use this feature, but when you are dealing with many files on your working copy this feature will keep your hair on it’s place, and it may save the day. svn changelist is available since Subversion 1.5.