There are two types of repository structures supported by Gearset: SFDX and MDAPI (Metadata API). You can choose which format to deploy in based on the features of your repository.
Deploying in SFDX format
If you deploy your metadata to an empty repository, Gearset's default behaviour is to write it in the SFDX format. You do not need to include a sfdx-project.json file for Gearset to recognise it in this format.
When your metadata is deployed, Gearset will automatically generate a sfdx-project.json file at the root.
If you already have metadata in your repository, then Gearset will only deploy your metadata in the SFDX format if you have a correctly placed sfdx-project.json file.
In the screenshot below, a sfdx-project.json file is not present at the root of the directory.
Gearset recognises this repository as containing metadata, but does not recognise it as SFDX because of the lack of sfdx-project.json file. Because of this, the metadata will be deployed in the MDAPI format. This will result in a mixture of SFDX and MDAPI formatting.
Deploying in MDAPI (Metadata API) format
Gearset will deploy your metadata in an MDAPI format if:
Your repository has metadata already in the MDAPI format OR
You have metadata in your repository but no correctly placed
sfdx-project.jsonfile
In the screenshot below, there is an SFDX-formatted file (Account.object-meta.xml) but no sfdx-project.json file in the branch.
The metadata is deployed in MDAPI format because the root is missing an sfdx-project.json file.
Common troubleshooting tips
If you are deploying to your repository and you see a lot of new metadata items that you know exist in your repository, then this suggests that you have mixed up the formatting between the MDAPI and SFDX formats.
You will need to decide which format you would like to use, and edit your repository structure accordingly.
First, check whether you have a sfdx-project.json file in your repository:
If you do not want the SFDX format, delete the
sfdx-project.jsonfile. Then delete all the SFDX formatted metadata, and re-deploy any missing metadata using Gearset. It will be deployed in the MDAPI format.If you do want the SFDX format, make sure that the
sfdx-project.jsonfile is at the root of the directory. Delete any MDAPI formatted metadata, and re-deploy any missing metadata using Gearset. It will be deployed in the SFDX format.
Please note: a file will need to have metadata included inside it for Gearset to recognise it as SFDX or MDAPI-formatted. An empty file with a properly formatted name will not be considered as metadata, so Gearset will read the repository as empty and deploy in SFDX format.