This section is from the "Version Control with Subversion" book, by Ben Collins-Sussman, Brian W. Fitzpatrick and C. Michael Pilato. Also available from Amazon: Version Control with Subversion.
You can create, modify, and delete changelists using the svn changelist command. More accurately, you use this command to set or unset the changelist association of a particular working copy file. A changelist is effectively created the first time you label a file with that changelist; it is deleted when you remove that label from the last file that had it. Let's examine a usage scenario that demonstrates these concepts.
Harry is fixing some bugs in the calculator application's mathematics logic. His work leads him to change a couple of files:
$ svn status M integer.c M mathops.c $
While testing his bug fix, Harry notices that his changes
bring to light a tangentially related bug in the user
interface logic found in button.c
. Harry
decides that he'll go ahead and fix that bug, too, as a
separate commit from his math fixes. Now, in a small working
copy with only a handful of files and few logical changes,
Harry can probably keep his two logical change groupings
mentally organized without any problem. But today he's going
to use Subversion's changelists feature as a special favor to
the authors of this book.
Harry first creates a changelist and associates with it the two files he's already changed. He does this by using the svn changelist command to assign the same arbitrary changelist name to those files:
$ svn changelist math-fixes integer.c mathops.c Path 'integer.c' is now a member of changelist 'math-fixes'. Path 'mathops.c' is now a member of changelist 'math-fixes'. $ svn status --- Changelist 'math-fixes': M integer.c M mathops.c $
As you can see, the output of svn status reflects this new grouping.
Harry now sets off to fix the secondary UI problem. Since he knows which file he'll be changing, he assigns that path to a changelist, too. Unfortunately, Harry careless assigns this third file to the same changelist as the previous two files:
$ svn changelist math-fix button.c Path 'button.c' is now a member of changelist 'math-fixes'. $ svn status --- Changelist 'math-fixes': button.c M integer.c M mathops.c $
Fortunately, Harry catches his mistake. At this point, he
has two options. He can remove the changelist association
from button.c
, and then assign a
different changelist name:
$ svn changelist --remove button.c Path 'button.c' is no longer a member of a changelist. $ svn changelist ui-fix button.c Path 'button.c' is now a member of changelist 'ui-fix'. $
Or, he can skip the removal and just assign a new
changelist name. In this case, Subversion will first warn
Harry that button.c
is being removed from
the first changelist:
$ svn changelist ui-fix button.c svn: warning: Removing 'button.c' from changelist 'math-fixes'. Path 'button.c' is now a member of changelist 'ui-fix'. $ svn status --- Changelist 'ui-fix': button.c --- Changelist 'math-fixes': M integer.c M mathops.c $
Harry now has two distinct changelists present in his
working copy, and svn status will group its
output according to these changelist determinations. Notice
that even though Harry hasn't yet modified
button.c
, it still shows up in the output
of svn status as interesting because it has
a changelist assignment. Changelists can be added to and
removed from files at any time, regardless of whether they
contain local modifications.
Harry now fixes the user interface problem in
button.c
.
$ svn status --- Changelist 'ui-fix': M button.c --- Changelist 'math-fixes': M integer.c M mathops.c $