When storing your metadata in source control, there are several options for how to store the metadata and where to put it in your repository. Your metadata needs to be structured correctly so that Gearset can find it.

Metadata API format

This is the standard format for Salesforce metadata, and is what you will be familiar with if you've used ANT, Eclipse or Workbench for deployments before. It's also the structure used by the sfdx force:mdapi:deploy command.

Normally the structure for a Metadata API formatted repository is something like:

<root directory>/
└── unpackaged/
    ├── objects/
        └── SomeObject__c.object
    ├── permissionsets/
    ...
    └── profiles/
        ├── MyProfile.profile
        └── MyOtherProfile.profile

The root directory contains an unpackaged directory, and all the metadata is inside it. Putting the metadata directly inside the root directory is also supported by Gearset:

<root directory>/
├── objects/
    └── SomeObject__c.object
├── permissionsets/
...
└── profiles/
    ├── MyProfile.profile
    └── MyOtherProfile.profile

Gearset also supports putting all of the metadata inside a src directory, which is the structure used by Eclipse:

<root directory>/
└── src/
    ├── objects/
        └── SomeObject__c.object
    ├── permissionsets/
    ...
    └── profiles/
        ├── MyProfile.profile
        └── MyOtherProfile.profile

Using a package.xml file

Optionally, when using the Metadata API format, you can include a package.xml  file in your repository. This can be used in Gearset to filter your comparisons. However, it must be located correctly, since it is also used by Gearset to locate your metadata folder.

If a package.xml  file is present anywhere in the repository, Gearset will use the directory that contains it as the root of your metadata. For example, Gearset will be able to find the metadata in this repository, which uses some-other/metadata-directory as the root for its metadata:

<root directory>/
└── some-other/
    └── metadata-directory/
        ├── package.xml
        ├── objects/
            └── SomeObject__c.object
        ├── permissionsets/
        ...
        └── profiles/
            ├── MyProfile.profile
            └── MyOtherProfile.profile

If you have a package.xml folder placed somewhere other than the root of your metadata, then Gearset will not be able to locate your metadata. For example, in the following example Gearset will treat the root of the repository as the metadata directory and will not find any of the metadata:

<root directory>/
├── package.xml      <--- This will stop Gearset from
└── unpackaged/           finding the metadata
    ├── objects/
        └── SomeObject__c.object
    ├── permissionsets/
    ...
    └── profiles/
        ├── MyProfile.profile
        └── MyOtherProfile.profile

In this case the package.xml  file should be removed, or moved to the unpackaged  folder.

Using the Salesforce DX metadata format

Salesforce DX has a new format for structuring metadata. It's the same structure used by the sfdx force:source:pull  and sfdx force:source:push  commands. Gearset supports this structure natively, and will automatically translate as necessary when deploying to and from repositories in the DX format.

In order for Gearset to detect your repository as being in DX format, it looks for a sfdx-project.json  file. If this file is not present in the root directory, Gearset will treat the repository as a Metadata API formatted repository, and will not find your metadata.

The following is an example of a correctly formatted DX repository:

<root directory>/
├── sfdx-project.json
└── force-app/
    └── main/
        └── default/
            ├── objects/
            ...
            ...
            └── profiles/
                ├── MyProfile.profile
                └── MyOtherProfile.profile
Did this answer your question?