---
url: /reference/sgconfig.md
---

# `sgconfig.yml` Reference

## Overview

To scan a project with multiple rules, you need to specify the root of a project by maintaining a `sgconfig.yml` file.
The file is similar to `tsconfig.json` in TypeScript or `.eslintrc.js` in eslint.
You can also create the `sgconfig.yml` and related file scaffoldings by the `ast-grep new` command.

::: tip sgconfig.yml is not `rule.yml`
ast-grep has several kinds of yaml files. `sgconfig.yml` is for configuring ast-grep, like how to find rule directories or to register custom languages.
While `rule.yml` is to specify one single rule logic to find problematic code.
:::

`sgconfig.yml` has these options.

## `ruleDirs`

* type: `String`
* required: Yes

A list of string instructing where to discover ast-grep's YAML rules.

**Example:**

```yaml
ruleDirs:
- rules
- anotherRuleDir
```

Note, all items under `ruleDirs` are resolved relative to the location of `sgconfig.yml`.

## `testConfigs`

* type: `List` of `TestConfig`
* required: No

A list of object to configure ast-grep's test cases.
Each object can have two fields.

### `testDir`

* type: `String`
* required: Yes

A string specifies where to discover test cases for ast-grep.

### `snapshotDir`

* type: `String`
* required: No

A string path relative to `testDir` that specifies where to store test snapshots for ast-grep.
You can think it like `__snapshots___` in popular test framework like jest.
If this option is not specified, ast-grep will store the snapshot under the `__snapshots__` folder under the `testDir`.

Example:

```yaml
testConfigs:
- testDir: test
  snapshotDir: __snapshots__
- testDir: anotherTestDir
```

## `utilDirs`

* type: `String`
* required: No

A list of string instructing where to discover ast-grep's [global utility rules](/guide/rule-config/utility-rule#global-utility-rules).

## `noIgnore`

* type: `List` of `String`
* required: No

A list of ignore-file categories to disregard when searching. The `run`,
`scan`, and `outline` commands use these values.

Possible values:

* `hidden`: Search hidden files and directories.
* `dot`: Do not respect `.ignore` files. Hidden files and directories remain
  excluded unless `hidden` is also specified.
* `exclude`: Do not respect repository-specific ignore files such as
  `.git/info/exclude`.
* `global`: Do not respect global ignore sources such as Git's
  `core.excludesFile`.
* `parent`: Do not respect ignore files in parent directories.
* `vcs`: Do not respect version-control ignore files such as `.gitignore`. This
  implies `parent` for version-control files; `.ignore` files remain effective.

These values apply when no command-line `--no-ignore` options are supplied.
Supplying one or more `--no-ignore` options overrides the configured list.

**Example:**

```yaml
noIgnore:
  - hidden
  - vcs
```

## `languageGlobs`

* type: `HashMap<String, Array<String>>`
* required: No

A mapping to associate a language to files that have non-standard extensions or syntaxes.

ast-grep uses file extensions to discover and parse files in certain languages. You can use this option to support files if their extensions are not in the default mapping.

