# Revise Command

## Overview

The `revise` command updates a bundle to conform to schema changes, normalize entity structures, and apply transformations. It's essential for migrating bundles between Gateway versions and ensuring bundle compatibility. 

> [!NOTE] 
> Currently, bundle portability is supported from the older gateway releases to the latest. This may not be true when the deprecated features are no longer supported. During this phase, revise command ensures the portability by transforming the bundles as per the target gateway.
>

## Syntax

```bash
graphman revise --input <input-file>
  [--output <output-file>]
  [--options.<name> <value>,...]
```

## Parameters

### Required Parameters

| Parameter | Description |
|-----------|-------------|
| `--input` | Input bundle file to revise |

### Optional Parameters

| Parameter | Description | Default |
|-----------|-------------|---------|
| `--output` | Output file for revised bundle | Standard output (console) |
| `--options.<name>` | Customize revise operation | See defaults below |

### Options

| Option | Default | Description |
|--------|---------|-------------|
| `normalize` | `false` | Normalize/sanitize bundle for import |
| `excludeGoids` | `false` | Remove GOIDs from entities (requires normalize) |

## Behavior

### Schema Revision

The revise command automatically:
- Updates entity structures to match current schema
- Adds new required fields with default values
- Removes deprecated fields
- Transforms field values to new formats
- Adjusts entity relationships

### Normalization

When `normalize: true`:
- Sanitizes bundle for import operations
- Removes duplicate entities
- Validates entity structures
- Applies import-ready transformations
- Optionally removes GOIDs

## Examples

### Basic Revision

Revise bundle to current schema:

```bash
graphman revise --input old-bundle.json --output revised-bundle.json
```

### Revise with Normalization

Normalize bundle for import:

```bash
graphman revise --input bundle.json --output normalized.json --options.normalize true
```

### Revise and Remove GOIDs

Prepare portable bundle without GOIDs:

```bash
graphman revise --input bundle.json --output portable.json \
  --options.normalize true \
  --options.excludeGoids true
```

### Revise to Console

View revised bundle without saving:

```bash
graphman revise --input bundle.json --options.normalize true
```

## Use Cases

### 1. Gateway Version Migration

Migrate bundle from older Gateway version:

```bash
# Export from old gateway (v10.x)
graphman export --gateway old-gw --output old-version.json

# Revise for new gateway (v11.x)
graphman revise --input old-version.json --output migrated.json

# Import to new gateway
graphman import --input migrated.json --gateway new-gw
```

### 2. Schema Compatibility

Update bundle to match current schema:

```bash
graphman revise --input legacy-bundle.json --output current-schema.json
```

### 3. Import Preparation

Prepare exported bundle for import:

```bash
# Export from source
graphman export --gateway source --output export.json

# Revise for import
graphman revise --input export.json --output import-ready.json \
  --options.normalize true \
  --options.excludeGoids true

# Import to target
graphman import --input import-ready.json --gateway target
```


### Custom Schema Version

Revise to specific schema version:

```bash
graphman revise --input bundle.json --output revised.json \
  --options.schema v11.1.1 \
  --options.normalize true
```

### Batch Revision

Revise multiple bundles:

```bash
#!/bin/bash
for file in bundles/*.json; do
  output="revised/$(basename $file)"
  graphman revise --input "$file" --output "$output" \
    --options.normalize true \
    --options.excludeGoids true
done
```