> For the complete documentation index, see [llms.txt](https://docs.flxbl.io/flxbl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flxbl.io/flxbl/sfp/analysing-a-project/duplicate-check.md).

# Duplicate Check

{% hint style="info" %}
Available in sfp-pro.
{% endhint %}

The duplicate check functionality helps identify duplicate metadata components across your Salesforce project. This analysis is crucial for maintaining clean code organization and preventing conflicts in your deployment process.

### Overview

Duplicate checking scans your project's metadata components and identifies:

* Components that exist in multiple packages
* Components in aliasified packages
* Components in unclaimed directories (not associated with a package)

### How It Works

The duplicate checker:

1. Scans all specified directories for metadata components
2. Creates a unique identifier for each component based on type and name
3. Identifies components that appear in multiple locations
4. Provides detailed reporting with context about each duplicate

### Configuration

Duplicate checking can be configured through CLI flags and an optional exclusion config file.

```bash
sfp project:analyze --fail-on duplicates --fail-on-unclaimed
```

#### Key Configuration Options

| Option                 | Description                                    | Default                |
| ---------------------- | ---------------------------------------------- | ---------------------- |
| `--show-aliasfy-notes` | Show information about aliasified packages     | true                   |
| `--fail-on-unclaimed`  | Fail when duplicates are in unclaimed packages | false                  |
| `--duplicates-config`  | Path to duplicates exclusion config file       | config/duplicates.yaml |

#### Exclusion Config — `config/duplicates.yaml`

You can exclude specific components or file paths from duplicate detection using a YAML config file. Without this file, all components are scanned.

The file is checked in this order:

1. `--duplicates-config <path>` CLI flag
2. `config/duplicates.yaml` relative to the project root

```yaml
# config/duplicates.yaml

excludes:
  # Exclude specific components or entire metadata types from duplicate detection.
  # Formats:
  #   - "TypeName"                     exclude all components of this type
  #   - "TypeName:ComponentName"       exclude a specific component by name
  #   - "TypeName:Parent.Child"        exclude child components (e.g. CustomField in a CustomObject)
  components:
    - ApexClass:MyUtilityClass
    - CustomField:Account.LegacyField__c
    - PermissionSet

  # Exclude file paths matching these glob patterns.
  paths:
    - 'src/**/test/**'
    - 'src/**/deprecated/**'
```

| Field                 | Type       | Description                                                                                     |
| --------------------- | ---------- | ----------------------------------------------------------------------------------------------- |
| `excludes.components` | `string[]` | Component identifiers to skip. Supports type-only, `Type:Name`, or `Type:Parent.Child` formats. |
| `excludes.paths`      | `string[]` | Glob patterns for file paths to exclude from scanning.                                          |

### Understanding Results

The duplicate check provides three types of findings:

1. **Direct Duplicates**: Same component in multiple packages
2. **Aliasified Components**: Components in aliasified packages (typically expected)
3. **Unclaimed Components**: Components in directories (such as unpacakged or src/temp) not associated with packages

#### Sample Output

```markdown
# Duplicate Analysis Report

## Aliasified Package Information
- Note: Package "env-specific" is aliasified - duplicates are allowed.

## Component Analysis

### ❌ CustomObject: Account.Custom_Field__c (Duplicate Component)
- `src/package1/objects/Account.object` 
- `src/package2/objects/Account.object`

### ⚠️ CustomLabel: Common_Label (Aliasified Component)
- `src/env-specific/qa/labels/Custom.labels` (aliasified)
- `src/env-specific/prod/labels/Custom.labels` (aliasified)
```

### Understanding Indicators

The analysis uses several indicators to help you understand the results:

* ❌ Indicates a problematic duplicate that needs attention
* ⚠️ Indicates a duplicate that might be intentional (e.g., in aliasified packages)
* *(aliasified)* Marks components in aliasified packages
* *(unclaimed)* Marks components in unclaimed directories

### Best Practices

1. **Regular Scanning**: Run duplicate checks regularly during development
2. **Clean Package Structure**: Keep each component in its appropriate package
3. **Proper Package Configuration**: Ensure all directories are properly claimed in sfdx-project.json
4. **Documented Exceptions**: Document cases where duplication is intentional

### Common Scenarios and Solutions

#### 1. Legitimate Duplicates

Some components may need to exist in multiple packages. In these cases:

* Use aliasified packages when appropriate
* Document the reason for duplication
* Consider creating a shared package for common components

#### 2. Unclaimed Directories

If you find components in unclaimed directories:

1. Add the directory to sfdx-project.json
2. Assign it to an appropriate package
3. Re-run the analysis to verify the fix

#### 3. Aliasified Package Duplicates

Duplicates in aliasified packages are often intentional:

* Used for environment-specific configurations
* Different versions of components for different contexts
* Not considered errors by default

### Integration with CI/CD

{% hint style="info" %}
Integration is limited only to GitHub at the monent, The command needs GITHUB\_APP\_PRIVATE\_KEY and GITHUB\_APP\_ID to be set in an env variable for the results to be reported as a GitHub check
{% endhint %}

When integrating duplicate checking in your CI/CD pipeline:

1. **Configure Failure Conditions**:

   ```bash
   sfp project:analyze --fail-on duplicates --fail-on-unclaimed --output-format github
   ```
2. **Generate Reports**:

   ```bash
   sfp project:analyze --report-dir ./reports --output-format markdown
   ```
3. **Review Results**:
   * Use generated reports for tracking
   * Address critical duplicates
   * Document accepted duplicates

### Troubleshooting

1. **False Positives**
   * Verify package configurations in sfdx-project.json
   * Check if components should be in aliasified packages
   * Ensure directories are properly claimed
2. **Missing Components**
   * Verify scan scope (package, domain, or path)
   * Check file permissions
   * Validate metadata format


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.flxbl.io/flxbl/sfp/analysing-a-project/duplicate-check.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.