# 참조와 가져온 폴더

값을 필요한 폴더마다 복사하지 않고 한곳에 두는 기능이 두 가지 있습니다.

- **참조**는 값 안에서 다른 시크릿을 가리킵니다. 값이
  `postgres://${DB_USER}:${DB_PASSWORD}@db.internal/app`이면 프로그램이 읽을 때 `DB_USER`와
  `DB_PASSWORD`의 값으로 채워집니다.
- **가져온 폴더**는 그 폴더의 키를 모두 다른 폴더에 빌려줍니다. `shared:/`를 각 환경의 루트로 가져오면
  `shared`에 둔 키를 모든 환경이 자기 키처럼 읽습니다.

둘 다 시크릿을 읽을 때 해석됩니다. 그래서 가리키는 시크릿이나 가져온 폴더의 키를 바꾸면 따로 고칠 복사본 없이
모든 곳에서 읽는 값이 바뀝니다.

## 참조 쓰기

시크릿 값에 다음 중 하나를 씁니다.

| 쓰는 것 | 읽는 값 |
|---|---|
| `${KEY}` | 같은 폴더의 `KEY` |
| `${production.KEY}` | `production` 환경 루트의 `KEY` |
| `${production.billing.stripe.KEY}` | `production`의 `/billing/stripe` 폴더에 있는 `KEY` |

값에 `${`를 글자 그대로 넣으려면 `$${`라고 씁니다. 참조가 가리키는 시크릿에 또 참조가 있어도 되며, 5단계까지
따라갑니다.

지금 해석되지 않는 참조(키나 폴더가 아직 없거나 읽을 권한이 없음)가 있는 값을 저장하면, 편집기가 그 참조를
보여 주고 저장할지 묻습니다. 쓴 그대로 두려면 **그대로 저장**을 고릅니다. `.env` 가져오기도 미리 보기에서 같은
경고를 보여 줍니다. 올바르지 않은 참조가 있거나 참조가 돌고 돌게 되는 값은 저장되지 않고, 편집기가 이유를
알려 줍니다.

값을 표시하면 참조 부분이 강조되어, 읽을 때 무엇이 채워지는지 알 수 있습니다. 표시되는 값은 참조까지 포함해
저장된 그대로입니다.

## 폴더 가져오기

폴더의 시크릿 아래 **가져온 폴더**에 이 폴더가 가져오는 폴더가 순서대로 나옵니다.

1. **가져온 폴더 편집**을 고릅니다.
2. **환경**을 고르고 **폴더 경로**를 입력한 뒤(환경의 루트는 `/`) **폴더 추가**를 고릅니다. 폴더는 최대
   20개까지 가져올 수 있고, 자기 자신은 가져올 수 없습니다.
3. 화살표로 순서를 바꾸거나 **빼기**로 폴더를 뺍니다.
4. **바뀌는 내용 보기**를 고릅니다. **지금** 목록과 **저장 후** 목록이 나오고, 추가되거나 빠지거나 순서가
   바뀐 것이 표시됩니다.
5. **가져온 폴더 저장**을 고릅니다.

순서가 중요합니다. 뒤에 있는 폴더가 앞의 폴더보다 우선하고, 이 폴더의 시크릿은 가져온 모든 폴더보다 우선합니다.
가져오기는 한 단계만 적용됩니다. 가져온 폴더가 다시 가져오는 폴더는 포함되지 않습니다.

### 키가 어디서 오는지 보기

목록 아래에는 가져온 폴더에서 들어오는 키마다 그 키를 가진 폴더가 모두 나옵니다. 값이 쓰이는 폴더는 강조되고,
그 폴더에 가려진 폴더에는 취소선이 그어집니다. **쓰이는 값**은 이 폴더의 시크릿이 우선하는지, 어느 가져온
폴더의 값인지 알려 줍니다.

이 목록은 키만 보여 주고 값은 표시하지 않습니다. 읽을 권한이 없는 폴더는 이름만 나오고 키는 나오지 않습니다.
더 이상 없는 폴더를 가져오고 있으면 **폴더 없음**으로 표시되고, 그 폴더가 다시 만들어질 때까지 아무 키도
들어오지 않습니다.

## 해석된 값 미리 보기

**해석된 값**을 고르면 프로그램이 이 폴더에서 읽는 값을 봅니다. 직접 넣은 키와 가져온 키가 모두 나오고, 참조는
채워져 있으며, 각 값이 어느 폴더에서 왔는지도 나옵니다.

값을 표시할 때처럼 이 미리 보기도 읽은 모든 폴더와 함께 [감사 로그](https://www.mocco.club/docs/ko/articles/2yiscf-audit-log)에 남고, 1분
뒤 다시 가려집니다.

해석되지 않는 것이 있으면 키, 참조, 이유가 나옵니다.

| 이유 | 해결 방법 |
|---|---|
| 그런 시크릿이 없음 | 키를 추가하거나 참조의 이름을 고칩니다 |
| 그런 환경이나 폴더가 없음 | 만들거나, 참조나 가져온 폴더의 경로를 고칩니다 |
| 그 폴더를 읽을 권한이 없음 | 소유자나 관리자에게 권한을 요청하거나 다른 폴더를 가리킵니다 |
| 참조가 돌고 돌아 제자리로 옴 | 미리 보기에 나온 고리(예: `A` → `B` → `A`)를 끊습니다 |
| 참조가 5단계보다 깊음 | 최종 값에 더 가까운 곳을 가리킵니다 |
| 올바른 참조가 아님 | `${…}`를 고치거나, `${`를 글자로 쓰려면 `$${`라고 씁니다 |
| 해석된 값이 너무 큼 | 값을 이루는 시크릿을 줄입니다 |

해석되지 않은 참조는 값에 쓴 그대로 남습니다. 그래서 프로그램은 빈 문자열이 아니라 `${KEY}`를 보게 됩니다.