SwiftGen/Documentation/ConfigFile.md

# SwiftGen Configuration File

SwiftGen expects you to have a `swiftgen.yml` configuration file at the root of your repository, to specify which files to parse, what template to use, and where to write the generated files.

## Creating a Config file

To create your configuration file, you can use the **`swiftgen config init`** command.

This will create (and open) an example configuration file that you can use for inspiration, with some typical entries commented out. All you have to do is to then uncomment the parts of the config that you need, adapt them to your project, and/or copy&paste the examples to add configuration for additional parsers.

You can of course also create the `swiftgen.yml` configuration file manually from scratch, using the text editor of your choice. The file just has to be in YAML format _(note: JSON, being a subset of YAML, is also supported)_ and provide the keys described below.


For more options (like using a file at another path or with another name, checking your config file for errors, …), see further below.

## Configuration File Format

### Global Structure

The configuration file is a YAML file structured like this (example):

```yaml
input_dir: Sources/Resources
output_dir: Sources/Generated/
strings:
  inputs: Base.lproj
  filter: .+\.strings$
  outputs:
    - templateName: structured-swift5
      output: L10n-Constants.swift
xcassets:
  - inputs: Logos.xcassets
    outputs:
      - templateName: swift5
        output: Logos-Constants.swift
        params:
          enumName: Logos
  - inputs:
      - Colors.xcassets
      - Images.xcassets
    outputs:
      - templatePath: Resources/my-assets-custom-template.stencil
        output: Assets-Constants.swift
```

ℹ️ All _relative_ paths specified in the configuration file (`input_dir`, `output_dir`, `inputs`, `templatePath`, `output`) are relative to the location of the _configuration file_ itself.

> 💡 We advise against using _absolute_ paths — starting with `/` — in the configuration file, so that they won't rely on where the project was cloned on your machine.

### Keys details

Here's a quick description of all the possible _root_ keys. All of them are optional.

| Key | Description | Intended usage |
|-----|-------------|----------------|
| `input_dir` | If present, it is prepended to all input `inputs` keys used in the rest of the configuration file | This is useful to avoid repeating any common subdirectory everywhere in each `inputs` key, when all your input paths are all in subdirectories of a common parent folder. |
| `output_dir` | If present, it is prepended to all `output` keys used in the rest of the configuration file | This is useful if, like most people, you want all files generated by SwiftGen to be generated in a common directory like `Sources/Generated/` for example. |
| `colors` | Describe the parameters to run with the `colors` parser | See below for a detail of all the subkeys. |
| `coredata` | Describe the parameters to run with the `coredata` parser | See below for a detail of all the subkeys. |
| `files` | Describe the parameters to run with the `files` parser | See below for a detail of all the subkeys. |
| `fonts` | Describe the parameters to run with the `fonts` parser | See below for a detail of all the subkeys. |
| `ib` | Describe the parameters to run with the `ib` parser | See below for a detail of all the subkeys. |
| `json` | Describe the parameters to run with the `json` parser | See below for a detail of all the subkeys. |
| `plist` | Describe the parameters to run with the `plist` parser | See below for a detail of all the subkeys. |
| `strings` | Describe the parameters to run with the `strings` parser | See below for a detail of all the subkeys. |
| `xcassets` | Describe the parameters to run with the `xcassets` parser | See below for a detail of all the subkeys. |
| `yaml` | Describe the parameters to run with the `yaml` parser | See below for a detail of all the subkeys. |

Each key corresponding to a SwiftGen parser (`colors`, `coredata`, `files`, `fonts`, `ib`, `json`, `plist`, `strings`, `xcassets`, `yaml`) expects the corresponding value to be:

* Either a dictionary, with the keys described below, if you want to invoke the corresponding SwiftGen parser only once (most common use case)
* Or an array of those dictionaries, in the less common case where you need to invoke that SwiftGen parser multiple times (for example to use one template with some input files and another template for other input files…)

