본문으로 건너뛰기

[2/7] Obsidian과 GitHub로 원본 저장소 만들기

· 약 4분

이 글은 실제 Abulafium 구축 이력(2026-10-09 기준)을 바탕으로 다시 작성한 공개용 실습 매뉴얼입니다. [실제 검증]은 구축 과정에서 성공을 확인한 상태, [재현 절차]는 이를 일반화한 실행 순서, [확인 필요]는 실제 소스·대시보드를 추가 확인해야 하는 사항입니다. 명령어의 <USER>, <REPO_URL> 등은 자신의 환경으로 변경하세요.

완성 목표​

  • Git 저장소의 최상위에 사이트 코드와 원본 garden/을 함께 둔다.
  • garden/을 기존 폴더로 Obsidian Vault에 연결한다.
  • 문서 수정은 Git으로 명시적으로 Commit·Push한다.

사전 준비 [재현 절차]: Git, Obsidian, GitHub 접근 권한. Windows 예시를 기본으로 설명한다. 이미 GitHub에 저장소가 있다면 새 저장소로 초기화하지 말고 clone한다.

1. 왜 모노레포로 구성했나​

실제 사용한 저장소는 비공개 abulafium/abulafium이며 Git의 최상위는 C:\works\abulafium이다. garden/ 자체가 별도 Git 저장소가 아니다. Docusaurus 소스와 Markdown 원본을 동일 리비전으로 복원하기 위해 이 구조를 선택했다.

2. 저장소 준비 [재현 절차]​

Windows PowerShell:

New-Item -ItemType Directory -Force C:\works | Out-Null
Set-Location C:\works
git clone <REPO_URL> abulafium
Set-Location .\abulafium
git status -sb
git remote -v
Get-ChildItem

완료 조건: garden과 abulafium-site가 보이며 정상 브랜치와 원격 주소가 출력된다. git clone 전에 인증 체계(Git Credential Manager 또는 SSH 키)를 준비해야 한다. 저장소가 비어 있다면 garden/, abulafium-site/를 만들고 첫 Commit 후 Push하는 별도 초기화 작업이 필요하다.

3. Obsidian Vault 연결 [실제 검증]​

  1. Obsidian → 폴더를 보관함으로 열기를 선택한다.
  2. C:\works\abulafium\garden을 지정한다.
  3. 이름을 바꾼다고 폴더 이름 garden 자체를 변경하지 않는다.
  4. Obsidian Git 커뮤니티 플러그인을 설치한다.
  5. 작업 시작 시 Pull을 사용하되 Commit·Push는 수동으로 유지한다.

실제 시행착오: Vault 표시명을 바꾸려다 실제 garden/ 디렉터리 이름이 변경되어 Git이 대량 삭제/추가로 인식했다. 원래 garden/으로 복구하여 해결했다. 폴더 경로는 Docusaurus·Docker·Syncthing까지 연결돼 있기 때문이다.

4. Git 제외 규칙 [구성 확인]​

루트 .gitignore에 다음을 적용한다.

**/.obsidian/

이 규칙은 Obsidian 설정 파일을 Git에서 추적하지 않는다. Syncthing 무시 규칙과는 별개다. .gitignore를 수정했더라도 이미 추적 중인 파일은 git ls-files로 확인해야 한다. 삭제 조치는 상황에 따라 달라지므로 확인 없이 git rm을 일괄 실행하지 않는다.

5. 이미지와 Markdown 링크 [구성 확인]​

문서 첨부 이미지를 가까운 images/ 폴더에 두고 상대 경로의 표준 Markdown 링크를 사용한다.

blog/tech-notes/example.md
blog/tech-notes/images/example.png
![환경 설정](./images/example.png)

Obsidian의 [[wikilink]]보다 일반 Markdown 링크를 권장한 이유는 Docusaurus와 기타 Markdown 처리기에서의 호환성 때문이다. 첨부 이미지 경로 설정을 문서 작성 전에 테스트한다.

6. 실제 Git 작업 절차​

Set-Location C:\works\abulafium
git status -sb
git pull --ff-only
# Obsidian에서 garden 문서 수정
git status --short
# 변경을 확인한 뒤 필요한 파일만 stage
git add garden/blog/tech-notes/example.md
git commit -m "docs: add technical note"
git push origin main

Obsidian Git 플러그인에서도 동등한 Commit·Push가 가능하다. Vault 내 변경 파일로 작업 범위를 제한하는 옵션을 켰더라도 Git 저장소 기록의 루트는 상위 폴더이며 Pull은 전체 저장소에 영향을 줄 수 있다.

7. Syncthing을 함께 사용하는 경우: 중요한 운영 규칙​

garden/은 Syncthing으로 복제하지만 .git/은 복제되지 않는다. 각 기기의 Git 인덱스와 브랜치 상태는 서로 다를 수 있다. 한 기기에서 Push하고 다른 기기가 같은 파일을 자동 동기화한 경우, 두 번째 기기의 Git에서는 원격 히스토리와 로컬 작업 파일이 어긋날 수 있다.

  • 동기화 중 자동 git pull --rebase, 자동 Commit/Push를 여러 PC에서 동시에 돌리지 않는다.
  • 가급적 한 기기를 출판 담당으로 정해 그 장치에서 Git 상태를 점검하고 Push한다.
  • 다른 기기에서 Git Pull 전 git status -sb를 확인한다. 미Commit 파일이 있다면 작업을 중단하고 원인을 확인한다.
  • git reset --hard, git clean -fd, 강제 Push를 동기화 문제의 즉석 해결책으로 쓰지 않는다.

[확인 필요] 실제 운영의 단일 출판 담당 기기는 아직 확정되지 않았다. 위 정책은 공개 가이드의 권장 운영 규칙이지 모두 실증 완료된 자동화가 아니다.

검증​

git rev-parse --show-toplevel
git status -sb
git check-ignore -v garden/.obsidian/workspace.json

첫 명령의 출력은 C:/works/abulafium에 해당해야 한다. 세 번째는 파일이 존재한다면 .gitignore 규칙을 보여야 한다. 비공개 inbox/ 파일이 사이트에 공개되지 않는지는 3·4편에서 따로 검사한다.