# !include.raw

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

## Availability and evaluation

Supported locations:

- **CLI configuration** (`atmos.yaml`, `atmos.d`, and profiles): during file loading.
- **Stack manifests**: during file loading, before inheritance and merging.
- **Workflow manifests**: during manifest loading.
- **Scaffold manifests**: during manifest loading.

The path cannot depend on the final merged component context.

Automatic evaluation requires native YAML tags from edition `2026-10-20`, including unpinned projects. Quoted function strings remain literal; earlier editions retain legacy string-form behavior.

See [YAML function scope](/functions/yaml/scope) for field restrictions, import timing, and native tags versus quoted strings.

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 three kinds of local file paths. The kind is decided by how the path is
written, and Atmos never falls back from one kind to another:

| Path | Resolved relative to |
| --- | --- |
| `/abs/script.sh` | Nothing — used as written |
| `./script.sh`, `../script.sh` | The directory of the file that contains the `!include.raw` |
| `scripts/script.sh` | [`base_path`](/cli/configuration#base-path) |

Each kind has one primary location. If the file does not exist there, `!include.raw` fails with an error that
names where it looked. The only fallback is for bare paths in stack manifests, which are also checked against the
directory you run Atmos from (see below). A `./` path that is missing next to the including file is never replaced
by a same-named file under `base_path`; when one exists, the error suggests dropping the `./` prefix.

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

2. **Paths relative to the including file (`./` or `../`)** — Paths that start with `./` or `../` are resolved
   relative to the directory of the file that contains the `!include.raw` — the stack manifest, or the imported catalog
   file, where the tag is written. For example, if the manifest is at `stacks/deploy/dev.yaml`, then
   `../config/policy.rego` resolves to `stacks/config/policy.rego`. Only that location is checked.

   ```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`.

   For stack manifests, a bare path that does not exist under `base_path` is checked against the directory you run
   Atmos from as a last resort. Don't rely on it: the result then depends on where Atmos is invoked.

### 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