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:
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:
Gearset also supports putting all of the metadata inside a
src directory, which is the structure used by Eclipse:
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.
Gearset does not support a branch with multiple
package.xml files. Gearset may have problems parsing your branch if multiple
package.xml files are present.
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:
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:
├── package.xml <--- This will stop Gearset from
└── unpackaged/ finding the metadata
In this case the
package.xml file should be removed, or moved to the
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:
(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.
Restrictions to which metadata is picked up
Gearset will pick up metadata as long as two rules are met:
The metadata is in a subdirectory listed as a package directory in the
The metadata file/directory is not excluded by a rule in a
Therefore you can use either of these rules to include/exclude metadata from a comparison or deployment by Gearset.
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.:
are valid, but
are not valid, as the paths conflict.
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:
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:
Gearset first looks for a folder of a known metadata type (
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.:
are both valid.
Gearset does not support multiple paths in directories below the
packageDirectories level. For example, this is not supported: