# Combine Command

## Overview

The `combine` command merges two or more Gateway configuration bundles into a single unified bundle. This is useful for consolidating configurations from multiple sources or environments.

## Syntax

```bash
graphman combine --inputs <input-file> <input-file> ... [--output <output-file>]
```

## Parameters

### Required Parameters

| Parameter | Description |
|-----------|-------------|
| `--inputs` | Two or more input bundle files to combine. At least two bundles are required. |

### Optional Parameters

| Parameter | Description | Default |
|-----------|-------------|---------|
| `--output` | Specify the output file to save the combined bundle | Standard output (console) |

## Behavior

### Merge Strategy

When combining bundles, the command follows these rules:

1. **Rightmost Precedence**: When similar entities are encountered across multiple bundles, entities from the rightmost bundle take precedence
2. **Entity Matching**: Entities are matched based on their identifying attributes (e.g., name, GUID)
3. **Non-duplicate Preservation**: Unique entities from all bundles are preserved in the result
4. **Automatic Sorting**: The output bundle is automatically sorted for consistency

### Processing Order

The combine operation processes bundles from left to right:
1. All entities from the rightmost bundle are added first
2. Entities from other bundles are added only if they don't already exist
3. The final result contains all unique entities with rightmost precedence for duplicates

## Examples

### Basic Combination

Combine two bundles into one:

```bash
graphman combine --inputs bundle1.json bundle2.json --output combined.json
```

### Multiple Bundle Combination

Combine three or more bundles:

```bash
graphman combine --inputs base.json dev.json prod.json --output final.json
```

In this example:
- Entities unique to `base.json` are included
- Entities unique to `dev.json` are included
- Entities from `prod.json` override any matching entities from `base.json` or `dev.json`

### Output to Console

Combine bundles and output to standard output:

```bash
graphman combine --inputs bundle1.json bundle2.json
```

## Use Cases

### 1. Environment Configuration Merging

Combine a base configuration with environment-specific overrides:

```bash
graphman combine --inputs base-config.json production-overrides.json --output prod-config.json
```

### 2. Incremental Configuration Building

Build up a configuration from multiple smaller bundles:

```bash
graphman combine \
  --inputs core-services.json \
           security-policies.json \
           custom-assertions.json \
  --output complete-config.json
```

### 3. Configuration Consolidation

Merge configurations from multiple gateways into a unified bundle:

```bash
graphman combine --inputs gateway1.json gateway2.json gateway3.json --output consolidated.json
```

## Important Notes

- **Minimum Requirement**: At least two input bundles must be provided
- **Entity Identification**: Entities are matched using their unique identifiers (typically name and/or GUID)
- **Precedence Rule**: Always remember that rightmost bundles take precedence in case of conflicts
- **Automatic Sorting**: The output is automatically sorted, ensuring consistent formatting
- **File Format**: All input files must be valid Gateway configuration bundles in JSON format

## Error Handling

The command will fail if:
- The `--inputs` parameter is missing
- Fewer than two input bundles are provided
- Any input file cannot be read or is not a valid bundle format

## Related Commands

- **[export](Export-Command.md)**: Export configuration from a Gateway
- **[import](Import-Command.md)**: Import a bundle to a Gateway
- **[diff](Diff-Command.md)**: Compare two bundles to see differences

## Technical Details

### Algorithm

The combine operation uses the following algorithm:

1. Initialize an empty result bundle
2. Process the rightmost bundle first, adding all its entities to the result
3. Process remaining bundles from left to right:
   - For each entity in the current bundle
   - Check if a matching entity exists in the result
   - If no match is found, add the entity to the result
4. Sort the final result bundle for consistent output