Intro

Emacs is… what you want it to be.

This is a collection of files for configuration of Emacs.

This Emacs flavor is intended to be well-organized, documented, good-looking, and behaving according to modern expectations. A priority is given to the usage of the built-in packages, but without usability sacrifice.

This configuration tested to work well on MacOS, Linux, and Windows. The same time, it provides MacOS-specific treats.

See also this list of other configurations and starter-kits for a source of inspiration to configure your own Emacs.

Playing With This Repo

Install

1. Download this configuration:
   • Backup contents of the directory ~/.emacs.d, if you have the one.
   • Do one of the following:
     • Download one of the releases, unpack it, and rename to ~/.emacs.d~.
       • Earlier versions might become a good starting point for a newbie.
     • $ git clone git@gitlab.com:yugaego/emacs-config.git ~/.emacs.d
     • $ git clone git@github.com:yugaego/emacs-config.git ~/.emacs.d
2. Install configured packages:
   • $ cd ~/.emacs.d
   • $ emacs --script install-packages.el

Structure

init.el

Main configuration file.

early-init.el

Configurations loaded very early in the startup process.

custom.el

Emacs Customization writes to this file. Read-only.

configs/init-*.el

Auto-loaded configuration files extracted from init.el for better readability.

install-packages.el

Install configured packages after cloning (on new devices).

local-pre-init.el

Private information can be stored in this file.
This optional file is excluded from the repository and loaded only if present in the file system.

examples/local-pre-init.el

Example local configurations.

local-post-init.el

One more git-ignored optional file, loaded after configs/init-*.el files load.

CHANGELOG.org

Lists notable changes.

Global Custom Keybindings

C-x C-b

M-x ibuffer-other-window

C-c b k

M-x kill-some-buffers

C-c b r

M-x yet-rotate-windows-buffers

C-c c /

M-x company-other-backend

C-c c f

M-x company-files

C-c c d

M-x company-dabbrev

C-c c c

M-x company-capf

C-z

ctl-x-map (for split keyboard usability)

M-<delete>

M-x kill-word

M-s M-s

M-x isearch-forward-thing-at-point

C-c b w

M-x whitespaces-mode (toggle)

C-c d

M-x yet-duplicate-current-line-or-region (calls function duplicate-dwim since Emacs 29.1)

C-c f r

M-x rename-visited-file (since Emacs 29.1)

C-c s-f

M-x yet-mac-open-finder-current-file

C-c s-d

M-x yet-mac-open-dictionary-current-word

C-c s-g

M-x yet-browse-grammarly

C-c l s

M-x eglot

C-c i s

M-x imenu-list-smart-toggle (toggle)

C-c t s

M-x yet-start-term

C-c b i

M-x display-fill-column-indicator-mode

C-c b l

M-x scroll-lock-mode

C-c b s

M-x yet-toggle-window-split (toggle)

C-c e r

M-x restart-emacs

C-c e q

M-x M-x yet-kill-emacs-reset-desktop

Getting Started with Emacs on Mac OS

With the listed types of installation you get a “pure” Emacs that behaves similarly to other OS applications.

For example, on Mac OS you may:

• quit Emacs with Cmd-q or hide Emacs with Cmd-h,
• perform well-known operations with Cmd-c, Cmd-v, Cmd-a, Cmd-x,
• navigate text with the arrows.

Install

Pre-compiled

The first two approaches install Emacs.app to /Applications/. Consult documentation of the listed providers for more information.

DMG file

Download from EmacsForMacOSX, install as any other application.

Homebrew

$ brew cask install emacs

• Upgrade: $ brew upgrade homebrew/cask/emacs
• Info: $ brew cask info homebrew/cask/emacs

Macports

• $ sudo port install emacs-app
  • Installs Emacs.app to /Applications/MacPorts/
  • Current default variants +nativecomp and +rsvg are fine choice.
  • Pre-install mailutils +gnutls if you plan to retrieve e-mails in Emacs.
• $ sudo port install emacs
  • Installs /opt/local/bin/emacs
  • Current default variant +nativecomp is a fine choice.

More on Mac OS installers.

And by the way, Emacs usage is smooth with Dvorak layout and a split keyboard.
I personally use Kinesis Advantage and feel comfortable having a set of modifier keys under each of my hands.

From source

Compiling from source is simple enough.

• $ git clone git://git.savannah.gnu.org/emacs.git YOUR-DIR
• $ cd YOUR-DIR
• $ ./autogen.sh
  • This is an optional step.
  • Only needed for the fresh clone of the code without the configure script.
  • On this step the configure script and some related files are generated.
• $ ./configure
  • For example, with additional options:
    • $ ./configure -C --with-json --with-native-compilation --with-mailutils --with-imagemagick.
  • $ ./configure --help lists all the available options.
• $ make
  • Compiles emacs into YOUR-DIR/src/.
  • Launch install emacs from CLI.
• $ make install
  • This is an optional step.
  • Adds Emacs.app to YOUR-DIR/nextstep/.
  • Feel free to move or symlink the created app.

For more details consult the files YOUR-DIR/INSTALL, YOUR-DIR/nextstep/INSTALL, and YOUR-DIR/README.

What’s Next

As the next steps, I highly recommend:

• following the Emacs tutorial (Ctrl-h t),
• then reading the Emacs manual (Ctrl-h r).

EmacsWiki is one of the most helpful resource online for the beginners.

Experiment while reading documentation. For example, in my case, it took two months to read the manual and switch to feeling comfortable with Emacs.

The result of that period was a basic configuration file and this key bindings cheat sheet.

Contributing

I hope you find this repository helpful. If you see a way to improve it, feel free to submit changes or ideas. This project attempts to follow the KISS principle, so reporting any unclarity is welcome too.

Happy Emacsing!