There are two types of repository structures supported by Gearset: SFDX source format and MDAPI (Metadata API) format. You can choose which format to deploy in based on the features of your repository.

Deploying in SFDX source format

If you deploy your metadata to an empty repository, Gearset's default behavior is to write it in the SFDX source format. You do not need to include a sfdx-project.json file for Gearset to recognize 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 source 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 recognizes this repository as containing metadata, but does not recognize it as SFDX source format 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 source and MDAPI formatting.

Deploying in MDAPI (Metadata API) format

Gearset will deploy your metadata in a 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.json file

In the screenshot below, there is an SFDX source 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 a 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 source 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 source format, delete the sfdx-project.json file. Then delete all the SFDX source formatted metadata, and re-deploy any missing metadata using Gearset. It will be deployed in the MDAPI format.
If you do want the SFDX source format, make sure that the sfdx-project.json file 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 source format.

Please note: a file will need to have metadata included inside it for Gearset to recognize it as SFDX source 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 source format.