Wei, let me start by describing the difference between Retrieve, Retrieve & Merge, and Refresh.
- Refresh downloads the latest server copy of metadata that you already have locally and overwrites it in-place with no additional prompting or opportunity for merging. Refresh can be very efficient because it doesn't need to enumerate the metadata in the server to determine what to download. It constructs its retrieval manifest based on the files in the local file system.
- Retrieve downloads the latest server copy of metadata potentially including metadata that you don't already have locally. To do that it needs to enumerate the metadata in the org which can be quite expensive in densely-populated orgs. You're given an opportunity to fine-tune what is retrieved in the resulting dialog. If in that dialog you choose the Retrieve button, the metadata is downloaded directly into your project root just as with Refresh except that it may include new metadata. If instead you choose Retrieve & Merge the metadata is downloaded into a separate temporary directory and a diff tool is displayed with the downloaded metadata on the left and your project metadata on the right so that you can carefully merge into your local project.
The short version is that if you just want the latest version of what you already have, use Refresh; if you need additional metadata from the server and/or need to merge server metadata into local metadata, use Retrieve.
I get this question often and definitely need to include it in the FAQ and/or other documentation.
As for not being able to pull down the Loan_Committee__c object, let me explain the process required to grab new metadata:
- Open the subscription editor using Illuminated Cloud>Configure Module. or by starting a Retrieve Metadata operation and then clicking the edit icon to the right of the Contents drop-down.
- Assuming you're using a Selected metadata subscription, click the Refresh button above the tree view.
- Find the new metadata you'd like to include in the tree, in this case CustomObject>Loan_Committee__c, and selected it.
- Click OK to save the changes.
- If you haven't already, start a Retrieve Metadata operation. The dialog will refresh based on the latest metadata and you should see objects>Loan_Committee__c.object in the retrieval tree as Server Only.
- Use either Retrieve or Retrieve & Merge as appropriate to bring the new metadata down into your project.
Please let me know if that doesn't address the issue and answer your questions about how this feature works.
Best regards,
Scott Wells