Centaur Emacs: a full Emacs configuration you install by cloning it

Cloning Centaur Emacs straight into the directory Emacs already reads

Installation is one clone, and the target directory is not arbitrary. Emacs looks for `~/.emacs.d` on every start, so replacing that directory replaces the configuration rather than adding to it:

# Backup your existing configuration
mv ~/.emacs.d ~/.emacs.d.bak

# Clone the repository
git clone --depth 1 https://github.com/seagle0128/.emacs.d.git ~/.emacs.d

The `--depth 1` flag matters here. This directory is meant to be replaced by a fresh clone rather than merged into, so a shallow checkout avoids carrying a full history into a folder you are likely to delete and re-clone several times.

Linux users who keep configuration in an XDG location get a second path, and it has a hard precondition rather than a preference:

# Ensure ~/.emacs.d, ~/.emacs and ~/.emacs.el don't exist
git clone --depth 1 https://github.com/seagle0128/.emacs.d.git $XDG_CONFIG_HOME/emacs

If `~/.emacs.d`, `~/.emacs` or `~/.emacs.el` still exist, Emacs finds the old configuration first and the clone appears to do nothing. That failure is silent, which is the main thing to know before starting. A ZIP archive is offered as an alternative to git for anyone who would rather extract a file than run a clone.

Reading the top-level tree as a startup sequence

The tree is short and ordered like a boot path. `early-init.el` is the earliest hook Emacs offers, before package loading, and `init.el` is the main entry point that does the real work. `init-mini.el` sits beside them as a deliberately reduced configuration, and the README points at it as the troubleshooting entry: `emacs -Q -l ~/.emacs.d/init-mini.el` bypasses your own settings and loads almost nothing.

Two directories carry most of the weight. `lisp/` holds the project's own Elisp, which the README calls its core library, so this is not a manifest of third-party packages alone. `site-lisp/` is present as a separate home for code that belongs to a particular site rather than to the distribution. `eshell/` is a single feature split into its own directory, which matches the shell emulation the README lists among the extras rather than treating it as core.

The rest is infrastructure: `.github/` for the CI workflow, `Dockerfile/` for the container build, `banner.txt` and `_config.yml` for the GitHub Pages site at seagle0128.github.io, and `AGENTS.md` for instructions aimed at coding agents working inside the repository. One detail to watch: the README's manual configuration section tells you to edit `custom.el`, while the tree lists `custom-example.el`. On a fresh clone the example file is what you have, and `custom.el` is the file Emacs writes when you save through the Customize interface.

First startup is where the package list becomes real

After cloning, you start Emacs and wait. There is no install step in the traditional sense, because packages are downloaded and compiled during that first startup, and the README warns twice about it: first startup may take a while, and if it stalls you should check your network or set a proxy rather than assume the configuration is broken.

The package surface is where most of the advertised value lives, and the README is specific about the categories. Out of the box it lists quick fuzzy search for files and text, auto completion, Fly for syntax and spell checking, Git integration, project and workspace integration, a Pomodoro timer, MPD support for a music player daemon, and Docker tooling. The language coverage is enumerated rather than promised: C, C++, Objective-C, C#, Java, Python, Ruby, Perl, PHP, Shell, PowerShell, Batch, JavaScript, TypeScript, JSON, YAML, HTML, CSS, XML, Go, Swift, Rust, Dart and Elixir, followed by an ellipsis.

Chinese input support gets its own line rather than being buried: a Chinese calendar, Youdao dictionary lookup, Google translation, and pinyin search. That is a narrower signal about who the project is for than the language list suggests, and it is worth knowing before you install.

Two variables control the first minutes of your new configuration:

;; Set user information
(setq centaur-full-name "Your Name")           ; Your full name
(setq centaur-mail-address "[email protected]")   ; Your email address

;; Proxy settings
(setq centaur-proxy "127.0.0.1:1087")          ; HTTP/HTTPS proxy
(setq centaur-socks-proxy "127.0.0.1:1086")    ; SOCKS proxy

There is a third that matters more than the other two on a first run. `(setq centaur-logo nil)` turns off the startup logo, which is the splash screen shown while packages compile. If you suspect the configuration has frozen, disabling it tells you whether the delay is the logo or the work behind it.

Updating is split into four commands rather than one

Centaur Emacs separates updating the configuration from updating the packages, and that split is the most defensible design decision in the repository. A single `git pull` would bring in new configuration code that has not been checked against your machine, so the project gives you a choice instead:

