philosophy | for whom? | screenshots | documentation | contribute | achievements | FAQ

Quick Install:

This assumes you don't have an existing e-macs setup and want to run Space-macs as your config. If you do have one, look at the full installation instructions for other options.

• For stable releases:

  git clone https://github.com/syl20bnr/space-macs ~/.e-macs.d

• For development updates and participation:

  git clone -b develop https://github.com/syl20bnr/space-macs ~/.e-macs.d

Table of Contents

• Introduction
• Features
• Documentation
• Getting Help
• Prerequisites
  • e-macs
    • Linux distros
    • macOS
    • Windows
• Install
  • Default installation
  • Alternative installations
    • Modify HOME environment variable
    • Modify space-macs-start-directory variable
  • Space-macs logo
• Update
  • Automatic update (on master branch)
  • Manual update (on master branch)
  • On develop branch
  • Revert to a specific version
• Quotes
• Contributions
• Communities
• Space-macs Everywhere
• License
• Supporting Space-macs

Space-macs is a new way of experiencing e-macs -- it's a sophisticated and polished set-up, focused on ergonomics, mnemonics and consistency.

Just clone and launch it, then press the space bar to explore the interactive list of carefully-chosen key bindings. You can also press the home buffer's [?] button for some great first key bindings to try.

Space-macs can be used naturally by both e-macs and Vim users -- you can even mix the two editing styles. Being able to quickly switch between input styles, makes Space-macs a great tool for pair-programming.

Space-macs is currently in beta, and any contributions are very welcome.

• Great documentation: access the Space-macs documentation with SPC h SPC.
• Beautiful GUI: you'll love the distraction free UI and its functional mode-line.
• Excellent ergonomics: all the key bindings are accessible by pressing the space bar or alt-m.
• Mnemonic key bindings: commands have mnemonic prefixes like SPC b for all the buffer commands or SPC p for the project commands.
• Batteries included: discover hundreds of ready-to-use packages nicely organised in configuration layers following a set of conventions.

Comprehensive documentation is available for each layer by pressing SPC h SPC.

You can also check the general documentation, quick start guide and the FAQ.

If you need help, ask your question in the Gitter Chat and a member of the community will help you out.

If you prefer IRC, connect to the Gitter Chat IRC server and join the #syl20bnr/space-macs channel.

Last but not least there are a lot of high class tutorials available on YouTube:

• Jack of Some's Space-macs related channel here
• GDQuest's Game Design oriented tutorials to Space-macs here
• Practicalli's Clojure tutorials based on Space-macs here
• Eivind Fonn's classic Space-macs ABC here

Space-macs is an extension of a popular text editor called e-macs. Thus you need to first install base e-macs and then download the Space-macs extension files with Git.

Space-macs requires e-macs 25.1 or above. The development version of e-macs is not officially supported, but it should nevertheless be expected to work.

Some modes require third-party tools that you'll have to install via your favorite package manager.

Install the e-macs package with your linux distributions package manager.

Do not install the xe-macs package. It's not supported by Space-macs. Xe-macs is an old fork of e-macs. The X in its name is unrelated to X11.

e-macs has graphical support.

Note: The Ubuntu LTS 12.04 and 14.04 repositories only have e-macs version 24.3 available. Version 25.1 or greater needs to be built from source. This might also be true for other linux distributions.

brew tap d12frosted/e-macs-plus
# to install e-macs 26
brew install e-macs-plus
# or to install e-macs 27
brew install e-macs-plus@27 --with-space-macs-icon
# or to install e-macs 28
brew install e-macs-plus@28 --with-space-macs-icon
brew link e-macs-plus

brew tap railwaycat/e-macsmacport
brew install e-macs-mac
brew link e-macs-mac

Homebrew now recommends to use the cask version with the following message: "Please try the Cask for a better-supported Cocoa version". To install the cask version:

brew cask install e-macs

This installs a pre-built package from https://e-macsformacosx.com/

If you're not comfortable with the ways mentioned above, then e-macsWiki lists down a few ways to install e-macs for macOS.

Once e-macs is installed, run the following commands in the terminal to install the default Source Code Pro font:

brew tap homebrew/cask-fonts
brew cask install font-source-code-pro

git clone https://github.com/syl20bnr/space-macs ~/.e-macs.d

Notes: After completing the Space-macs install process, then it's also recommended to add the osx layer to your dotfile. Installation instructions are available in the documentation for the osx layer.