The key of this option is the language name. The values are a list of [glob patterns](https://www.wikiwand.com/en/Glob_\(programming\)) that match the files you want to process.

Note, `languageGlobs` takes precedence over the default language parser so you can reassign the parser for a specific file extension.

**Example:**

```yml
languageGlobs:
  html: ['*.vue', '*.svelte', '*.astro']
  json: ['.eslintrc']
  cpp: ['*.c'] # override the default parsers
  tsx: ['*.ts'] # useful for rule reuse
```

The above configuration tells ast-grep to treat the files with `.vue`, `.svelte`, and `.astro` extensions as HTML files, and the extension-less file `.eslintrc` as JSON files. It also overrides the default parser for C files and TS files.

:::tip Similar languages
This option can override the default language parser for a specific file extension, which is useful for rule reuse between similar languages like C/Cpp, or TS/TSX.
:::

## `outlineRules`

* type: `HashMap<String, String>`
* required: No
* default: no additional project outline rules

Since 0.51.3, maps built-in language names or aliases to outline extraction
rule files. Keys are ASCII case-insensitive; custom language names are not
accepted. Paths are resolved relative to `sgconfig.yml`.

These rules are added to bundled extractors and load without custom language
permission. `--no-default-outline-rules` disables only the bundled extractors;
`--outline-rules` adds command-line files after the configured rules.

See the [outline guide](/guide/outline-code#custom-extraction-rules) for setup
and the [extraction rule reference](/reference/outline-rules) for the file format.

## `customLanguages`

* type: `HashMap<String, CustomLang>`
* required: No

A dictionary of custom languages in the project.

The key of the dictionary is the custom language name. The value of the dictionary is the custom language configuration object.

Please see the [guide](/advanced/custom-language) for detailed instructions.

Since 0.50.0, the CLI loads these native libraries only when explicitly allowed
or when the configuration is trusted. See the
[custom language loading guide](/advanced/custom-language#enable-custom-language-loading)
for setup and trust management.

A custom language configuration object has the following options.

### `libraryPath`

* type: `String` or `HashMap<String, String>`
* required: Yes

The path to the tree-sitter dynamic library of the language. The string field is interpreted as the dynamic library path relative to the sgconfig.yml.

If `libraryPath` is a map, the key should be the [target triple](https://doc.rust-lang.org/rustc/platform-support.html) string and the value should be the dynamic library path. Projects supporting multiple host platforms can use object style configuration for different developers.

**Example:**

```yaml
# simple string is library path
libraryPath: my-lang-parser.so

# object style config
libraryPath:
  aarch64-apple-darwin: lang-parser-mac.so
  x86_64-unknown-linux-gnu: lang-parser-linux.so
# target triple list can be found below
# https://doc.rust-lang.org/rustc/platform-support.html
```

### `extensions`

* type: `Array<String>`
* required: Yes

The file extensions for this language.

### `outlineRules`

* type: `String`
* required: No

The path to the YAML file containing outline extraction rules for this custom
language. The path is resolved relative to `sgconfig.yml`.

When this field is set and custom language loading is enabled, `ast-grep outline`
loads the configured outline rules for the custom language. The `ignore` and
`revoke` loading policies skip these files along with the native libraries.
You can still pass additional
`--outline-rules` files on the command line; rules from `customLanguages` are
loaded before command-line outline rule files.

See [outline extraction rule reference](/reference/outline-rules) for the
rule file format.

### `expandoChar`

* type: `String`
* required: No

An optional char to replace $ in your pattern.

### `languageSymbol`

* type: `String`
* required: No

The dylib symbol to load ts-language, default is `tree_sitter_{name}`, e.g. `tree_sitter_mojo`.

**Example:**

```yaml
customLanguages:
  mojo:
      libraryPath: mojo.so     # path to dynamic library
      extensions: [mojo, 🔥]   # file extensions for this language
      outlineRules: outline/mojo.yml # optional outline extraction rules
      expandoChar: _           # optional char to replace $ in your pattern
```

## `languageInjections`&#x20;

* type: `List<LanguageInjection>`
* required: No
* status: **Experimental**

A list of language injections to support embedded languages in the project like JS/CSS in HTML.
This is an experimental feature.

Please see the [guide](/advanced/language-injection) for detailed instructions.

A language injection object has the following options.

### `hostLanguage`

* type: `String`
* required: Yes

The host language name, e.g. `html`. This is the language of documents that contains the embedded language code.

### `rule`

* type: `Rule` object
* required: Yes

Defines the ast-grep rule to identify the injected language region within the host language documents.

### `injected`

* type: `String` or `List<String>`
* required: Yes

The injected language name, e.g. `js`. This is the language of the embedded code.

It can be a static string or a list of strings. If it is a list, ast-grep will use the `$LANG` meta variable captured in the rule to dynamically determine the injected language. The list of strings is the candidate language names to match the `$LANG` meta variable.

**Example:**

This is a configuration to support styled-components in JS files with static `injected` language.

```yaml
languageInjections:
- hostLanguage: js
  rule:
    pattern: styled.$TAG`$CONTENT`
  injected: css
```

This is a configuration to support CSS in JS style in JS files with dynamic `injected` language.

```yaml
languageInjections:
- hostLanguage: js
  rule:
    pattern: styled.$LANG`$CONTENT`
  injected: [css, scss, less]
```
