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/
                └── Asset/
                    └── Asset.object-meta.xml
                ...
                ...
                ...
                └── profiles/
                    ├── MyProfile.profile-meta.xml
                    └── MyOtherProfile.profile-meta.xml

(Note that this guide replaces the force-app folder name with unpackaged; this is supported as long as the path variable in the sfdx-project.json matches the folder name.)

You can also use our sample SFDX repository to copy or fork from to help you see what an SFDX structure should look like.

By default Gearset will write your metadata in the SFDX format if your repository is empty.

If your repository already has metadata, Gearset will write in the SFDX format only if it detects a correctly placed sfdx-project.json file. If the repository already has metadata but no sfdx-project.json file, then Gearset will write in the MDAPI format.

Support for metadata with multiple SFDX paths

Gearset supports multiple paths in the packageDirectories in the sfdx-project.json. We use all the paths to search for metadata to compare.

If default is set to true it will be searched first for metadata, if multiple packages have default set to true they will be prioritised over none default packages for searching. The path can have multiple package levels of any name, we usually use the default force-app but any valid path is usable.

The final package level can not be inside another packageDirectory path. I.e.:
- foo/bar
- foo/baz
are valid, but
- foo/bar
- foo/bar/baz
are not valid, as the paths conflict.

Inside these packageDirectories is where we look for metadata to compare. We look for metadata at any folder depth inside the packageDirectories path. If force-app was our packageDirectories path, these are examples of metadata Gearset will pick up:


- force-app/main/default/applications/Dreamhouse.app-meta.xml

- force-app/classes/MyClass.class-meta.xml

- force-app/one/foo/bar/baz/Account.object-meta.xml

After the packageDirectories path, any folders levels can be named whatever you like, and you can split your metadata up into folders however you like, such as:
- main/default
- main/test
- my-feature-1/default
- foo/bar/my-feature-2/my-component-1
- my-component-2

Gearset first looks for a folder of a known metadata type (aura, lwc, applications, classes, pages etc.), and then loads metadata from inside here. It will still try to process the metadata if this is not named something we expect but it is not ideal.

Inside the final "metadata folder" should be the metadata file, however for simple types which occur as a flat list of files inside this folder, it can be in subsequent folders named anything you like i.e.:
foo/bar/applications/Dreamhouse.app-meta.xml
foo/bar/applications/baz/Dreamhouse.app-meta.xml
are both valid.

Did this answer your question?