안드로이드 Termux로 옵시디언 깃(Git) 완벽 연동하기

들어가는 말: 로컬 앱의 숙명, 그리고 스마트폰 깃(Git) 동기화의 벽

노션(Notion) 같은 일반적인 클라우드 기반 메모 서비스와 달리, Obsidian은 모든 데이터가 내 기기 안에 직접 마크다운 파일로 저장되는 '로컬 퍼스트(Local-first)' 프로그램입니다. 내 소중한 지식의 주권을 플랫폼에 맡기지 않고 내가 온전히 통제한다는 엄청난 장점이 있지만, 그 대가로 기기 간 문서를 최신 상태로 유지하는 '동기화(Sync)'는 오롯이 사용자가 직접 해결해야 하는 숙제가 됩니다.

공식 유료 옵시디언 싱크부터 다양한 클라우드 연동 플러그인까지 여러 가지 동기화 선택지가 존재하지만, 완벽한 버전 기록 추적과 안전한 원격 백업, 그리고 비용 없는 자유도를 원하는 파워 유저들은 단연 Git 을 선택합니다. 실제로 PC 환경에서는 터미널이든 커뮤니티 플러그인이든 눈 깜짝할 사이에 커밋과 푸시가 완료되며 더할 나위 없는 만족감을 줍니다.

하지만 이 견고한 워크플로우를 '스마트폰(안드로이드)'으로 확장하려는 순간, 전혀 예상치 못한 높은 벽과 마주하게 됩니다. 모바일 옵시디언 앱 내부에서 돌아가는 Obsidian Git 플러그인은 메모리 제한이 빡빡하고 백그라운드 작업이 제한되는 스마트폰 OS 특성상, 대용량 볼트에서 수시로 튕기거나 오류를 뿜으며 멈추기 일쑤입니다. 결국 "스마트폰에서는 깃 동기화를 포기해야 하나?"라는 깊은 회의감에 빠지게 됩니다.

이때 가장 완벽한 탈출구가 바로 안드로이드용 리눅스 터미널인 터먹스(Termux)입니다. 불안정한 앱 내부 플러그인에 의존하는 대신 스마트폰 안에 진짜 리눅스 네이티브 Git 환경을 심어두면, PC 못지않게 빠르고 에러 없는 모바일 깃 동기화 체계를 완성할 수 있습니다. 이번 1부에서는 Termux를 올바르게 설치하고, 만료 스트레스 없는 SSH 키 방식으로 내 스마트폰과 깃을 영구 연결하는 실전 세팅법을 차근차근 정리해 드리겠습니다.

1. 시작 전 필수 주의사항: 어디서 설치해야 할까?

Termux를 설치할 때 초보자가 가장 많이 하는 치명적인 실수가 있습니다. 바로 구글 플레이스토어(Play Store)에서 Termux를 검색해 설치하는 것입니다.

구글의 보안 정책 변경으로 인해 플레이스토어 버전의 Termux는 2020년 이후 공식 업데이트가 완전히 중단되었습니다. 이 버전을 설치하면 패키지 관리자(pkg나 apt)의 서버 주소가 옛날 경로로 묶여 있어, 깃은커녕 기본 프로그램 설치조차 에러를 뿜으며 실패합니다.

따라서 Termux는 반드시 오픈소스 앱스토어인 F-Droid(f-droid.org) 웹사이트나 공식 GitHub 릴리즈(GitHub Releases) 페이지에서 APK 파일을 직접 내려받아 설치하셔야 합니다. 이것만 지키셔도 세팅 과정에서 생기는 오류의 90%를 미리 방지할 수 있습니다.

Termux F-Droid 다운로드 링크: https://f-droid.org/packages/com.termux/

2. Termux 기본 세팅과 저장소 권한 연결

스마트폰 화면에서는 긴 명령어를 복사하고 붙여넣는 과정에서 줄바꿈 오류가 발생하기 쉽습니다. 따라서 모든 명령어는 모바일 화면에서 한 줄씩 복사하여 붙여넣기 편하도록 단계별로 나누어 진행하겠습니다. 도중에 진행 여부를 묻는 안내(Y/n)가 나오면 y를 누르고 엔터를 치시면 됩니다.

(1) 최신 패키지 업데이트

가장 먼저 터미널 환경을 최신 상태로 갱신해 줍니다. 아래 한 줄을 복사해 터미널에 붙여넣고 실행합니다.

pkg update && pkg upgrade -y

(2) Git 및 OpenSSH 설치