;; Update everything: configurations and packages
M-x centaur-update

;; Update only Emacs configurations
M-x centaur-update-config

;; Update only packages
M-x centaur-update-packages

A fifth command, `M-x centaur-update-dotfiles`, covers the separate dotfiles repository the README recommends, and `M-x centaur-update-all` chains configurations, packages and dotfiles together. `M-x centaur-update-dotfiles` is inert unless you installed that companion setup.

The narrower commands are the ones worth knowing. When a package upgrade breaks a binding, `M-x centaur-update-config` lets you take new configuration without touching your installed package versions, which is the cheapest way to isolate the fault. Configuration updates come from a `git pull` of this repository, and package updates come through package.el, so the two failure modes stay separable.

The alternative path is the Customize interface, which the README calls the easiest way to change settings: run `M-x customize-group`, pick the `centaur` group, edit, click Save, and restart. Saving there writes `custom.el` rather than `init.el`, which means your changes accumulate in a separate file. Keeping configuration in `init.el` by hand keeps your edits reviewable in version control.

Docker support exists, and it is a build rather than a published image

The README documents a container route in four commands, and it builds the image from the repository rather than pulling one:

# Navigate to the Dockerfile directory
cd ~/.emacs.d

# Build the Docker image
docker build -t centaur/emacs -f Dockerfile.xx .

# Run the container interactively
docker run -it centaur/emacs bash

Two things are worth noticing. The tag is `centaur/emacs`, which is a locally built name rather than a registry reference, so you build it once per machine and rebuild when the configuration changes. And the build context is the repository root with an explicit `-f Dockerfile.xx`, a name that suggests several variants exist for different Emacs versions. The README does not enumerate them, so choosing between them means reading the `Dockerfile/` directory directly.

The container is useful for exactly one thing: getting the same Emacs you have on a work machine onto something else without installing Emacs there. It is not a way to keep configuration in version control, because the container reads the same `~/.emacs.d` that the native install does. For a first startup that stalls on package downloads, this is also a poor debugging environment, since the network problem you are trying to isolate travels with you into the container.

What the release history says and where the documentation runs out

The version line is where the honest reading of this project gets interesting. Releases stopped at v8.2.1 on 2025-07-24, with v8.2.0 the day before on 2025-07-23 and v8.1.1 back on 2025-02-27 under the blunt name "The last release for 27+". Those notes are worth reading closely, because they document real breakage rather than feature lists: v8.2.0 drops Emacs 27 support, switches from `iscroll` to `ultra-scroll`, replaces vterm with eat, and ships a break change renaming `font-installed-p` to `font-available-p`.

So the tagged history says 8.2, the project floor says 28.1, and the README contradicts itself about the current release, naming 31.1 in one line and 30.1 in another. Meanwhile the last push to master was on 2026-09-26, more than a year after the newest tag. For a configuration you install by cloning, that gap is not a problem: you get master either way, and the tags mostly mark breaking changes you can consult when a binding stops working.

The README is a good index and a thin manual. It gives you the clone, the first-startup warning, the update commands, the option list and the Docker block. Everything deeper lives one hop away: the rendered site at seagle0128.github.io for screenshots and prose, the Centaur Dotfiles repository for a full system configuration, and wikiemacs.org for installing Emacs itself on your platform. The Hydra keybindings section is announced in the table of contents with a screenshot placeholder, so the actual bindings are something you learn by running `M-x describe-mode` rather than by reading ahead.

If you are weighing this against writing a configuration from scratch, the honest comparison is that a hand-built `init.el` is small, reviewable and yours, while this one is large, current and someone else's. The README's own answer to newcomers and power users alike implies you are expected to move from one to the other: install it, then edit `custom.el` until it is not Centaur Emacs any more.

Editorial conclusion

Centaur Emacs is a configuration rather than a package, which means it suits someone who wants a working Emacs today and is prepared to treat `init.el` as code they own afterwards. The trade is explicit in the repository: you get fuzzy search, flycheck, Magit, LSP and language tooling wired up in one clone, and in exchange you inherit a startup path, a package set and a set of defaults that the maintainer decides, not you. Emacs 28.1 is the floor, Windows works through Cygwin or MSYS rather than natively, and there has been no tagged release since v8.2.1 on 2025-07-24 even though the last push to master was on 2026-09-26. Start with `init-mini.el` to confirm Emacs itself is sound, then move to the full configuration and read `custom-example.el` before changing anything.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. seagle0128/.emacs.d on GitHub