Castlemacs

#+SETUPFILE: ~/code/org-themes/org-html-themes/setup/theme-readtheorg.setup #+LANGUAGE: en #+TITLE: Castlemacs: modern, minimalist Emacs for macOS ⌘

[[https://img.shields.io/github/tag/freetonik/castlemacs.svg?label=release&style=flat-square]] [[https://img.shields.io/badge/license-MIT-green.svg?style=flat-square]]

[[./screenshots/main2.png]]

---

[[#installation][Installation]] | [[CHANGELOG.org][Changelog]]

---

• Features

• Compatibility with common macOS keybindings
• Ergonomic keybindings that follow simple, sensible rules
• Easy windows management and movement
• Easy movement between points in the file and between files
• Multiple cursors, project manager, Git front end, file tree, terminal
• Handy spellchecker, built-in thesaurus and word definition lookup
• A handful of tiny, useful helper functions

• Table of Contents :PROPERTIES: :TOC: this :END:

  • [[#intro][Intro]]
  • [[#core-principles][Core principles]]
  • [[#faq][FAQ]]
  • [[#installation][Installation]]
  • [[#install-emacs][Install Emacs]] - [[#alternative-version-advanced][Alternative version (advanced)]]
  • [[#install-dependencies][Install dependencies]]
  • [[#install-castlemacs][Install Castlemacs]]
  • [[#setup-keyboard][Setup keyboard]]
  • [[#note-to-mojave-users][Note to Mojave users]]
  • [[#usage][Usage]]
  • [[#modifier-keys][Modifier keys]]
  • [[#basics][Basics]]
  • [[#navigation][Navigation]] - [[#basic-movement][Basic movement]] - [[#moving-text][Moving text]] - [[#simple-jumping-within-text][Simple jumping within text]] - [[#smart-jumping-within-buffer-and-between-buffers][Smart jumping within buffer and between buffers]]
  • [[#search-and-replace][Search and replace]]
  • [[#editing][Editing]] - [[#words-and-lines][Words and lines]] - [[#deleting-text][Deleting text]] - [[#multiple-cursors][Multiple cursors]] - [[#indentation][Indentation]] - [[#region][Region]]
  • [[#window-management][Window Management]] - [[#splitting-windows][Splitting windows]] - [[#moving-between-windows][Moving between windows]] - [[#restoring-window-configuration][Restoring window configuration]]
  • [[#project-management][Project Management]]
  • [[#git][Git]] - [[#git-gutter][Git gutter]] - [[#magit][Magit]]
  • [[#terminal-shell][Terminal (shell)]]
  • [[#file-tree-and-open-buffers][File tree and open buffers]]
  • [[#programming][Programming]] - [[#languages-and-modes][Languages and modes]] - [[#code-completion][Code completion]] - [[#emmet][Emmet]]
  • [[#spellchecking-thesaurus-definition][Spellchecking, thesaurus, definition]] - [[#spellchecking][Spellchecking]] - [[#thesaurus][Thesaurus]] - [[#word-definition][Word definition]]
  • [[#org-mode][Org mode]]
  • [[#why-this-name][Why this name?]]

• Intro

Emacs is +an extensible, customizable text editor+ a framework for creating any text editor you want. The goal of Castlemacs is to build a simple, modern and minimalist Emacs setup tailored to macOS while following these

** Core principles

1. Be beginner-friendly. Anyone should be able to start using Castlemacs just like they can start using VS Code, Sublime, etc.
2. Respect macOS. Common system-wide keybindings work as you expect.
3. Respect Emacs. Never break vanilla Emacs compatibility. Always provide a way to go "full Emacs" if user so desires.
4. No layers of complexity. No custom configuration layers, no DSL, nothing new. Simple =init.el=, packages installed and configured via =use-package=.
5. Go minimal when possible. For example, use lightweight =avy= instead of full-featured =Helm=.

• FAQ

Is Castlemacs compatible with non-macOS systems? Yes! /Nothing/ binds Castlemacs to macOS except for some conventions. As long as you have some key on your keyboard that can play a role of =Super= (e.g. =windows= key), you're good to go.

I don't know Emacs. Can I use Castlemacs or is it hard?. You don't need to know Emacs, but it will help. The goal of this project is to make a setup that is suitable for absolute beginners.

Is this similar to Spacemacs? No. Spacemacs is a big, custom distribution with additional layers on top of Emacs. Castlemacs is simply a pre-configured Emacs. You don't need to learn anything new if you know your way around Emacs.

Will Castlemacs support <something>? Probably, unless it goes against the Core Principles. Feel free to open an issue.

Does this setup work well in the terminal? It works, but it is not built for terminal use, since one of the Core Principles is to behave like a native macOS application.

Why is it called Castlemacs? See [[#why-this-name][Why this name?]]

Where do I store my private config? You can store your regular private config in =private.el=. This file will not be changed in Castlemacs, so you don't have worry about conflicts.

Why does Castlemacs uses the system clipboard separately from the kill ring? Kill ring system is powerful, but potentially confusing for newcomers. The way it is integrated with the system clipboard by default makes it even more confusing. For these reasons Castlemacs uses the system clipboard only (via the usual macOS key combinations), and keeps the kill ring system independently available to those who want it.

• Installation

** Install Emacs

Download Emacs from [[https://emacsformacosx.com/][emacsformacosx.com]]. That's it!

*** Alternative version (advanced)

The "simplest way" is the canonical Emacs distribution for macOS. However, it has a number of disadvantages:

• Due to some build options related to graphics, certain extensions like Powerline produce incorrect colors (RGB space issue)
• No emoji support (if you're into this kind of stuff)
• No sub-pixel smooth scrolling
• No native support for =org-protocol=

If these are important to you, consider installing Mitsuharu Yamamoto's port instead.

#+BEGIN_SRC sh brew tap railwaycat/emacsmacport brew install emacs-mac --with-natural-title-bar ln -s /usr/local/opt/emacs-mac/Emacs.app /Applications #+END_SRC

** Install dependencies

Castlemacs relies on [[https://github.com/BurntSushi/ripgrep][ripgrep]] to quickly search within a project. Install it:

#+BEGIN_SRC sh brew install ripgrep #+END_SRC

Castlemacs requires =aspell=, a Free and Open Source spell checker. Install it:

#+BEGIN_SRC sh brew install aspell #+END_SRC

We also need gnutls — GNU Transport Layer Security (TLS) Library:

#+BEGIN_SRC sh brew install gnutls #+END_SRC

** Install Castlemacs

Backup current Emacs config (if exists), then clone Castlemacs from Github:

#+BEGIN_SRC sh mv ~/.emacs.d ~/.emacs.d.bak git clone https://github.com/freetonik/castlemacs ~/.emacs.d #+END_SRC

Launch Emacs and wait for several minutes. On the first launch it will download and install packages. When it's done and the status line in the bottom stops outputting text, restart Emacs.

Don't worry about warning messages on the first launch, they will go away after first restart.

** Setup keyboard

I highly recommend changing Caps Lock to Control by going to System Preferences → Keyboard → Modifier Keys. This way you will have a more comfortable Control under your left pinky.

If you use Japanese Magic Keyboard, then you don't have to do anything, since =control= is in a good place already.

** Note to Mojave users

In macOS Mojave Emacs build might fail due to some changes in Xcode command line tools. Xcode command line tools must be pointed to the release version of Xcode 10 instead of the beta version. Use xcode-select to accomplish this.

• Usage

** Modifier keys

Castlemacs takes advantage of two facts:

1. =Command= key is used in macOS for all major system shortcuts, so users have muscle memory;
2. Emacs recognizes a =Super= key, but almost never uses it by default.

So, =Command= key becomes =Super=

| Name | On Mac keyboard | Emacs key | |---------+-----------------+-----------| | Super | Command ⌘ | =s= | | Meta | Left Alt ⌥ | =M= | | Control | Control ⌃ | =C= |

In this document we'll refer to keys with their common macOS names: Cmd, Alt, Ctrl.

** Basics

Basic combinations with =Command= work as expected.

| Binding | Description | Emacs default | |---------------+--------------------------+---------------| | =Escape= | Cancel current action | =C-g= | | =Cmd-z= | Undo | =c-_= | | =Cmd-Shift-z= | Redo | N/A | | =Cmd-s= | Save file | =C-x C-s= | | =Cmd-Shift-s= | Save file as | =C-x C-w= | | =Cmd-o= | Open file | =C-x C-f= | | =Cmd-a= | Select whole buffer | =C-x h= | | =Cmd-q= | Quit Emacs | =C-x C-c= | | =Cmd-Shift-p= | Open command palette | =M-x= | | =Ctrl-x c= | Open private config file | N/A | | =Ctrl-x C= | Open init config file | N/A |

** Navigation

*** Basic movement

Buttons I, J, K, L form a natural alternative to arrow keys. You can move around by holding Cmd while using these keys, without leaving the home row (press Cmd with your right thumb).

(See http://tonsky.me/blog/cursor-keys/ for some background and motivation.)

| Binding | Description | Emacs default | Alternative | |---------+-------------+---------------+-------------| | =Cmd-i= | Go up | =C-p= | Arrow UP | | =Cmd-k= | Go down | =C-n= | Arrow DOWN | | =Cmd-j= | Go left | =C-b= | Arrow LEFT | | =Cmd-l= | Go right | =C-f= | Arrow RIGHT |

*** Moving text

Hold =Alt= to move current line up or down. This is sometimes called "bubbling".

| Binding | Description | |------------+----------------| | =Alt-UP= | Move line up | | =Alt-DOWN= | Move line down |

*** Simple jumping within