COMP 310	Safely Moving and Renaming Packages and Folders in Eclipse

WARNING!

Eclipse and Subclipse do not interact properly when moving or renaming packages and folders.    Simply moving or renaming the folders as one might naturally do in Eclipse via almost any means is VERY likely to result in conflicts between Eclipse and Subversion that prevent the committing of code to the repository.

DO NOT EVER

• Manipulate a folder outside of the Eclipse environment, e.g. from a file explorer.
• Drag-and-drop a package or folder to a new location in Eclipse
• Rename a folder in Eclipse
• Refactor an entire folder

A Safe(r) Procedure

The following procedure appears to be reasonably safe but if you encounter any problems contact the course staff immediately!

Moving a package/folder:

Do not modify any files or do anything else with your system until the entire process is completed! 
Contact the course staff IMMEDIATELY if you encounter any problems and DO NOT PROCEED.

1. Commit your entire codebase.  Make sure that ALL teammates have also fully committed their code!  Be sure that everything has the little yellow cylinders and nothing has black asterisks on it.
   • Do not have any teammates work on the affected package(s) unitl the process is complete.
2. There are two possible techniques (See the special case below if you are just changing the capitalizations of a folder and not changing its spelling or location):
   1. Rename the package (works even when there are sub-packages)
      1. If you are moving the package into another "parent" package, i.e. as a new sub-package, be sure that if the parent package already exists, there are no sub-packages already with the same name. 
         • If the parent package does not exist, do NOT make it.
      2. Right-click the package you want to move, and select "Refactor/Rename..." -- NOT "Move"!
      3. Modify the name of the package to reflect its desired new position in the package hierarchy, e.g.
         •  Prepend any new parent package name(s) if you are moving the package to downwards in the package hierarchy.
         • or remove parent package name(s) if the package is moving upwards in the package hierarchy.  
      4. Be sure to select the "Update references" and "Rename subpackages" options
      5. Click "Ok".
   2. Or, Move all the files in the package (works only if there are no sub-packages)
   1. Create a new empty package where you want the files to end up. 
   2. REFACTOR all the FILES in the old package to move them to the new package by selecting the desired files, right-clicking and selecting "Refactor/Move..." -
      • Do NOT just drap-and-drop the files!  
      • Your original package should be empty when you are done.
   3. Be sure to select the "Update references..." option
   4. Click "Ok".
3. Commit your entire codebase.
4. Open up the SVN Exploring Perspective
   • In the repository, if the original package still exists, delete the empty original package.   Do NOT delete it if it still has contents because this means that the moving process did not complete successfully!   Ask for help!
5. Do a Team/Update to Head to make sure you have the latest version.  This should also cause the old package to disappear if it hasn't already.
6. Clean your project:  The process of moving packages can cause Eclipse to become out of sync with its code files resulting is strange errors where Eclipse complains about not recognizing certain classes in perfectly valid code.
   1. In the main menu of Eclipse go to "Project/Clean..."
   2. In the dialog that pops up, be sure that the desired project is checked.
   3. Click OK to make Eclipse delete all the compiled files in the project's bin directory.  
   4. If the project is set to auto-compile ("Build Automatically", the default), Eclipse will immediately and automatically recompile everything, resyncing with the code files and any spurious errors should disappear.    If the project is not set for auto-compile, manually click "Project/Build All".
7. Commit your entire codebase.
8. Tell ALL team members update their projects:
   • In  the Java Perspective, right-click the entire project and select Team/Update to Head. 

Special Case for Just Changing the Capitalization of a Package/Folder

Technically this is a problem only on Windows machines, where the operating system ignores the case in folder names.   To be safe however, this practice is highly recommended for ALL systems.

When simply changing the capitalization of a package or folder (i.e. not moving it as well), the operating system does not necessarily create a new, separate folder to do so.   Subversion however, assumes that a new folder has been created.   Attempting to commit a simply re-capitalized folder could result in data loss.    Note that this issue does not apply to moving folders to a new location where the name is the same except for capitalization. 

To solve this problem, one has to move the contents of the original package/folder twice, once into a temporary package/folder and then once into the final, properly capitalized package/folder.

Making In-place Capitalization Changes to the Name of a Package/Folder

1. Perform the above procedure to move all the contents of the original package to a temporary package (or any distinctly different name, e.g.  originalPackage_temp). 
2. Now that the original package has been removed, create  the desired final package with the corrected capitalization.
3. Perform the above procedure to move all the contents of the temporary folder to the new final destination folder.

© 2017 by Stephen Wong