# !include.raw

The `!include.raw` function forces any file to be included as a raw string,
bypassing automatic parsing based on file extension.

While the regular [`!include`](./include) function parses files based on their extension (JSON, YAML, HCL),
`!include.raw` always returns the file content as a plain string. This is useful when you need
the actual file content as text rather than parsed data structures.

## Usage

```yaml
vars:
  # Always injects content from file or URL as string
  json_string: !include.raw config.json
  yaml_string: !include.raw settings.yaml
  hcl_string: !include.raw terraform.tfvars
```

## Common Use Cases

### Template Files

Include template files that need to be processed later:

```yaml
components:
  terraform:
    my-service:
      vars:
        # Kubernetes manifest template as string
        manifest_template: !include.raw k8s-deployment-template.yaml

        # JSON config template for interpolation
        config_template: !include.raw config-template.json

        # Terraform HCL template
        tf_template: !include.raw module-template.tf
```

### Documentation and Scripts

Include documentation or scripts as strings:

```yaml
metadata:
  # Include markdown documentation
  readme: !include.raw README.md
  release_notes: !include.raw docs/release-notes.md

  # Include shell scripts
  install_script: !include.raw ./scripts/install.sh
  deploy_script: !include.raw ./scripts/deploy.sh
```

### Preserving Formatting

When you need to preserve the exact formatting of a file:

```yaml
vars:
  # Preserve JSON formatting for display or logging
  example_config: !include.raw example-config.json

  # Keep YAML with comments intact
  annotated_yaml: !include.raw annotated-config.yaml

  # Include HCL with original formatting
  terraform_example: !include.raw example.tf
```

### Configuration as Strings

When you need configuration files as strings for further processing:

```yaml
components:
  terraform:
    app:
      vars:
        # Pass JSON config as string to Terraform
        json_config_string: !include.raw app-config.json

        # YAML config for base64 encoding
        yaml_config_string: !include.raw settings.yaml
```

## Remote Files

The `!include.raw` function works with all remote sources supported by `!include`:

```yaml
vars:
  # GitHub raw content
  remote_template: !include.raw https://raw.githubusercontent.com/org/repo/main/template.yaml

  # S3 bucket files
  s3_script: !include.raw s3://my-bucket/scripts/deploy.sh

  # Google Cloud Storage
  gcs_config: !include.raw gcs://my-bucket/configs/app.json

  # With query parameters (extension detection ignores query strings)
  versioned_template: !include.raw https://api.example.com/template.yaml?version=2
```

## Comparison with !include

| Function | File: `config.json` | Content | Result |
|----------|-------------------|---------|---------|
| `!include` | `config.json` | `{"key": "value"}` | Parsed JSON object: `{key: value}` |
| `!include.raw` | `config.json` | `{"key": "value"}` | Raw string: `'{"key": "value"}'` |

### Example

Given a file `config.json`:

```json
{
  "database": {
    "host": "localhost",
    "port": 5432
  }
}
```

Using in a stack manifest:

```yaml
components:
  terraform:
    app:
      vars:
        # Parsed as JSON object
        config_parsed: !include config.json
        # Result: {database: {host: localhost, port: 5432}}

        # Raw string
        config_string: !include.raw config.json
        # Result: '{"database":{"host":"localhost","port":5432}}'
```

## YQ Expressions Not Supported

> **Note**
>
> The `!include.raw` function does not support YQ expressions since it always returns raw strings.
> Use the regular `!include` function when you need to query structured data with YQ.

```yaml
vars:
  # ❌ YQ expressions are not supported with !include.raw
  # This will fail - !include.raw does not process YQ expressions
  invalid: !include.raw config.json .database.host

  # ✅ Use regular !include for YQ expressions
  valid: !include config.json .database.host
```

## File Extension Handling

Unlike `!include` which uses file extensions to determine parsing behavior,
`!include.raw` completely ignores file extensions:

```yaml
vars:
  # All return raw strings regardless of extension
  json_raw: !include.raw data.json          # Raw string
  yaml_raw: !include.raw config.yaml        # Raw string
  hcl_raw: !include.raw terraform.tfvars    # Raw string
  text_raw: !include.raw readme.txt         # Raw string
  no_ext_raw: !include.raw LICENSE          # Raw string
```

## Supported Sources

### Local Files

The `!include.raw` function supports the following local file sources. Atmos resolves local file paths using the following
strategies in order, finding the **first match** that points to an existing file:

1. **Absolute paths** — Used as-is with no resolution needed.
   ```yaml
   vars: !include.raw /Users/me/Documents/policy.rego
   ```

2. **Stack Manifest-relative paths (`./` or `../`)** — Paths that start with `./` or `../` are resolved relative to the
   directory containing the manifest file where the `!include.raw` function is used. Atmos rewrites the path by
   joining it with the manifest's directory before checking if the file exists. For example, if the manifest is at
   `stacks/deploy/dev.yaml`, then `../config/policy.rego` resolves to `stacks/config/policy.rego`.

   ```yaml
   # Resolved relative to the directory of the current manifest file
   vars: !include.raw ../config/policy.rego
   script: !include.raw ./scripts/deploy.sh
   ```

   > **Note**
   >
   > Use `./` or `../` prefixes when you want to explicitly reference files relative to the current manifest's
   > location. This is the most unambiguous way to include files that live near the manifest.

3. **Paths relative to `base_path`** — All other relative paths (those **without** a `./` or `../` prefix) are
   resolved relative to the [`base_path`](/cli/configuration#base-path) defined in `atmos.yaml`. This is the most
   common pattern for referencing shared configuration files (e.g., in a `config/` or `stacks/catalog/` directory)
   from any stack manifest, regardless of where that manifest is in the directory tree.

   ```yaml
   # Resolved relative to `base_path` in atmos.yaml (typically the repo root)
   policy: !include.raw stacks/catalog/policies/deny.rego
   readme: !include.raw config/README.md
   ```

   For example, given this `atmos.yaml`:

   ```yaml
   base_path: "./"
   ```

   The path `config/README.md` in any manifest resolves to `<repo-root>/config/README.md`.

### Remote Files

- HTTP/HTTPS: `!include.raw https://example.com/config.json`
- S3: `!include.raw s3::https://bucket.s3.amazonaws.com/file.yaml`
- GCS: `!include.raw gcs::gs://bucket/path/file.hcl`
- Git: `!include.raw git::https://github.com/org/repo.git//file.txt?ref=v1.0.0`

## See Also

- [`!include`](./include) - Standard include function with automatic parsing based on file extension
- [YAML Functions](/functions/yaml) - Overview of all YAML functions in Atmos