Changelists As Operation Filters
The visual grouping that Harry sees in the output of svn status as shown in our previous section is
nice, but not entirely useful. The status command is just one of many operations he might wish to perform on his
working copy. Fortunately, many of Subversion’s other operations
understand how to operate on changelists via the use of the --changelist
option.
When provided with a --changelist option,
Subversion commands will limit the scope of their operation to only
those files to which a particular changelist name is assigned. If Harry
now wants to see the actual changes he’s made to the files in his
math-fixes changelist, he
could explicitly list only the files that make up
that changelist on the svn diff command
line:
$ svn diff integer.c mathops.c Index: integer.c =================================================================== --- integer.c (revision 1157) +++ integer.c (working copy) ... Index: mathops.c =================================================================== --- mathops.c (revision 1157) +++ mathops.c (working copy) ... $
That works okay for a few files, but what if Harry’s change touched 20 or 30 files? That would be an annoyingly long list of explicitly named files. Now that he’s using changelists, though, Harry can avoid explicitly listing the set of files in his changelist from now on, and instead provide just the changelist name:
$ svn diff --changelist math-fixes Index: integer.c =================================================================== --- integer.c (revision 1157) +++ integer.c (working copy) ... Index: mathops.c =================================================================== --- mathops.c (revision 1157) +++ mathops.c (working copy) ... $
And when it’s time to commit, Harry can again use the
--changelist option to limit the scope of the commit to
files in a certain changelist. He might commit his user interface fix by
doing the following:
$ svn ci -m "Fix a UI bug found while working on math logic."
--changelist ui-fix
Sending button.c
Transmitting file data .
Committed revision 1158.
$
In fact, the svn commit command
provides a second changelists-related option:
--keep-changelists. Normally, changelist assignments are removed from files after they
are committed. But if --keep-changelists is provided,
Subversion will leave the changelist assignment on the committed (and
now unmodified) files. In any case, committing files assigned to one
changelist leaves other changelists undisturbed:
$ svn status --- Changelist 'math-fixes': M integer.c M mathops.c $
Note
The --changelist option acts only as a filter
for Subversion command targets and will not add targets to an
operation. For example, on a commit operation specified as
svn commit /path/to/dir, the target is the
directory /path/to/dir and its
children (to infinite depth). If you then add a changelist specifier
to that command, only those files in and under /path/to/dir that are
assigned that changelist name will be considered as targets of the
commit—the commit will not include files located elsewhere (such is in
/path/to/another-dir), regardless
of their changelist assignment,
even if they are part of the same working copy as the operation’s target(s).
Even the svn changelist command
accepts the --changelist option. This allows you to
quickly and easily rename or remove a changelist:
$ svn changelist math-bugs --changelist math-fixes --depth infinity . svn: warning: Removing 'integer.c' from changelist 'math-fixes'. Path 'integer.c' is now a member of changelist 'math-bugs'. svn: warning: Removing 'mathops.c' from changelist 'math-fixes'. Path 'mathops.c' is now a member of changelist 'math-bugs'. $ svn changelist --remove --changelist math-bugs --depth infinity . Path 'integer.c' is no longer a member of a changelist. Path 'mathops.c' is no longer a member of a changelist. $
Finally, you can specify multiple instances of the
--changelist option on a single command line. Doing so
limits the operation you are performing to files found in any of the
specified changesets.