| Subkey | Type | Description |
|--------|------|-------------|
| `inputs` | Path or Array of Paths | The file(s)/dir(s) to parse (e.g. the path to your assets catalog for the `xcassets` command, or your `.lproj` or `Localizable.strings` file for the `strings` command, etc). |
| `options` | Dictionary | Any optional list of settings for the parser, to change its behaviour. See the commands' specific documentation for available options. |
| `filter` | Regular Expression | The regular expression to apply to each input path; only paths matching the given filter will be used. Filters are applied to actual (relative) paths, not just the filename. Note that each command has a default built-in filter (based on expected file extensions), so you generally don't need to specify this subkey in your config file; but it is useful if you want to override it with a custom filter. |
| `outputs` | Array | A list of output descriptions, composed of a template and a file output. |
| ~~`paths`~~ | Path or Array of Paths | **Deprecated** ~~The file(s)/dir(s) to parse (e.g. the path to your assets catalog for the `xcassets` command, or your `Localizable.strings` file for the `strings` command, etc).~~ |
| ~~`templateName`~~ | String | **Deprecated** ~~The name of the template to use. If you provide a value for this, you shouldn't also provide a value for `templatePath`.~~ |
| ~~`templatePath`~~ | Path | **Deprecated** ~~The path to the template to use. If you provide a value for this, you shouldn't also provide a value for `templateName`.~~ |
| ~~`output`~~ | Path | **Deprecated** ~~The path of the output file to generate. _(Note: Any intermediate directory up to this file must already exist.)_~~ |
| ~~`params`~~ | Dictionary | **Deprecated** ~~Any optional parameter you want to pass to the template (similarly to `--param` in the CLI).~~ |

> 💡 Tip: For custom file filters, use `.+` to match multiple characters (at least one), and don't forget to escape the dot (`\.`) if you want to match a literal dot like for an extension. Add `$` at the end to ensure the path ends with the extension you want. Regular expressions will be case sensitive by default, and not anchored to the start/end of a path. For example, use `.+\.xib$` to match files with a `.xib` extension. Use a tool such as [RegExr](https://regexr.com) to ensure you're using a valid regular expression.

The `outputs` parameter accepts either a dictionary, or an array of dictionaries, with the keys described below. Each such "output" will take the input files, and use the output template to generate a file at the given output path. This allows you to generate multiple outputs for the same input files (which will only be parsed once).

| Subkey | Type | Description |
|--------|------|-------------|
| `templateName` | String | The name of the template to use. If you provide a value for this, you shouldn't also provide a value for `templatePath`. |
| `templatePath` | Path | The path to the template to use. If you provide a value for this, you shouldn't also provide a value for `templateName`. |
| `output` | Path | The path of the output file to generate. _(Note: Any intermediate directory up to this file must already exist.)_ |
| `params` | Dictionary | Any optional parameter you want to pass to the template. See the template documentation in GitHub (or using `swiftgen template doc` command) for the list of available params each template supports. |

Note that:

* `inputs` and `outputs` are mandatory.
* You must specify either `templateName` or `templatePath`, but not both, nor neither.
* `params` is optional.

### Environment Variables

You can use environment variables in your config file, by using the `${VARNAME}` syntax. Those environment variables will be expanded when SwiftGen parses the config file.

If you're running `swiftgen` as part of a Script Build Phase in Xcode, this especially allows you to inject values coming from Xcode's build settings (as Xcode expose those as env vars) into your config file. For example:

```yaml
strings:
  inputs: ${PROJECT_DIR}/${TARGET_NAME}/Resources/
  outputs:
    templateName: structured-swift5
    output: ${PROJECT_DIR}/${TARGET_NAME}/Constants/Strings-${TARGET_NAME}.swift
```

## Advanced options for running the config file

Running `swiftgen` without any subcommand or argument is actually a shortcut invocation which is equivalent to running `swiftgen config run`.

If you need more control when using a configuration file, you can use some advanced features by using the full `swiftgen config run` command to specify more options. In particular you can:

* Ask to use a different config file — instead of the default `swiftgen.yml` — using the `--config` flag.

  ```sh
  swiftgen config run --config tools/swiftgen/swiftgen-config.yml
  ```

* When you want to create a new config file, you can also provide an alternate path where to create the file with a similar `--config` flag.

  ```sh
  swiftgen config init --config tools/swiftgen/swiftgen-config.yml
  ```
  
* Change the default log level to quiet or verbose. If no log level is specified, default will be used.

  * Verbose mode (`--verbose` or `-v` flag), which will print every command being executed when executing it. This allows your to:
    * control what is being run, by logging what happens during execution
    * know the equivalent command to type if you were to run each swiftgen command manually instead of using the config file — which can be useful if you need to debug or tweak a particular command in isolation for example

      ```sh
      swiftgen config run --verbose
      ```
  * Quiet mode (`--quiet` or `-q` flag), which will silence all logs (except for errors):

      ```sh
      swiftgen config run --quiet
      ```

## Linting the configuration file

You can also use `swiftgen config lint` (or `Pods/SwiftGen/bin/swiftgen config lint` if you installed it using CocoaPods) to lint the configuration file.

Without any additional option this will lint the default `swiftgen.yml` configuration file, but you can specify a different configuration file using the `--config` flag, similarly to `swiftgen config run`

`swiftgen config lint` will ensure that:

* the YAML file is a valid YAML
* each mandatory key in the YAML is present
* each key is of the expected type.

It will print a descriptive error in case there's something wrong, and describe the interpretation of the content of the configuration file if everything is valid.