---
title: "Config and sources"
description: "Load a resolved configuration, read the documents of a source and make sure checkouts exist."
canonical_url: "https://diglot.sh/store/config-and-sources"
---
# Config and sources

> Load a resolved configuration, read the documents of a source and make sure checkouts exist.

## Load the configuration

`loadConfig(cwd = '.', overrides = {})` finds `diglot.config.ts`, `.mts`, `.js` or `.mjs` in `cwd`, imports it, merges `overrides` over it and resolves the result. The returned `ResolvedConfig` has defaults applied and paths made absolute:

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Content
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        root
      </code>
    </td>
    
    <td>
      The absolute directory of the translations repository
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        locales
      </code>
    </td>
    
    <td>
      The target locales
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sources
      </code>
    </td>
    
    <td>
      The sources, from <code>
        sources.yml
      </code>
      
       or from the config itself
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        parser
      </code>
    </td>
    
    <td>
      <code>
        comark
      </code>
      
       or <code>
        mdast
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        policy
      </code>
      
      , <code>
        diff
      </code>
      
      , <code>
        mt
      </code>
    </td>
    
    <td>
      As configured, or empty objects
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        outDir
      </code>
      
      , <code>
        stateDir
      </code>
    </td>
    
    <td>
      Absolute paths, from <code>
        dist
      </code>
      
       and <code>
        .diglot
      </code>
      
       by default
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        glossary
      </code>
    </td>
    
    <td>
      The absolute path of the shared glossary, when one is configured or <code>
        glossary.yml
      </code>
      
       exists
    </td>
  </tr>
</tbody>
</table>

A config may import `@diglot/core` without installing it next to the file. Locales that aren't valid BCP 47 tags throw an error that names the tag. A missing `sources.yml` yields no sources unless the config names one explicitly, in which case the read error is thrown.

`resolveConfig(config, root)` applies the same resolving to a config object you already have, and loads `sources.yml` when the object doesn't list sources itself.

## Parse sources

`parseSources(content)` parses the text of a `sources.yml`, either a list or an object with a `sources` list. It checks that every source has a valid unique `name` and that the string and list fields have the right type, and throws an error that names the offending source. See [define sources](https://diglot.sh/guide/how-to/sources) for the fields.

## Read a source

`readSource(source, cwd)` returns `{ source, sha?, files }`. Each file is `{ path, content }` with the path relative to the checkout root, sorted by path. With a `ref`, the files come from git at that commit, so the working tree doesn't matter. Without a `ref`, the working tree is read and `sha` is the current `HEAD` when there is one. A source without a `path` throws.

`include` and `exclude` are globs relative to `dir`. `DEFAULT_INCLUDE` is `['**/*.md', '**/.navigation.yml']`.

## Ensure checkouts

`ensureCheckouts(config, sources, cloneUrl?)` makes sure that each source's checkout exists and has its refs, then returns the sources with `path` filled in where it was missing (`<stateDir>/checkouts/<repo>`). A missing path is created as a bare repository, existing bare repositories are refreshed, and working copies with a `.git` directory are left alone. All refs of sources that share a checkout are fetched in one go, one commit deep. A source that needs fetching but has no `ref` throws.

`cloneUrl` maps `owner/repo` to a URL and defaults to `https://github.com/<repo>.git`.


## Sitemap

See the full [sitemap](https://diglot.sh/sitemap.md) for all pages.