시작하기

시작하기에 앞서

Dojang은 크로스플랫폼 닷파일 관리자입니다. 닷파일이란 POSIX 계열 플랫폼에서 프로그램들이 마침표로 시작하는 설정 파일을 홈 디렉터리에 두기에 생긴 말이지만, 여기서는 닷파일을 다양한 형태의 설정 파일들을 일컫는 말로 사용합니다. 예를 들어, ~/.vimrc나 ~\AppData\Roaming\alacritty\alacritty.toml 모두 Dojang이 다루는 대상입니다.

Dojang은 설정 파일의 기기 간 동기화를 제공하지 않으며, 앞으로도 제공할 계획이 없습니다. 대신, 사용자가 직접 저장소를 Git이나 Mercurial 같은 형상 관리 시스템으로 관리하거나, Dropbox나 iCloud 같은 클라우드 저장소를 사용하여 기기 간 동기화를 구현할 수 있습니다.

또한, 명령행 프로그램이기 때문에 기본적인 터미널 사용법을 알고 있어야 합니다. 그래픽 사용자 인터페이스는 제공하지 않으며, 앞으로도 제공할 계획이 없습니다.

설치

검증된 릴리스 설치 스크립트, 패키지 관리자, Stack 중 하나로 Dojang을 설치할 수 있습니다. 지원하는 방법은 설치 문서를 참고하세요.

설치가 완료되면 dojang 명령을 사용할 수 있습니다. dojang --help 명령으로 사용법을 확인할 수 있습니다.

기본 개념

Dojang은 기기에 실제로 적용되는 대상 설정 파일들과, 여러 기기에서 쓸 수 있도록 중립적으로 구성한 원본 설정 파일들을 구분합니다. 후자를 모아두는 디렉터리를 Dojang에서는 저장소(repository)라고 부릅니다.

저장소에는 원본 설정 파일이 기기의 어느 위치로 복사해야 하는지, 운영체제 등의 환경에 따라 어느 파일과 디렉터리가 선택되어야 하는지 등을 기술하는 선언 파일이 있습니다. 선언 파일은 일반적으로 dojang.toml이라는 이름으로 저장소의 최상위에 둡니다.

원본 설정 파일들을 기기에 실제로 동기화하여 적용하는 것을 적용이라고 부르고, 반대로 기기에 적용되고 있는 대상 설정 파일을 고쳤을 때 이를 원본 설정 파일에 동기화하는 것을 반영이라고 부릅니다. 적용과 반영은 dojang 명령을 통해 수행할 수 있습니다.

저장소 초기화

저장소는 한 번 잘 만들어 두면, 이를 앞으로 여러분의 여러 기기에서 모두 사용하게 됩니다. 따라서, 저장소 초기화는 처음 한 번만 하는 일입니다.

저장소를 초기화하려면 우선 빈 디렉터리가 필요합니다.

$ mkdir my-dotfiles/
$ cd my-dotfiles/

디렉터리 이름은 자유롭게 지어도 괜찮습니다. 빈 디렉터리 안에서 dojang init 명령을 실행하면 저장소가 초기화되며 선언 파일이 만들어집니다.

$ dojang init

선언 파일을 만들려면 기존 항목을 대체하지 않는 원자적 rename을 지원하는 파일 시스템이 필요합니다. 저장소 파일 시스템이 이를 지원하지 않으면 동시에 만들어진 선언 파일을 교체하는 위험을 감수하는 대신 dojang init이 파일 쓰기 오류로 중단됩니다. 저장소를 이를 지원하는 로컬 파일 시스템으로 옮긴 뒤 다시 실행하세요.

여러분이 쓰는 기기들의 종류를 물으면 쓰는 모든 종류를 선택하면 됩니다.

Note

