Emacs 도움말

이 문서는 Emacs를 처음 쓰거나, 기존 편집기 대신 Emacs에서 문서와 코드를 다루려는 사용자를 위한 공개 도움말이다.

환경마다 달라지는 값은 모두 예시 경로와 예시 이름으로 표시한다.

Emacs 설치와 설정에 필요한 실행 파일은 공용 자료로 하나씩 제공한다. 각 파일을 따로 내려받아 같은 폴더에 둔다.

예시 파일을 실제 ~/.emacs.d/init.el 로 사용할 때는 파일 상단의 User settings 블록을 먼저 자기 환경에 맞게 바꾼다.

Emacs는 다음 작업을 한곳에서 처리할 수 있는 편집기다.

• 파일과 프로젝트 탐색
• 검색과 이동
• 문서 작성
• 코드 편집과 자동완성
• Git 작업
• 터미널 실행
• Org 문서 작성과 출판
• 외부 도구 연동

실제 설치된 패키지와 단축키는 각 사용자의 설정에 따라 다를 수 있다. 이 문서는 일반적으로 많이 쓰는 구성과 대표 단축키를 기준으로 설명한다.

Emacs 단축키 표기에서 C- 는 Ctrl 키를, M- 는 Alt 또는 Meta 키를 뜻한다.

명령 입력 도중 빠져나오고 싶으면 먼저 C-g 를 누른다.

복사와 붙여넣기 기본 흐름:

1. C-SPC 로 선택을 시작한다.
2. 방향키나 이동 키로 영역을 고른다.
3. M-w 로 복사하거나 C-w 로 잘라낸다.
4. 붙여넣을 위치에서 C-y 를 누른다.

공개 예시 init.el 은 Emacs 내부 입력기를 korean-hangul 로 설정하고, C-\ 키로 한글 입력과 영문 입력을 전환한다.

OS의 한영 키, fcitx, ibus, macOS 입력 소스처럼 운영체제 입력기를 그대로 써도 된다. 다만 운영체제 입력기를 쓰면 Emacs 밖의 앱과 입력 상태가 함께 바뀌고, C-\ 를 쓰면 Emacs 안에서만 입력 상태가 바뀐다.

전환 키를 바꾸고 싶으면 ~/.emacs.d/init.el 상단의 example-input-toggle-key 값을 바꾼다. Emacs Lisp 문자열에서는 백슬래시를 한 번 더 적기 때문에, 실제 설정 파일에는 "C-\\" 처럼 쓴다.

(setq example-default-input-method "korean-hangul"
      example-input-toggle-key "C-\\")

어떤 키가 무슨 일을 하는지 모를 때는 C-h k 를 누른 뒤 확인할 키를 입력한다.

Emacs에서는 파일을 열면 그 내용이 버퍼에 표시된다. 버퍼는 파일일 수도 있고, 명령 결과나 도움말 화면일 수도 있다.

예시 파일 경로:

~/documents/example.org
/path/to/project/README.md
/path/to/project/src/example.py

프로젝트 전체 검색은 사용 중인 설정에 따라 consult-ripgrep, projectile-ripgrep, grep 같은 명령을 사용할 수 있다.

시스템 파일을 편집해야 할 때는 sudo emacs 로 Emacs 전체를 관리자 권한으로 실행하기보다, 일반 Emacs에서 TRAMP sudo 경로로 필요한 파일만 연다.

/sudo::/path/to/system-file

예:

/sudo::/etc/example/example.conf
/sudo::/etc/example/example.service

이 방식은 현재 사용자 Emacs 설정을 유지하면서 저장할 때만 관리자 권한을 사용한다.

프로젝트 관리 패키지를 쓰면 현재 프로젝트 안에서 파일 찾기, 검색, 명령 실행을 빠르게 할 수 있다.

파일 트리 패키지를 사용하는 경우 다음과 같은 키를 둘 수 있다.

Dired는 Emacs 안에서 디렉터리를 파일 관리자처럼 다루는 기본 기능이다.

삭제나 이동 명령은 실제 파일에 영향을 주므로 대상 파일을 확인한 뒤 실행한다.

