Source Format

The commands that Salesforce Extensions for VS Code and Code Builder uses to deploy and retrieve your source assume that your files are in source format (rather than metadata format). Source format is optimized for working with version control systems. For details, see Salesforce DX Project Structure and Source Format in the Salesforce DX Developer Guide.

Because legacy tools such as Force.com IDE used the metadata format, you can’t directly open your such projects in VS Code. You must either convert your metadata to source format (using sfdx force:mdapi:convert) or create a new project and then retrieve the metadata from your org using the manifest (package.xml file) that you used in your previous IDE.

If you have a Salesforce project that is in metadata format and tracked in Git, a bulk convert to the new source format loses all the revision history. Git has built in limits and it fails to detect the enormous number of changes that happen at the same time. The solution is to convert the project to source format in smaller chunks so that you can maintain the revision history. Let’s take the dreamhouse project as an example to follow the conversion steps.

Here’s a snapshot of the code structure in metadata format in the ./metadata folder.

To convert the project from metadata to source format without losing the git history, follow these steps:

1. Create a temporary SFDX project outside of the Git repo. This temporary project has the structure and a configuration file as required by a Salesforce project.

   $ sf project:generate -n tempproj

2. Convert the project in metadata into a temporary project.

   $ sfdx force:mdapi:convert --rootdir ./project/metadata --outputdir ./tempproj

   Now, you have two copies of the project, one in the original location and the other in the new directory temproj, where the project files after converting them to the source format are stored.

3. Move the sfdx-project.json file and the config folder. The sfdx-project.json file identifies the directory as a Salesforce project.

   $ mv ./tempproj/sfdx-project.json ./project/sfdx-project.json

   $ mv ./tempproj/confg ./project/config

4. Commit these changes to the repo.

   $ git add -A

   $ git commit -m "Created sfdx-project.json and config"

5. Create the new folder structure as required by a Salesforce project.

   $ mkdir ./project/force-app

   $ mkdir ./project/force-app/main

   $ mkdir ./project/force-app/main/default

With the folder structure in place, you can now start converting the metadata format to source format.

If the metadata type is composed of one or two files (a source file and a metadata.xml file or only a single xml file), you can:

1. Copy the entire folder (for example, triggers) of the converted source from the temporary project to the appropriate new folder.

   $ mv ./tempproj/force-app/main/default/triggers ./project/force-app/main/default/triggers

2. Delete the old metadata.

   $ rm -rf ./project/metadata/triggers

3. Commit your changes.

   $ git add -A

   $ git commit -m "Converted triggers to source format"

Repeat these steps to convert all the files or folders that contain simple metadata format.

If the changes aren’t detected correctly, the metadata folder may have too many files. In such cases, setting a rename detection limit for merge allows all renames in a single commit. Use the merge.renameLimit variable to set this rename limit. This option doesn’t work for custom objects.

These commands set the rename detection limit and convert to source format in a single commit.

If the new format is of expanded source type where a single metadata item is split into multiple files (for example, Custom Objects), a good approach to convert:

1. Create the folder structure as required by a Salesforce project.

   $ mkdir ./project/force-app/main/default/objects

   $ mkdir ./project/force-app/main/default/objects/MyObject__c

2. Move the metadata format file to the source format location.

   $ mv ./project/metadata/objects/MyObject__c.object / ./project/force-app/main/default/objects/MyObject__c/MyObject__c.object-meta.xml

3. Commit the change.

   $ git add -A

   $ git commit -m "Moved MyObject to source format location"

4. Move the source-formatted files to the source format location and also overwrite the old metadata-formatted version in that location.

   $ mv -f ./tempproj/force-app/main/default/objects/MyObject__c/**/*.* ./project/force-app/main/default/objects/MyObject__c

5. Commit the change.

   $ git add -A

   $ git commit -m "Converted MyObject to source format"

Repeat these steps to convert all the metadata items that are split into multiple files.