Removals
********

This section describes how the Subversion client deals with removals of files and directories.  Many of these behaviors are newly invented, because they follow from the fact that Subversion is versioning directories.  (In other words, the CVS model hasn't had to deal with these scenarios before.)

Removing items
==============

The svn rm subcommand is used to mark items in your working copy for removal from the repository.  Note that marking them is not the same as actually removing them in the repository: the repository is never modified until you run svn commit (or svn import for new data).

Also, note that there two different ways to interpret the phrase "remove an item".  In the less destructive case, the item is removed from revision control (i.e. no longer tracked by Subversion), but it is not removed from your working copy.  In the more destructive case, the item is removed both from revision control and from disk.

Subversion defaults to the less destructive behavior -- svn rm by itself only removes an item from revision control.  However, if the -f flag (--force) is given, the item(s) will also be removed from disk.  However, no item containing local modifications will be removed, nor will items that are not under revision control (you can remove such items by hand).

To remove a file:  svn rm foo.c

     This will schedule foo.c to be deleted from the repository. The file is still tracked in the administrative directory until the user commits;  afterwards, the working copy will no longer track the file.

     If foo.c is locally modified, this command will return an error (you'll have to svn revert your change).

To recursively remove a directory: svn rm dirname

     This will recursively schedule every item below directory dirname to be deleted from the repository.

     If any locally modified items live below the directory, this command will return an error.

To undo a deletion before committing:  svn undel item

     This subcommand will "unmark" a file or directory that is scheduled for removal.  In the directory case, it does not recurse by default (like the way svn rm does.)  To recurse, use the --recursive flag.

When an item has been scheduled for removal, but not yet committed, the client more-or-less treats the item as if it were gone.  Although the item will still show up in the svn status command with a D flag next to it, the client will now allow the user to add a new item of the same name.  In this case, the svn status output will describe the item as replaced (with an R flag).

(todo:  perhaps we should show some examples here...)

This scenario is made even more complicated when the item in question is a directory.  If a directory is recursively marked for deletion, and then a directory of the same name is added with svn add, the user can continue to add (or replace) items in the newly added directory. The svn status command would then show the parent directory as "replaced", and items inside the directory as a mixture of items that are scheduled to be "deleted", "added", and "replaced".

Committing removals
===================

When the user runs svn commit, and items are scheduled for removal, the items are first removed from the repository.  If there are server-side conflicts, then (as usual) an error message will explain that the working copy is out-of-date.

After the items are removed from the repository, all tracking information about the items is removed from the working copy.  In the case of a file, its information is removed from .svn/.  In the case of a directory, the entire .svn/ administrative area is removed, as well as all the administrative areas of its subdirectories.

Note that commit never removes any real working files or directories; that only happens with a svn rm -f command, or possibly during a svn update.

Removals in updates
===================

When an update tries to remove a file or directory, the item is not only removed from local revision control, but the item itself is deleted.  In the case of a directory removal, this is equivalent to a Unix rm -rf command.

There are two exceptions, for safety's sake:

  * items that are not under revision control will be preserved.

  * items that are locally modified result in a conflict (C), with the locally modified version being preserved

Thus it's possible that after an update which recursively removes a directory, there may be stray path "trails" leading down to individual locally-modified files that were deliberately saved.