Blog

Any engineer who has the opportunity to do any substantial amount of development in Apex, the proprietary language of Salesforce.com, knows that installing the Force.com IDE is essential.  The Force IDE, built upon the Eclipse Platform, allows us to use standard development tools such as version control tools and deployment scripts.  It also has the interesting, yet frustrating, quirk of retaining multiple copies of the exact same code on your file system…

It is easy to see what I am talking about.  To recreate it, simply open up your Force.com IDE.  Open the src folder, and you will see at least one subfolder, named “unpackaged.”  If you have created any packages, you will see an additional subfolder for each one, with the same name as the package.  If you don’t have any packages yet, go ahead and create one in Salesforce.  Now open up the unpackaged folder, and you will see the stuff you would normally expect to see in a source directory: classes, pages, object, etc.  Open up a packaged folder now, and you well see copies of the exact same code!  If you log into Salesforce and look at the components listed in the web interface, you can see that there is only one copy of each component.

So what is going on here?  Why are there multiple copies in the Force.com IDE, yet only one in Salesforce itself?  Let’s explore a bit more.

Make a change to a component in the packaged folder and save it.  Look at it on Salesforce.  You can observe that the change is present in the code on the cloud.  Go back to the IDE, and look at the related component in the unpackaged component.  It does not have the change in it.  Or does it?  Right click on the component and choose Refresh from Server.  Voilà!  Now the unpackaged copy reflects the change made in the packaged version.

Aha.

It turns out that the Force.com IDE maintains multiple copies of the same code, and all of the point to the same object in the cloud.  Why?  Well my best guess is to keep the components in different packages logically separated.  Let’s assume that Package 1 has Components A, B, and C.  Package 2 has Components A, B, and D.  The subfolder structure in the Force.com IDE allows you to easily see which components are in which package.  The unpackaged subfolder contains all of the components regardless of package (similar to the component lists in Salesforce itself).  While this can be handy when working with multiple packages, it also opens up the possibility of error.  If you change Component A in Package 1, you must refresh Component A in Package 2 and the unpackaged subfolder before making changes there.  If not, you will not be able to save to the server because your local copy will be dirty.  Since there is not conflict resolution in the Force.com IDE, you are forced to refresh, effectively losing all of the newer changes.  If you happen to be working in offline mode, this can be further exaggerated, because you likely won’t catch the issue until several changes have been made.

The way to prevent this is to ensure that you are refreshing your entire code base (at the top level) every time you switch packages.  This will ensure that you are always working with a clean version of the code.  Alternatively you could develop ONLY in the unpackaged subfolder.  While this would eliminate the convenience of seeing the logical separation between projects, it would also lower the risk of losing changes due to dirty copies.  Either way, as long as you go into development knowing about the multiple copies, you should be OK.  I wish someone had told me about it several months ago… :)