노트 이름을 바꾸고 참조를 안전하게 갱신하기
노트의 이름은 한 값이 아니다. 사람이 읽는 title, 파일 시스템의 경로, 검색과 이전 이름 호환에 쓰는 aliases, 다른 문서가 저장한 explicit reference가 함께 문서 identity를 이룬다. Glif의 노트 이름 변경 리팩터는 이 값들을 한 dialog에서 검토하고, 지원하는 참조를 새 경로로 다시 쓴 뒤 한 작업으로 적용한다.
단순히 파일 탐색기에서 .md 파일 이름만 바꾸면 다른 문서의 링크가 이전 경로를 계속 가리킬 수 있다. 이 명령은 적용 전에 영향 범위를 숫자로 보여 주고, 실패하면 이미 시작한 쓰기와 경로 이동을 되돌리는 방식으로 그 위험을 줄인다.
이름 변경에서 서로 다른 네 값
| 값 | 이 예제의 변경 | 저장 위치 | 영향 |
|---|---|---|---|
| 문서 제목 | 릴리즈 점검표 → 출시 승인 체크리스트 |
front matter title |
탭, 검색 결과와 title 기반 표시 |
| 파일 경로 | notes/release-checklist.md → playbooks/launch-approval-checklist.md |
Scope 안의 파일 시스템 | 경로 기반 link와 embed target |
| 별칭 | 기존 별칭 + 새 별칭 + 이전 대표 제목 | front matter aliases |
이전 이름 검색·자동 연결 호환 |
| explicit reference | 지원 문법의 target만 새 상대 경로로 변경 | 참조하는 각 .md 파일 |
링크와 embed가 이동한 문서를 계속 가리킴 |
본문의 # H1은 front matter title과 별개다. 이 장의 실증에서도 title은 출시 승인 체크리스트로 바뀌었지만 본문 첫 heading # 릴리즈 점검표는 그대로 남았다. 두 값을 같게 유지하려면 적용 뒤 H1을 직접 편집한다.
실습 파일
세 파일을 같은 rename-note 폴더 구조로 내려받아 별도 위치에 복사한 뒤, 그 복사본을 Scope로 연다.
- 이름을 바꿀
notes/release-checklist.md - Markdown 참조가 있는
release-dashboard.md - wiki link와 embed가 있는
operations-hub.md
대상 노트의 시작 metadata는 다음과 같다.
---
title: 릴리즈 점검표
aliases:
- 배포 체크리스트
---두 참조 문서는 일반 link, fragment link, reference definition, 확장자를 생략한 wiki link와 fragment를 가진 wiki embed를 포함한다. code fence와 inline code에는 같은 이전 경로를 문법 예시로 넣었다. 이름 변경이 실제 참조와 설명용 code를 구분하는지 함께 확인하기 위한 구성이다.
1. 변경 전 참조를 확인한다
release-dashboard.md에는 대상 note를 가리키는 세 참조와 고치지 않아야 할 code fence가 있다.
[릴리즈 점검표](notes/release-checklist.md)
[승인 절차 바로가기](notes/release-checklist.md#approval)
[승인 기준][release-checklist]
[release-checklist]: notes/release-checklist.md#approval
```markdown
[문법 예시](notes/release-checklist.md)
```
현재 link가 모두 열리고 #approval이 승인 절차 heading으로 이동하는지 먼저 확인한다. 이미 깨진 link가 있다면 rename 결과와 기존 결함을 구분하기 어렵다.
2. 노트 이름 변경 리팩터를 연다
notes/release-checklist.md를 활성화한 뒤 Ctrl+P를 누른다. 검색창 맨 앞에 >를 입력해 명령 모드로 바꾸고 노트 이름 변경을 검색한 다음 노트 이름 변경 리팩터를 선택한다.
dialog 기본값은 현재 문서에서 읽은 값이다.
- 제목: 현재 front matter
title - 파일 이름: 현재
.md파일 이름 - 저장 위치: Scope root 기준 현재 상위 폴더
- aliases: 현재 별칭을 한 줄에 하나씩 표시
- 이전 대표 제목을 alias로 보존: title이 바뀔 때 이전 대표 이름을 호환 별칭으로 유지
기본 상태에서도 영향 검토가 계산된다. 제목이나 경로를 바꾸지 않고 aliases만 정리할 수도 있지만, 아무 값도 바꾸지 않았다면 적용할 실제 변경이 없다는 안내가 나타난다.
3. 새 identity 값을 입력한다
이 예제에서는 다음처럼 입력한다.
| 필드 | 입력값 |
|---|---|
| 제목 | 출시 승인 체크리스트 |
| 파일 이름 | launch-approval-checklist.md |
| 저장 위치 | playbooks |
| aliases | 배포 체크리스트, 릴리즈 승인표 |
| 이전 대표 제목 보존 | 선택 |
파일 이름에서 .md를 생략하면 Glif가 확장자를 보완한다. 저장 위치는 Scope root 기준 상대 경로이며 여러 폴더를 /로 구분할 수 있다.
Scope 밖 경로는 적용할 수 없다
../outside처럼 . 또는 .. segment를 사용해 상위 폴더로 빠져나가는 위치는 차단된다. 이때 영향 검토 대신 오류가 표시되고 적용 버튼을 사용할 수 없다.
드라이브 문자나 /로 시작하는 절대 경로를 입력하지 않는다. 다른 Scope로 옮기는 작업은 이름 변경 리팩터가 아니라 명시적인 문서 이동·가져오기 흐름으로 처리한다.
4. 영향 검토를 숫자로 읽는다
유효한 playbooks 위치를 입력하면 Glif가 적용 전에 write plan을 다시 만든다. 이번 fixture에서 관측한 값은 다음과 같다.
| 검토 항목 | 관측값 | 의미 |
|---|---|---|
| 새 경로 | playbooks/launch-approval-checklist.md |
Scope root 기준 최종 target |
| 갱신 문서 수 | 2 | 대상 note 외에 참조가 바뀌는 문서 수 |
| Markdown 링크 | 2 | inline link 두 개 |
| reference definition | 1 | [id]: target 정의 한 개 |
| 위키 링크 | 1 | [[target]] 계열 한 개 |
| embed syntax | 1 | ![[target#fragment]] 한 개 |
| fragment 포함 참조 | 3 | #approval을 보존해야 하는 참조 수 |
개수는 “문자열을 몇 번 바꾼다”는 뜻이 아니다. parser가 실제 참조로 판정한 지원 문법만 센다. 따라서 code fence와 inline code 안의 문법 예시는 포함되지 않는다.
적용 전에 최소한 다음을 대조한다.
- 새 경로가 의도한 Scope 안에 있는가?
- 참조 문서 수가 알고 있는 참조자와 지나치게 다르지 않은가?
- fragment 참조 수가 heading link·embed의 예상 개수와 맞는가?
- 적용 aliases에 기존 별칭과 보존할 이전 제목이 모두 있는가?
예상보다 0이 많다면 취소하고 Link Health, 검색과 원문 문법을 확인한다. rename은 임의의 일반 텍스트나 code 예시를 전역 치환하지 않는다.
이름 변경 전체 흐름 영상
다음 9.1초 영상은 변경 전 참조, dialog 기본값, 잘못된 상위 경로 차단, 영향 검토, 적용된 target, Markdown 참조와 wiki 참조 검증을 순서대로 보여 준다.
5. 적용된 target을 확인한다
적용을 누르면 target은 playbooks/launch-approval-checklist.md로 이동하고 활성 탭과 파일 트리도 새 경로를 가리킨다. 이전 notes/release-checklist.md는 남지 않아야 한다.
실증 결과 metadata의 핵심 identity는 다음과 같다.
title: 출시 승인 체크리스트
aliases:
- 배포 체크리스트
- 릴리즈 승인표
- 릴리즈 점검표릴리즈 점검표는 이전 대표 제목을 alias로 보존했기 때문에 자동으로 추가됐다. 이미 같은 이름을 다른 문서가 title 또는 alias로 사용해 충돌한다면 Glif는 이전 제목을 무조건 보존하지 않고 warning으로 경계를 알린다. 충돌을 확인한 뒤 더 구체적인 별칭을 직접 선택한다.
화면에서 본문 H1이 여전히 릴리즈 점검표인 것도 확인한다. H1까지 새 표현으로 맞추려면 다음처럼 별도 편집한다.
-# 릴리즈 점검표
+# 출시 승인 체크리스트
6. Markdown link와 reference definition을 확인한다
열려 있던 release-dashboard.md도 적용 직후 새 target을 표시해야 한다. 이번 실증에서는 Windows 경로 separator가 다른 열린 탭까지 같은 문서로 판정해 즉시 갱신되는 것을 확인했다.
-[릴리즈 점검표](notes/release-checklist.md)
+[릴리즈 점검표](playbooks/launch-approval-checklist.md)
-[승인 절차 바로가기](notes/release-checklist.md#approval)
+[승인 절차 바로가기](playbooks/launch-approval-checklist.md#approval)
-[release-checklist]: notes/release-checklist.md#approval
+[release-checklist]: playbooks/launch-approval-checklist.md#approval
다음 요소는 보존된다.
- link label
릴리즈 점검표,승인 절차 바로가기 - reference id
release-checklist - heading fragment
#approval - code fence 안의
[문법 예시](notes/release-checklist.md)
여기서 경로는 새 target의 절대 경로를 복사한 값이 아니라 각 참조 문서에서 계산한 상대 경로다. 참조 문서 자체도 다른 폴더로 이동한다면 그 문서 기준 결과를 다시 확인한다.
7. wiki link와 embed를 확인한다
operations-hub.md의 wiki 문법은 원래 확장자 사용 방식을 유지한다.
-[[notes/release-checklist|릴리즈 점검표]]
+[[playbooks/launch-approval-checklist|릴리즈 점검표]]
-![[notes/release-checklist.md#approval]]
+![[playbooks/launch-approval-checklist.md#approval]]
첫 wiki link는 원래 .md를 생략했으므로 새 경로에서도 생략한다. embed는 원래 .md와 #approval을 썼으므로 둘 다 보존한다. |릴리즈 점검표 label도 target path와 별개이므로 바뀌지 않는다.
inline code의 `[[notes/release-checklist]]`는 문법을 설명하는 텍스트이므로 이전 값 그대로 남는다. 실제 참조로 바꾸려면 backtick을 제거한 뒤 다시 rename하거나 직접 target을 고친다.
지원하는 rewrite와 경계
| 문법 | rewrite | 보존하는 요소 |
|---|---|---|
[label](note.md) |
예 | label, query·fragment |
[label][id] + [id]: note.md |
definition target 갱신 | label과 reference id, fragment |
[[note]]과 label variant |
예 | .md 생략 여부, label, fragment |
![[note.md#heading]] |
예 | embed marker, 확장자 방식, fragment |
| inline code와 fenced code | 아니요 | 원문 전체 |
| 일반 텍스트의 파일 이름 | 아니요 | 원문 전체 |
| 외부 URL | 아니요 | 원문 전체 |
| parser가 해석할 수 없는 사용자 정의 문법 | 보장하지 않음 | 검색과 수동 검토 필요 |
“모든 문자열”이 아니라 “지원하는 explicit reference”를 갱신한다는 경계를 기억한다. 사용자 정의 shortcode, HTML attribute, script와 데이터 파일에 경로를 저장했다면 Scope 검색으로 별도 확인한다.
적용은 검토 결과와 같은 작업이어야 한다
dialog를 연어 둔 사이 다른 문서가 바뀌면 처음 계산한 영향 범위가 낡을 수 있다. Glif는 적용 직전에 plan을 다시 계산하고 검토 generation과 다르면 이전 검토를 그대로 실행하지 않는다. 현재 상태에서 다시 검토한 뒤 적용한다.
또한 이름 변경을 시작한 Scope와 적용 순간의 활성 Scope가 다르면 작업을 중단한다. 다른 프로젝트에 같은 상대 경로가 있다고 해서 그 프로젝트에 쓰지 않는다.
실패와 rollback
이름 변경은 다음 순서의 여러 쓰기를 포함한다.
- target metadata 저장
- 필요하면 파일 경로 이동
- 참조 문서들을 새 내용으로 저장
- 열린 탭·최근 문서·활성 문서 같은 session path 동기화
중간 참조 문서 저장이 실패하면 앞에서 완료된 target 쓰기와 경로 이동을 원래 내용·경로로 되돌린다. rollback도 일부 실패한 예외 상황에서는 “성공”으로 숨기지 않고 남아 있는 경로를 오류에 포함한다.
오류가 보이면 같은 명령을 즉시 반복하기 전에 다음 순서로 확인한다.
- 이전 경로와 새 경로 중 어느 파일이 존재하는지 확인한다.
- target의
title과aliases가 이전 값인지 새 값인지 확인한다. - 영향 검토에 나온 두 참조 문서를 열어 old/new target을 검색한다.
- 오류가 보고한 남은 경로를 기록하고 사본을 만든다.
- Link Health에서 깨진 참조를 확인한다.
- 상태가 명확해진 뒤 현재 파일을 기준으로 다시 검토한다.
파일을 임의로 여러 번 이동하거나 old/new 파일을 동시에 남기면 identity 충돌이 커질 수 있다. rollback이 완전하지 않다는 메시지가 있다면 먼저 사본을 확보한다.
예상과 다를 때
| 증상 | 원인 후보 | 조치 |
|---|---|---|
| 명령 검색에 나타나지 않음 | command mode가 아님 | Ctrl+P 뒤 > 노트 이름 변경 입력 |
| 적용 버튼이 비활성 | 변경 없음, 잘못된 상대 경로 또는 target 충돌 | dialog warning과 새 경로 확인 |
.. 경로 오류 |
Scope 밖으로 이동하려 함 | Scope root 기준 정상 하위 경로 입력 |
| 같은 경로 문서가 이미 있음 | 새 파일 이름·폴더 충돌 | 기존 문서를 덮어쓰지 말고 고유 경로 선택 |
| 예상 참조 수보다 적음 | code 안의 예시, 일반 텍스트 또는 미지원 문법 | Scope 검색으로 old path를 찾아 수동 검토 |
| label이 이전 제목으로 남음 | label은 target path와 별개 | 문맥상 필요할 때 label만 별도 편집 |
| 본문 H1이 이전 제목 | rename의 title은 front matter 값 |
H1을 의도에 맞게 직접 편집 |
| 이전 제목 alias가 없음 | 보존 선택 해제 또는 title/alias 충돌 | warning 확인 후 안전한 별칭 직접 추가 |
| 적용 직전 stale review 오류 | dialog를 연 뒤 관련 파일이 바뀜 | 최신 상태로 영향 검토 다시 실행 |
| 활성 Scope 오류 | 검토 뒤 다른 Scope로 전환 | 원래 Scope에서 명령을 다시 시작 |
| 적용 후 열린 탭과 파일이 다름 | 외부 변경 또는 session 동기화 문제 | 저장 상태를 확인하고 탭을 다시 연 뒤 Link Health 실행 |
완료 체크리스트
- 새
title, 파일 이름과 Scope root 기준 저장 위치가 의도와 같다. - 기존 aliases와 새 aliases, 이전 대표 제목 보존 여부를 검토했다.
- 영향 검토의 문서·문법·fragment 개수가 예상과 맞는다.
- 이전 파일 경로가 사라지고 새 파일 경로가 존재한다.
- target front matter의
title과aliases가 예상과 같다. - 본문 H1을 유지할지 새 title에 맞출지 별도로 결정했다.
- Markdown inline link 두 개와 reference definition이 새 상대 경로를 가리킨다.
- wiki link label,
.md사용 방식과 embed fragment가 보존됐다. - inline code와 fenced code의 설명 예시는 바뀌지 않았다.
- 이전 경로를 Scope 검색해 미지원 참조가 남지 않았는지 확인했다.
- 새 target을 실제로 열고
#approvalfragment로 이동했다. - Link Health에서 새 깨진 참조가 생기지 않았다.
다음 단계에서는 선택·문단·문서 범위의 plain text normalize와 metadata 편집 경계를 다룬다.