업데이트가 끝나면 깃(Git)과 보안 접속용 도구를 설치합니다.

pkg install git openssh -y

(3) 스마트폰 저장소 접근 권한 열기 (`termux-setup-storage`)

Termux는 보안상 기본적으로 스마트폰의 일반 파일에 접근할 수 없습니다. 아래 명령어를 실행해 파일 접근 권한을 열어줍니다.

termux-setup-storage

명령어를 실행하면 안드로이드 시스템 팝업으로 "Termux가 기기의 사진, 미디어, 파일에 접근하도록 허용하시겠습니까?"라는 창이 뜹니다. 반드시 '허용'을 눌러주셔야 합니다. 이제 ~/storage/shared/ 경로를 통해 내 스마트폰의 '내 파일(문서, 다운로드 폴더 등)'에 자유롭게 접근할 수 있습니다.

3. GitHub 본인 인증: 왜 토큰(PAT) 대신 'SSH 키'를 써야 할까?

스마트폰에서 GitHub에 접속할 때 많은 분들이 개인 접근 토큰(PAT)을 쓰려다 좌절합니다. 모바일 브라우저로 GitHub의 복잡한 권한 설정 화면을 확대해가며 토큰을 만들기 매우 번거로울 뿐만 아니라, 30일~90일이 지나 토큰이 만료되면 어느 날 갑자기 모바일 동기화가 먹통이 되기 때문입니다.

반면 SSH 키 방식은 스마트폰 터미널에서 명령어 한 줄로 키를 만들고, 생성된 문자열을 GitHub에 딱 한 번 등록해 두기만 하면 만료일 없이 영구적으로 비밀번호 입력 없이 자동 인증됩니다. 모바일 환경에서는 무조건 SSH 키 방식이 압도적으로 편리하고 안전합니다.

(1) 초간단 SSH 키 생성 (명령어 딱 한 줄 실행)

아래 한 줄 명령어를 복사하여 터미널에 붙여넣고 실행합니다. 뒤의 이메일(-C "...")은 깃허브에서 내 기기를 식별하기 위한 메모이므로, 본인의 GitHub 이메일을 적어주시면 됩니다. (만약 이메일 수정이 귀찮다면 -C "..." 부분을 지우고 ssh-keygen -t ed25519만 실행하셔도 무방합니다.)

ssh-keygen -t ed25519 -C "내이메일@example.com"

명령어를 실행하면 키 저장 위치와 비밀번호(Passphrase)를 묻는 질문이 3번 연속으로 나옵니다. 아무것도 입력하지 마시고 엔터(Enter)만 3번 연속으로 탁-탁-탁 치시면 비밀번호 없는 자동 로그인 키 생성이 즉시 끝납니다.

(2) 내 공개키 확인 및 복사

방금 생성된 내 스마트폰의 고유 공개키를 화면에 출력합니다.

cat ~/.ssh/id_ed25519.pub

터미널 화면에 ssh-ed25519 AAAA...로 시작하는 긴 한 줄의 텍스트가 나타납니다. 이 한 줄 전체를 스마트폰 터치로 길게 눌러 복사(Copy)합니다.

(3) GitHub 웹사이트에 내 폰 등록하기