Depending on the installed version of GnuTLS securely installing e-macs packages may fail. In this case it is possible to install using e-macs --insecure. However be aware that this means your packages will be transferred using http, use at your own risk.

You might also have some issues when doing some search on your projects, you probably want to install grep through homebrew with default names:

$ brew install grep --with-default-names

Download the official 64-bit (x86_64) stable builds from the GNU FTP.

You'll also need gzip and put it in your path, to download it go to the GNUWin32 project page

Be sure to declare an environment variable named HOME that's pointing to your user directory C:\Users\<username>. Then you can clone Space-macs into that directory.

If the following error occurs after starting e-macs:

The directory ~/.e-macs.d/server is unsafe

Fix it by changing the owner of the directory ~/.e-macs.d/server:

• from Properties select the Tab “Securityâ€�,
• select the button “Advancedâ€�,
• select the Tab “Ownerâ€�
• change the owner to your account name

Source: Stack Overflow

For efficient searches we recommend installing pt (the platinum searcher). pt version 1.7.7 or higher is required.

Notes: Depending on the installed version of GnuTLS securely installing e-macs packages may fail. In this case it is possible to install using e-macs --insecure. However be aware that this means your packages will be transferred using http, use at your own risk.

1. If you have an existing e-macs configuration, back it up first by running the following code in your terminal:

   cd ~
   mv .e-macs.d .e-macs.d.bak
   mv .e-macs .e-macs.bak

   Don't forget to backup and remove the ~/.e-macs file. Otherwise Space-macs WILL NOT be able to load. Because that file prevents e-macs from loading the proper initialization file.

2. Clone the repository with Git:

   git clone https://github.com/syl20bnr/space-macs ~/.e-macs.d

   Or

   git clone --depth 1 https://github.com/syl20bnr/space-macs ~/.e-macs.d

   In case you have a limited internet connection or speed.

   master is the stable branch and it is immutable, DO NOT make any modification to it or you will break the update mechanism. If you want to fork Space-macs safely, use the develop branch where you'll handle updates manually.

   Note for Windows users If you use windows, then you'll have to modify the git command by inserting the correct path to your .e-macs.d folder. The dot before the folder means that it's hidden. You'll have to search for hidden files to find the folder. When you have found the folder, substitute the original path with the correct one. The proper code would look something like this:

   git clone https://github.com/syl20bnr/space-macs /path/to/your/.e-macs.d

3. (Optional) Install the default fonts

   It's recommended to install Source Code Pro by Adobe, as the default font. It ensures that, for example the symbols on the modeline (bottom bar) looks correct. It's also recommended to use a "Fallback font". These depend on the system:

   • GNU/Linux: NanumGothic (package named fonts-nanum on Debian, for example)
   • macOS: Arial Unicode MS
   • Windows: MS Gothic or Lucida Sans Unicode

   If the modeline doesn't look similar to the picture at the top of this page, then make sure you have the correct fallback font installed.

   If you're running in a terminal then you'll also need to change the terminals font settings.

4. Launch e-macs. Space-macs will automatically install the packages it requires. There is a well-known issue with some GPG keys having expired end of 2019. This can be fixed by upgrading to e-macs 26.3 or above or by manually adding the new keys using something like:

   gpg --homedir ~/.e-macs.d/elpa/gnupg --receive-keys 066DAFCB81E42C40

   If you have a restrictive firewall it may help to manually specify the keyserver:

   gpg --keyserver keyserver.ubuntu.com --homedir ~/.e-macs.d/elpa/gnupg/ --receive-keys 066DAFCB81E42C40

5. Launch e-macs, and answer the questions in the Dotfile wizard installer. If you are new to e-macs and Space-macs, then it's fine to just accept the default choices. It's easy to try the other choices later, without having to reinstall Space-macs. They can be changed in the dotfile ~/.space-macs.

   After answering the questions, then Space-macs starts downloading and installing the packages it requires. When the packages have been installed. Restart e-macs to complete the installation.

Notes: If you are behind a firewall or similar and you get an error regarding package downloads then you may try to disable the HTTPS protocol by starting e-macs with

e-macs --insecure

but this should be a last resort because of the security implications.

You can set the dotspace-macs-elpa-https variable to nil in your dotfile ~/.space-macs but this has the same security implications as the insecure flag. You may also want to clear out your .e-macs.d/elpa directory before doing this, so that any corrupted packages you may have downloaded will be re-installed.

error: Package 'package-build-' is unavailable may occur due to heavy network taffic. You can fix it by setting the dotspace-macs-elpa-timeout variable to 70 in your dotfile.