자동완성은 사용하는 설정에 따라 corfu, company, completion-at-point 등으로 제공될 수 있다.

일반적인 흐름:

• 글자를 입력하면 자동완성 후보가 뜬다.
• TAB 또는 방향키로 후보를 고른다.
• RET 로 후보를 삽입한다.

스니펫 패키지를 사용하는 경우 스니펫 이름을 입력한 뒤 TAB 으로 템플릿을 펼칠 수 있다.

Python 개발에는 LSP 서버와 포맷터를 함께 쓰면 편하다.

대표 LSP 서버:

pip install basedpyright

또는:

pip install pyright

대표 포맷터:

pip install ruff

자주 쓰는 기능:

프로젝트 명령 예시는 환경에 맞게 경로를 바꿔 실행한다.

cd /path/to/project
python -m pip install -r requirements.txt
python manage.py check
python manage.py test

Git 작업은 magit 같은 Emacs Git 패키지로 처리할 수 있다.

GitHub PR이나 Issue 연동은 forge 같은 패키지를 사용할 수 있다. 처음 사용할 때는 각 서비스의 인증 설정이 필요하다.

Emacs 안에서 터미널을 열면 편집 중인 프로젝트 위치에서 명령을 바로 실행할 수 있다.

명령 예시:

cd /path/to/project
make test
python -m pytest

Emacs에서는 설정에 따라 대화형 AI, 코드 보조, CLI 기반 코드 도구를 연동할 수 있다.

환경변수나 API 키가 필요한 도구는 실제 값을 문서에 쓰지 않는다. 쉘이나 운영체제의 비밀값 관리 방식에 등록하고, 공개 문서에는 다음처럼 예시만 둔다.

export EXAMPLE_API_KEY="replace-with-your-secret"

대화형 AI 패키지 예시:

CLI 기반 코드 도구 예시:

실행 파일 경로가 필요한 경우에는 설정 파일에 예시 경로를 넣고, 각자 환경에 맞게 바꾼다.

(setq example-cli-command "/path/to/example-cli")

코드 제안 도구는 별도 설치와 로그인이 필요할 수 있다. 사용하는 서비스의 공식 안내에 따라 설치하고, 인증 정보는 공개 문서나 저장소에 남기지 않는다.

예시 명령:

M-x example-tool-install
M-x example-tool-login
M-x example-tool-diagnose

설치 후에는 주로 프로그래밍 모드나 문서 작성 모드에서 제안이 표시된다. 제안 수락 키는 각 패키지 설정을 확인한다.

Org는 메모, 문서, TODO, 표, 코드 블록을 함께 다룰 수 있는 Emacs 문서 형식이다. Org 문서 작성법과 주요 단축키는 별도 도움말에 정리되어 있다.

• Org 사용자 도움말

Emacs 기본 조작을 먼저 익힌 뒤 Org 문법, 제목 접기, 표, 링크, 코드 블록, Agenda, Capture가 필요할 때 위 문서를 참고한다.

PlantUML을 쓰면 텍스트로 다이어그램을 작성할 수 있다.

대표 확장자:

• .puml
• .plantuml

SVG로 내보내는 키는 설정에 따라 다르지만, plantuml-mode 에서는 보통 export 명령을 사용한다.

jar 파일 경로가 필요한 경우 예시처럼 설정하고 실제 위치로 바꾼다.

(setq plantuml-jar-path "/path/to/plantuml.jar")

Emacs를 처음 설정한 뒤에는 다음 순서로 확인한다.

1. Emacs가 오류 없이 시작되는지 확인한다.
2. 패키지 설치가 완료되는지 확인한다.
3. 파일 열기와 저장이 되는지 확인한다.
4. 프로젝트 파일 찾기와 검색이 되는지 확인한다.
5. Python 같은 개발 파일에서 자동완성과 진단이 동작하는지 확인한다.
6. Git 상태창이 열리는지 확인한다.
7. 터미널이나 compile 명령이 실행되는지 확인한다.
8. AI 도구를 쓸 경우 인증과 진단 명령을 별도로 확인한다.