스마트폰 브라우저로 GitHub SSH 키 등록 페이지(https://github.com/settings/ssh/new)에 접속합니다.
Title: 알아보기 쉽게 내 스마트폰 또는 Galaxy Termux라고 적습니다.
Key: 방금 복사한 ssh-ed25519 ... 텍스트를 그대로 붙여넣습니다.
초록색 Add SSH key 버튼을 누르면 스마트폰 등록이 영구적으로 완료됩니다.

(4) SSH 연결 성공 여부 즉시 확인하기 (단 1회 테스트)

키 등록이 잘 되었는지 터미널에서 아래 한 줄을 실행하여 확인합니다.

ssh -T git@github.com

처음 접속할 때는 보안 확인을 위해 Are you sure you want to continue connecting (yes/no/[fingerprint])?라는 질문이 나옵니다. 당황하지 마시고 yes를 입력하고 엔터를 누르시면 됩니다.

화면에 아래처럼 본인의 깃허브 계정명과 함께 환영 메시지가 뜨면 완벽하게 인증된 것입니다. 이제 비밀번호 없이 마음껏 깃을 쓸 수 있습니다.

Hi 내아이디! You've successfully authenticated, but GitHub does not provide shell access.

[!NOTE]
기존 토큰(PAT)을 사용하고 싶다면?
이미 PC 등에서 발급해 둔 토큰이 익숙하시다면 HTTPS 주소로 클론하신 뒤, 토큰을 비밀번호 칸에 넣고 git config --global credential.helper store를 쓰셔도 무방합니다. 다만 정기적으로 만료되어 다시 발급받아야 하므로, 모바일 기기에는 만료 없는 SSH 방식을 적극 권장합니다.

4. 스마트폰의 옵시디언 볼트 폴더 연결 및 첫 푸시 테스트

여기서 가장 중요한 핵심 원칙이 있습니다. 옵시디언 볼트 폴더는 반드시 스마트폰의 일반 공용 저장소(예: Documents 폴더)에 존재해야 한다는 점입니다. Termux 내부 전용 폴더($HOME)에 볼트를 넣어두면, 스마트폰의 옵시디언 앱에서 해당 폴더를 읽어오지 못하거나 Termux 앱을 초기화할 때 소중한 메모까지 함께 사라질 위험이 있습니다.

(1) 기존 볼트 폴더가 이미 폰에 있는 경우

스마트폰의 Documents/Obsidian 경로에 볼트가 이미 있다면, 아래 명령어로 이동합니다.

cd ~/storage/shared/Documents/Obsidian

(2) GitHub에서 새로 볼트를 클론하는 경우

기존 볼트가 폰에 없다면 문서 폴더로 이동한 뒤, SSH 주소(git@github.com:...)로 깃 클론을 수행합니다.

1단계: 문서 폴더로 이동

cd ~/storage/shared/Documents

2단계: SSH 주소로 저장소 복제 (주소는 본인 저장소의 SSH URL 입력)

git clone git@github.com:내계정/내저장소.git

(3) 첫 커밋 & 푸시 실행 (암호 없이 한 방에 통과!)

모바일 옵시디언 앱을 열어 테스트 메모를 작성하거나 수정한 뒤, Termux에서 다음 명령어를 순서대로 실행해 봅니다.

1단계: 변경 파일 전체 담기

git add .

2단계: 커밋 메시지 작성

git commit -m "Mobile sync test"

[!NOTE]
혹시 커밋할 때 "Author identity unknown" 메시지가 뜬다면?
깃(Git) 설치 후 최초 1회에 한해 커밋 작성자 확인을 요구하는 기본 안내입니다. 아래 한 줄만 복사하여 등록해 주시면 이후 다시 묻지 않습니다.
git config --global user.name "내이름" && git config --global user.email "내이메일@example.com"

3단계: GitHub로 전송

git push

비밀번호나 토큰을 묻는 번거로운 과정 없이, 방금 등록한 SSH 키를 통해 GitHub로 시원하게 푸시가 완료되는 것을 확인하실 수 있습니다. 모바일 옵시디언 플러그인이 버벅거리며 멈추던 답답함이 단번에 해소되는 순간입니다.

5. 실전 꿀팁: 명령어 한 줄로 끝내는 원클릭 단축 스크립트

스마트폰 가상 키보드로 매번 git add, commit, push를 일일이 타이핑하는 것은 매우 번거롭습니다. 단 한 번의 단축 명령어로 최신 글을 당겨오고(pull) 업로드(push)까지 끝내도록 세팅해 줍니다.

1단계: 단축 명령어(gsync) 등록

아래 한 줄을 복사하여 터미널에 그대로 붙여넣습니다. (폴더 경로는 본인 볼트 경로에 맞게 지정됩니다.)

echo "alias gsync='cd ~/storage/shared/Documents/Obsidian && git pull && git add . && git commit -m \"Mobile auto sync\" && git push'" >> ~/.bashrc

2단계: 설정 즉시 적용

source ~/.bashrc

이제 스마트폰 터미널을 열고 gsync라고 딱 한 단어만 치고 엔터를 누르면, 최신 글 당겨오기(pull)부터 작성한 글 전체 커밋과 푸시(push)까지 3초 만에 자동으로 완료됩니다.

맺음말: 완벽한 모바일 터미널 환경을 기반으로

이제 스마트폰은 단순히 문서를 소비하거나 가볍게 메모하는 도구를 넘어, PC와 동일한 신뢰성을 지닌 네이티브 깃 작업대로 탈바꿈했습니다. 토큰 만료나 동기화 오류 걱정 없이 언제 어디서나 안심하고 모바일 안드로이드 환경에서 옵시디언에 긴 글을 집필할 수 있는 탄탄한 뼈대가 마련된 셈입니다.