Warning (bytecomp) and other compilation warnings are perfectly normal. If you're curious, you can find out why these occur here.

If the mode-line turns red then be sure to consult the FAQ.

There are currently, two supported, alternative locations, for a Space-macs configuration.

This solution is ideal for quickly trying Space-macs without compromising your existing configuration. Clone Space-macs outside the e-macs dotdirectory ~/.e-macs.d and modify the HOME environment variable.

mkdir ~/space-macs
git clone https://github.com/syl20bnr/space-macs.git ~/space-macs/.e-macs.d
HOME=~/space-macs e-macs

Note: If you're using the Fish shell, then you'll need to modify the last command to: env HOME=$HOME/space-macs e-macs

This solution is better suited to "embed" Space-macs into your own configuration. If you've cloned Space-macs into ~/.e-macs.d/space-macs/, then drop the following lines in the ~/.e-macs.d/init.el file:

(setq space-macs-start-directory "~/.e-macs.d/space-macs/")
(load-file (concat space-macs-start-directory "init.el"))

For Ubuntu users, follow this guide to change the logo in Unity.

For macOS users, you need to download the .icns version of the logo, then change the logo on the Dock.

Space-macs shows a notification when a new version is available (only when you are on the default master branch). If you are on the develop branch then you'll have to update the Space-macs repository manually.

When a new version is available then a little arrow appears in the mode-line.

Its color depends on the number of versions that have been released since your last update. Green means that you have a recent version, orange and red means that you have an older version.

Click on the arrow to update Space-macs to the latest version.

Remove the < and > angle brackets when you're typing the lines below into your shell. And replace the text: "tag version which you are updating to" with a tagged version. This page lists the latest tags

git fetch
git reset --hard <tag version which you are updating to>

1. Close e-macs and update the git repository:

   git pull --rebase

2. Restart e-macs to complete the upgrade.

To revert to a specific version, just checkout the corresponding branch. For instance to revert to version 0.200, type the following command:

git checkout origin/release-0.200

After updating Space-macs (either manually or automatically), then you also should check if any updates are available for your packages. On the Space-macs Home Buffer SPC b h, click (press RET) on the [Update Packages] button.

Quote by ashnur:

«I feel that space-macs is an aircraft carrier and I am playing table tennis
on the deck as a freerider.»

Quote by deuill:

«I LOVE SPACe-macs AND MAGIT

 That is all»

Space-macs is a community-driven project, it needs you to keep it up to date and to propose great and useful configurations for all the things!

Before contributing be sure to consult the contribution guidelines and conventions.

• Gitter Chat
• Stack Exchange
• Reddit

Once you've learned the Space-macs key bindings, you can use them in other IDEs/tools, thanks to the following projects:

• Intellimacs - Space-macs' like key bindings for IntelliJ platform
• Spaceclipse - Space-macs’ like key bindings for Eclipse
• SpaceVim - A community-driven modular vim distribution
• VSpaceCode - Space-macs’ like key bindings for Visual Studio Code

The license is GPLv3 for all parts specific to Space-macs, this includes:

• the initialization and core files
• all the layer files
• the documentation

For the packages shipped in this repository, you can refer to the files header.

Space-macs logo by Nasser Alshammari released under a Creative Commons Attribution-ShareAlike 4.0 International License.

The best way to support Space-macs is to contribute to it either by reporting bugs, helping the community on the Gitter Chat or sending pull requests.

You can show your love for the project by getting cool Space-macs t-shirts, mugs and more in the Space-macs Shop.

If you want to show your support financially, then you can contribute to Bountysource, or buy a drink for the maintainer by clicking on the Paypal badge.

If you used space-macs in a project, and you want to show that fact, you can use the space-macs badge:

• For Markdown:

  [![Built with Space-macs](https://cdn.rawgit.com/syl20bnr/space-macs/442d025779da2f62fc86c2082703697714db6514/assets/space-macs-badge.svg)](http://space-macs.org)

• For HTML:

  <a href="http://space-macs.org"><img alt="Built with Space-macs" src="https://cdn.rawgit.com/syl20bnr/space-macs/442d025779da2f62fc86c2082703697714db6514/assets/space-macs-badge.svg" /></a>

• For Org-mode:

  [[http://space-macs.org][file:https://cdn.rawgit.com/syl20bnr/space-macs/442d025779da2f62fc86c2082703697714db6514/assets/space-macs-badge.svg]]
  

Thank you!