SFDX force:source vs force:mdapi
The main difference is that the file and directory structures are different. force:source refers to the new “source” format, while force:mdapi refers to the old “metadata” format.
As an example of the changes, in metadata format, a custom object is a single file, while in source format, an object has a core metadata file for the object itself, a folder full of files that represent each field, another folder for list views, etc.
Optional commands:
| Command | force:mdapi | force:source |
|---|---|---|
| convert | Converts metadata retrieved via Metadata API into the source format used in Salesforce DX projects | Converts source-formatted files into metadata that you can deploy using Metadata API |
| deploy | Deploys file representations of components into an org by creating or updating the components they represent | Deploys metadata in source format to an org |
| deploy:cancel | Cancels an asynchronous metadata deployment | Cancels an asynchronous source deployment |
| deploy:report | Checks the current status of an asynchronous metadata deployment | Checks the current status of an asynchronous metadata deployment |
| describemetadata | Displays details about metadata types enabled for your org | – |
| listmetadata | Displays properties of metadata components of a specified type | – |
| retrieve | Uses Metadata API to retrieve a .zip of XML files that represent metadata from the targeted org | Retrieves metadata in source format from an org to your local Salesforce DX project |
| retrieve:report | Check the status of an asynchronous metadata retrieval | – |
| delete | – | Deletes source files from your project and from a non-source-tracked org, such as a sandbox |
| open | – | Opens the specified Lightning Page in Lightning App Builder. Lightning Page files have the suffix .flexipage-meta.xml, and are stored in the flexipages directory. If you specify a different type of file, this command opens your org’s home page. |
| pull | – | Pulls changed source from the scratch org to your project to keep them in sync |
| push | – | Pushes changed source from your project to a scratch org to keep them in sync |
| status | – | Lists changes that have been made locally, in a scratch org, or both |
| tracking:clear | – | Clear all local source tracking information |
| tracking:reset | – | Reset local and remote source tracking |
What should I use?
If you have metadata formatted files, use force:mdapi. If you have source formatted files, use force:source. If you have neither, use the source format, as it is easier to work with.
The mdapi commands are to allow migration from existing source code repos to the newer format over time. You should prefer to use the force:source commands whenever possible, and use the force:mdapi commands only when dealing with legacy code repositories that have not yet been converted to “source” format.
Migrating to source format also means you’ll get the advantage of 2GP (Second generation packages), which allows you to create versions, dependencies, etc, so you can just install packages instead of uploading metadata every time. This greatly reduces deployment times and grants additional features, like the ability to delete an obsolete field by removing it from a package.
Exception:
For a Scratch Org it might be better to use force:mdapi because Scratch Orgs “track” changes, allowing developers to upload and download a delta (i.e. just the changes). Other orgs do not have this extra feature, and so you can only download and upload specified files, regardless if there has been any change. This means that it will typically take longer to upload and download changes, and it can be easier to miss changes.
See more:
https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_scratch_orgs.htm
Good to know – force:packege:
Another useful command is the force package command that helps you develop and install packages.
– force:package:create:
Creates a package.
– force:package:install:
Installs a package in the target org.
– force:package:list:
Lists all packages in the Dev Hub org.
References:
https://sfdx-isv.github.io/sfdx-workshop/sfdx-managed-packages/convert-sfdx-source-to-mdapi-source/
https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_scratch_orgs.htm