Repository files navigation

Welcome toEmacs-Kick, a feature-rich Emacs configuration designedfor users familiar withVim,Neovim, andVi. With thissetup, you don't need to leave behind your favorite terminal or toolslikeyazi,starship,lazygit, andlazydocker just togive Emacs a try.

Use Emacs the same way you'd useNeovim, seamlessly integrating itinto your workflow inside terminal multiplexers liketmux orZellij, while also enjoying modern features such astreesitterandLSP, no hassle.

Emacs-Kick isn’t a full-fledged distribution but rather astarting point for building your own Emacs configuration. It’sdesigned to be especially accessible for Vim/Neovim users, letting youexplore the power of Emacs without committing to its entire ecosystem.

You can take advantage of Emacs’ features without needing to masterevery Emacs-specific workflow right away. And if you find yourselfenjoying it, you can:

• Run it in a GUI for a richer experience
• Customize and expand your configuration as much as you want
• Experiment with frameworks like Doom Emacs or Spacemacs
• Tinker with vanilla Emacs to build a setup entirely your ownOR...
• Just keep using it on TUI, it is all up to you!

WithEmacs-Kick, the goal is to empower you to explore Emacs at yourown pace. The sky's the limit! 🌟

• Emacs version>=30.1
• You can verify your installed Emacs version by running:

emacs --version

Note: floating windows on TUI are only supported from Emacs >=31 (currentdevelopment version on Emacs master branch).

On macOS,Emacs-Kick may fail to function correctly due to missing orincompatible system utilities. To avoid common issues, make sure thefollowing tools are installed via Homebrew:

brew install coreutils git

This provides:

• gls: The GNU version ofls, required by Dired to avoid errorslike:

  Listing directory failed but 'access-file' worked.

• git: macOS system usually has an older version of Git, thistypically refers to the version installed through Apple's CommandLine Tools (part of Xcode). Installing from Homebrew ensures amodern version of git is installed and will avoid problems withmagit.

1. Clone the repository:

Note: If you already have an existing Emacs configuration in~/.emacs.d, please back it up before proceeding. You can do thisby renaming the directory:

mv~/.emacs.d~/.emacs.d.backup

If you have any additional configurations from other Emacsinstallations, please clean them up. This includes directories andfiles such as~/.emacs.d,~/.emacs,~/.emacs~,~/.config/emacs,~/.config/doom,~/.config/cache/emacs andany other related files.

After deleting/backing up, clone the repository:

git clone https://github.com/LionyxML/emacs-kick.git~/.emacs.d

2. Run the setup:

After cloning, install the configuration by running:

emacs -nw --eval="(ek/first-install)"

Alternatively, you can run the provided scriptek-reinstall.shfrom inside~/.emacs.d/, which will achieve the same result:

cd~/.emacs.d/&& ./ek-reinstall.sh

Both methods will install all necessary packages and apply theconfiguration.

NOTE: During the initial setup, you'll be prompted to install Tree-sittergrammars and download some fonts. This configuration usesNerd Fonts bydefault, so installing them now is highly recommended for the best experience.

VERY IMPORTANT: On first launch, Emacs will alsonative compile someexternal packages, which may take a little time. Additionally, the first timeyou perform certain actions, like opening the tree explorer, Emacs may compilerelated components in the background. This is completely normal and onlyhappens once per feature. You might notice a brief moment of sluggishperformance during this initial compilation.

3. Set terminal mode by default:

Note on Emacs TUI/GUI: Emacs automatically adapts to eithergraphical or terminal mode depending on the environment. But ifyou're in a graphical session and prefer terminal mode, just use:

emacs -nw

To ensure Emacs always opens in terminal mode, add the following toyour.bashrc or.zshrc:

alias emacs='emacs -nw'

Then, reload your shell configuration with:

source~/.bashrc# for bashsource~/.zshrc# for zsh

4. Start Emacs:

Once set up, start Emacs with:

emacs

Usage Tips:

• Leader Key: The leader key is set toSPC (spacebar),which-key is there to help you discover keybindings.
• Help Commands:
• SPC h i opens the Emacs info documentation (M-x info).
• SPC h v allows you to explore available variables.
• SPC h f lets you explore functions.
• SPC h k displays keybindings.

Troubleshooting:

• If you encounter any issues during installation, check the*Messages* buffer for more information. You can switch betweenbuffers withSPC SPC, and navigate options usingC-p andC-n.

...and a lot more, discoverable with which-key :)

This package is intentionally designed with a specific vision in mind,reflecting my own opinions and preferences. While contributions arewelcome, please understand that this configuration is quiteopinionated.

If you have suggestions or requests, they will be consideredcarefully, but I cannot make any promises regarding implementation oracceptance. Your input is valuable, and I appreciate any help orfeedback to improve the project.

To contribute, feel free to open an issue or submit a pullrequest. Let's make this configuration even better together!

Always welcome, not a promise to accept though (see above). Pleasedirect your PRs to thedevelopment branch of this repository.