Windows에서는 아직 dojang init이 인터랙티브 모드를 지원하지 않습니다. 이 문제는 추후 해결될 예정입니다 (이슈 #4 참고). 그 전까지는, 명령행 옵션을 통해 기기 종류 선택을 할 수 있습니다. dojang init --help를 통해 어떤 옵션들이 있는지 먼저 확인하세요. 예를 들어, Windows PC와 Intel Mac을 모두 쓴다면 다음과 같이 입력하면 됩니다.

> dojang init --win64 --intel-mac

이제 선언 파일을 열어서 원하는 대로 수정할 수 있습니다. 선언 파일에 대한 자세한 설명은 선언 문서를 참고하세요.

저장소가 이미 다른 머신이나 아카이브에 있다면 dojang init --from을 사용하세요. 로컬 및 설정된 외부 전송 방식은 부트스트랩 안내를 참고하세요.

상황 파악

저장소를 초기화하고 나면, dojang status 명령을 통해 현재 상황을 확인할 수 있습니다. 이 명령은 현재 기기의 설정 파일들과 저장소 내 설정 파일들을 비교하여, 어떤 설정 파일들이 적용되고 있는지, 어떤 원본 설정 파일들이 적용되어야 하는지 등을 보여줍니다.

그렇지만 대상 디렉터리에 무관한 파일이 너무 많아 압도될 수도 있습니다. 그리고 파일이 너무 많을 경우 dojang status 명령이 느려지기도 합니다. 이럴 때는 ignores 구획에 무시할 파일들을 지정해 주면 됩니다. 예를 들어, 아래 예시는 홈 디렉터리 안에 있는 Documents 디렉터리를 무시하도록 지정한 것입니다.

[ignores]
HOME = ["Documents"]

자세한 내용은 무관한 파일 무시 문서를 참고하세요.

경로 지정

경로 지정은 환경에 따라 설정 파일들을 다른 위치로 복사하는 것을 말합니다. 예를 들어, 홈 디렉터리의 위치는 모든 운영체제에서 다르기 때문에, 홈 디렉터리에 있는 설정 파일들을 각 운영체제에 맞게 다른 위치로 복사해야 합니다.

선언 파일의 내용 중 가장 중요한 것이 바로 이 경로 지정이라고 해도 과언이 아닙니다. 경로 규칙은 선언 파일 내 dirs 및 files 구획에 기술합니다. dojang init 명령을 통해 저장소를 초기화하면, 이미 선언 파일 내에 기본적인 경로 규칙이 기술되어 있을 것입니다. 예를 들어 다음은 홈 디렉터리에 위치한 설정 파일들을 위한 경로 규칙입니다.

[dirs.HOME]
posix = "$HOME"
windows = "$UserProfile"

HOME은 경로 규칙 이름으로, 저장소 내 *HOME/*이라는 디렉터리에 들어있는 설정 파일들이 원본이 됩니다. 경로 규칙 이름은 얼마든지 다른 이름이 될 수 있습니다.

posix와 windows는 모니커로, 마찬가지로 선언 파일 내의 monikers 구획에서 정의합니다. 모니커 이름은 posix나 windows 외에 다르게 정해도 상관 없습니다. 각 모니커는 환경에 대한 조건을 가리키는데, 이를테면 posix 모니커는 아래와 같이 정의될 수 있습니다.

[monikers.posix]
os = ["linux", "macos"]  # Linux 또는 macOS

따라서, posix는 Linux 또는 macOS인 경우를 가리킵니다. posix = "$HOME"이라는 경로 규칙은 Linux 또는 macOS인 경우 환경 변수 HOME이 가리키는 경로로 HOME/ 디렉터리 안쪽의 설정 파일들을 복사하라는 뜻이 됩니다. 마찬가지로, windows = "$UserProfile"은 Windows인 경우 환경 변수 UserProfile이 가리키는 경로로 HOME/ 디렉터리 안쪽의 설정 파일들을 복사하라는 뜻이 됩니다.

자세한 내용은 경로 지정 문서를 참고하세요.

기존 설정 파일 가져오기

기존에 사용하던 설정 파일들을 저장소에 추가해야 합니다. 여기서는 ~/.inputrc 파일을 예시로 들겠습니다.

쓰던 설정 파일을 그대로 복사해서 저장소에 넣어도 되지만, 실수에 대한 안전 장치가 있는 dojang reflect 명령을 활용하도록 합시다. 특히, dojang reflect는 기기에 설치된 설정 파일이 바뀐 경우에 이를 저장소에 반영할 때도 쓸 수 있습니다.

$ dojang reflect ~/.inputrc

만약 ~/.inputrc 파일이 무시 목록에 들어가 있다면, 아래처럼 오류가 뜰 수도 있습니다.

$ dojang reflect ~/.inputrc
Error: File /home/USER/.bash_history is ignored due to pattern "*" (route name: HOME).
Hint: You can reflect it anyway by enforcing it using -f/--force option.

이럴 때는 -f 옵션을 사용하여 강제로 반영할 수 있습니다.

변경된 모든 파일 반영하기

dojang reflect 명령을 인자 없이 실행하면 변경된 모든 파일을 한 번에 반영할 수 있습니다. 이는 기기에서 여러 설정 파일을 수정한 후 모두 저장소에 동기화하고 싶을 때 유용합니다.

$ dojang reflect
Found 3 changed file(s):
  /home/user/.inputrc
  /home/user/.vimrc
  /home/user/.bashrc
Reflect all changed files? [y/N]

명령은 변경된 파일 목록을 보여주고 진행하기 전에 확인을 요청합니다. 확인 프롬프트를 건너뛰려면 --all (-a) 플래그를 사용하세요.

$ dojang reflect --all

기본적으로 무시 패턴에 해당하는 파일은 경고와 함께 건너뜁니다. 포함하려면 --force (-f)를 사용하세요.

등록되지 않은 파일 반영하기

대상 디렉터리에 저장소에서 아직 추적하지 않는 새 파일이 있다면, --include-unregistered (-u) 플래그를 사용하여 포함할 수 있습니다.

$ dojang reflect --include-unregistered

등록되지 않은 파일에 여러 경로 규칙이 일치할 수 있는 경우, Dojang은 어떤 경로 규칙을 사용할지 선택하도록 프롬프트를 표시합니다.

설정 파일 편집

Dojang이 이미 관리하고 있는 설정 파일을 편집하고 싶을 때는 dojang edit 명령을 사용할 수 있습니다. 이 명령은 원본 파일을 편집기에서 열고, 저장하고 닫은 후에 자동으로 변경 사항을 적용합니다.

$ dojang edit ~/.inputrc

dojang edit 명령은 대상 파일(이 경우 ~/.inputrc)에 해당하는 원본 파일을 찾아 편집기에서 열고, 편집을 마친 후 dojang apply를 실행합니다.

기본적으로 편집기는 다음 순서에 따라 결정됩니다.

--editor (-E) 옵션
$VISUAL 환경 변수
$EDITOR 환경 변수
플랫폼 기본값 (Windows에서는 notepad, POSIX에서는 vi)

자동으로 적용하지 않으려면 --no-apply (-n) 옵션을 사용할 수 있습니다.

Note

dojang edit 명령은 Dojang이 저장소 경로를 ~/.dojang 파일에 기억하기 때문에 어느 디렉터리에서나 동작합니다. 이 파일은 dojang apply를 실행할 때 자동으로 생성됩니다.

변경된 모든 파일 편집하기

dojang reflect와 마찬가지로, dojang edit 명령을 인자 없이 실행하면 변경된 모든 원본 파일을 한 번에 편집할 수 있습니다.

$ dojang edit
Found 2 changed file(s):
  HOME/.inputrc
  HOME/.vimrc
Edit all changed source files? [y/N]

확인 프롬프트를 건너뛰려면 --all (-a) 플래그를 사용하세요. 파일을 한 번에 모두 열지 않고 하나씩 편집하려면 --sequential (-s) 플래그를 사용하세요.

edit으로 새 설정 파일 만들기

dojang edit을 사용하여 새 설정 파일을 만들 수도 있습니다. 아직 존재하지 않는 대상 경로를 지정하면, Dojang이 빈 원본 파일을 만들고 편집기에서 엽니다.

$ dojang edit ~/.my-new-config
Creating new source file: HOME/.my-new-config
Opening HOME/.my-new-config in vi...

대상 경로에 여러 경로 규칙이 일치할 수 있는 경우, Dojang은 어떤 경로 규칙을 사용할지 선택하도록 프롬프트를 표시합니다. 편집기를 저장하고 닫으면, dojang apply가 새 파일을 대상 위치로 복사합니다.

머신 상태

Dojang은 전체 중간 스냅샷을 저장소 밖의 플랫폼별 사용자 데이터 디렉터리에 보관합니다. 새 저장소에는 dojang init을 실행할 때 안정적인 repository-id가 생기므로 .gitignore 항목을 자동 생성할 필요가 없습니다.

이전 Dojang 릴리스에서 만든 저장소에는 작업 트리 안에 .dojang/ 디렉터리가 남아 있을 수 있습니다. dojang migrate를 실행하면 스냅샷을 복사하고 검증한 뒤 기존 디렉터리를 제거합니다. 플랫폼별 경로, 모의 실행 절차, 덮어쓰기 동작, 복구 방법은 머신 상태 문서를 참고하세요.

성공한 적용과 반영 작업은 관리한 대상도 기록합니다. 선언 파일 변경으로 예전 대상이 고아 레코드가 되면 dojang status가 그 이유와 변경 없음·수정됨·사라짐 상태를 표시합니다. 대상 파일을 삭제하지 않고 선택한 고아 레코드만 버리려면 dojang unmanage를 사용하세요. 원본과 대상 파일을 모두 보존하면서 이 저장소의 머신별 로컬 상태를 제거하려면 dojang forget을 사용하세요. 안전 규칙과 --force가 필요한 경우는 머신 상태 문서를 참고하세요.

새 설정 파일 추가

아예 새로운 설정 파일을 추가할 때는 두 가지 방법이 있습니다.

dojang edit을 대상 경로와 함께 사용 (edit으로 새 설정 파일 만들기 참고)
저장소에 직접 원본 설정 파일을 만들어 넣기

저장소에 직접 파일을 만든 경우, 저장소에서 대상 디렉터리로 복사해야 하므로 dojang reflect 대신 dojang apply 명령을 사용해야 합니다.

~/.my-new-config에 위치하게 될 새 설정 파일을 추가한다고 가정합시다. 저장소에 HOME/.my-new-config 파일을 만들고, 원본 설정 파일을 작성합니다. 그리고 dojang status 명령으로 상황을 확인해 봅니다. 결과 내에 아래와 같은 줄이 보여야 합니다.

Source ST Destination DT File
────── ── ─────────── ── ──────────────────────────────────────────
                            (생략됨…)
added  F  unchanged   -  .my-new-config
                            (생략됨…)

해당 줄은 순서대로 다음과 같은 의미를 지닙니다.

added: 원본 설정 파일이 저장소에 추가됐고, 아직 적용된 적 없다.
F: 원본 설정 파일이 (디렉터리나 심볼릭 링크가 아닌) 일반 파일이다.
unchanged: 대상 디렉터리에 있는 짝은 변경되거나 추가되지 않았다.
-: 대상 디렉터리에 있는 짝은 아직 없다.

현재 상황을 확인했으니, 이제 dojang apply 명령을 통해 적용해 봅시다. 이 명령은 파일 경로를 인자로 받아 지정된 파일만 복사하는 dojang reflect와 달리 저장소에 있는 모든 파일 중 대상 디렉터리에 아직 없거나 변경이 필요한 파일들을 복사합니다.

새 기기에 적용

변경이 필요한 모든 파일을 복사하는 dojang apply 명령은, 그 동작 덕분에 새 기기에 설정 파일들을 한 번에 적용할 때도 쓸 수 있습니다. 예를 들어 Git에 저장소를 올려두고, 새 기기에서 저장소를 클론한 후 dojang apply 명령을 실행하면 됩니다.