Beginners tutorial

The power of Spacemacs lies in its efficient key bindings. Because it is built on Emacs, we will use Emacs conventions for key binding notation. The most important modifier keys are:

• SPC = Space, used as the leader key in Vim editing style.
• RET = Return (also known as Enter)
• C- = Ctrl
• M- (for "meta") = Alt
• S- = Shift

The modifier keys can be used either in a sequence or as key chords by pressing two keys at the same time. SPC 1 is notation for a key sequence and means pressing Space first and pressing 1 after it. Key chords are notated by writing a - between the keys. Thus C-c means pressing Ctrl and the letter c simultaneously. Key chords and sequences can also be combined: C-c a means "First press Ctrl and c simultaneously, then press a". C-c C-a means "First press Ctrl and c simultaneously, then press Ctrl and a simultaneously".

This document assumes you chose the "Vim" editing style and notates accordingly. If you chose the Emacs editing style, just substitute SPC with M-m in all the commands that begin with SPC.

(Note: Other modifier keys such as Super, notated with a small-case s-, can be set up but this is rarely necessary in Spacemacs).

Writing (or programming) is typically not a simple linear process of adding words and lines until finished. At least as important part of the work consists of editing the text: deleting and rewriting parts, moving sentences around or jumping to an earlier point to fix a discrepancy.

The crudest way to, for example, delete a certain line is moving the mouse to the line in question, clicking on the line and then deleting it by pressing backspace repeatedly. This is slow and inefficient, both because you have to take your hands from your keyboard and because repeatedly pressing backspace takes time. The more time you spend pressing keys, the more time and energy is wasted.

To speed up editing, many editors use key chords for common editing tasks: Control-c for copying and so on. However, these types of shortcuts tend to have two problems. First, you have to press two keys at the same time, which is harder to coordinate and thus slower than pressing keys in a sequence. Second, you typically have to use your weakest fingers (pinkies) extensively and bend your wrists in unergonomic positions, which is uncomfortable for many and risks developing carpal tunnel syndrome in the long run.

By contrast, Spacemacs uses modal editing. Modal editing means that different modes are used for editing and writing text. While this can sound complicated at first, in practice it can be learned quickly and once learned is unparallelled in speed and ergonomy. Our earlier example of deleting a certain line of text (a very common edit task) can be achieved in Spacemacs by simply navigating to the line in question with the keys j and k (navigation keys) and pressing d (for "delete") two times!

You might have noticed that this was achieved entirely without moving your fingers from your home row (the row where your fingers lie in rest when touch-typing) and without using modifier keys.

The modal editing features of Spacemacs originate from a text editor called Vi, and thus the modal editing tutorial is called eVIl tutor. Press SPC h T v (that is, the spacebar followed by h, T and v) to familiarize yourself with modal editing.

Now that you are familiar with writing and editing text it is time to put the "Space" into Spacemacs. Because the spacebar is the most accessible key on the keyboard and is pressed by the strongest fingers (the thumbs), it is a natural choice for launching commands. You can think of it as the start menu of Spacemacs.

A short instant after the spacebar is pressed a menu pops up. This interactive menu shows you what submenus and commands can be accessed by subsequent keypresses. Browsing around this menu is a great way of finding new features in Spacemacs, so keep an eye on the different options! ESC usually breaks the combination you don't want to use.

Because Emacs (the extension of which Spacemacs is) was developed in the '80s before the advent of modern graphical user interfaces, Emacs has a different name of what we normally call "windows": in Emacs these are called "frames". A frame is what pops up when you launch Spacemacs from your desktop shortcut. A frame contains windows and buffers.

Windows are the visual spaces a frame is divided into. The default is one, but windows can be split to allow editing multiple files in one frame. Let's try this. Press SPC to bring up the menu. You can see different letters having different submenus associated with them, usually with a mnemonic for easier recall. The letter w is assigned for "windows": press it. A new menu opens with further options. Write the character / to split the currently active window vertically into two.

Now you should see two windows of this tutorial, and the one on the left should be active, as can be seen from the modeline in the bottom or by moving the cursor around using the navigation keys. This isn't very useful, as we would probably want to see a different file on the right.

First, activate the window on the right with SPC 2. Now that the window on the right is active, we can open a different buffer for a different file. We'll use the scratch buffer, which can be used like a notepad. Be warned, unlike other buffers it doesn't prompt you whether you want to save the changes you've made when quitting the program! Press SPC b to open the buffers menu and then switch to the scratch buffer by pressing s. Now you have two different buffers in two different windows open, great! You can write something on the scratch buffer, and when you're done, make sure that the scratch window is active and close it by pressing SPC w d.

Now the tutorial window fills the whole frame. But you only closed the window, not the scratch buffer, so the buffer is still open beneath the surface. You can quickly switch between the current buffer and the last with SPC TAB: use this a couple of times to switch between the tutorial and the scratch buffer. SPC b has more options for switching between buffers, for example SPC b b opens a searchable list of all currently open buffers and SPC b d closes the current buffer.

Files can be accessed under the SPC f mnemonic. You can navigate to any file with SPC f f and open it by pressing RET. Accessing recently opened files is a very common task and is done with SPC f r. An edited file is saved with SPC f s.

Spacemacs divides its configuration into self-contained units called configuration layers. These layers are stacked on top of each other to achieve a custom configuration.

By default Spacemacs uses a dotfile called ~/.spacemacs to control which layers to load. Within this file you can also configure certain features. First, split the window vertically to view both this tutorial and the dotfile simultaneously (SPC w /). Open the dotfile by pressing SPC f e d. Navigate to the line starting with "dotspacemacs-configuration-layers". The following lines have further instructions: uncomment org and git layers if you want to be familiarized with them. More layers for different languages and tools can be found by pressing SPC h SPC. The added layers will be installed upon restart of Spacemacs.

Some layers require third-party tools that you'll have to install via your favorite package manager. The layer readme will tell if this is the case.

You can toggle the theme by SPC T n. This cycles between currently activated themes. You can find more by adding the themes-megapack layer and activate them by writing their names in the dotspacemacs-themes list.

Editing the dotspacemacs-maximized-at-startup variable from nil to t will start Spacemacs maximized.

Save the changes you've made to the dotfile with SPC f s and then quit emacs by SPC q q. You can return to this tutorial by clicking it on the home screen!

Org mode is one of the best features of Spacemacs and enough reason to warrant its use. Org mode's official description tells that it is "for keeping notes, maintaining todo lists, planning projects, and authoring documents with a fast and effective plain-text system", but this gives only a small inkling of its versatility. If you do any kind of writing at all, chances are that Org mode will make it easier and more fun. This tutorial was written in Org mode.

To test some of it's features. Install the Org layer and open this tutorial. Make a copy named test.org with SPC f c somewhere outside of the .emacs.d directory. Press SPC SPC, write org-mode and press RET to switch to org-mode from the write-only documentation mode.

Press S-TAB repeatedly and observe that this cycles the visibility of the contents of different headlines. Press SPC m T T in normal mode and observe that you can add TODO tags on headlines. (This can be changed to just t, see the org layers documentation). Press M-k or M-j in normal mode and see how you can quickly move parts of the document around.

This is not even scratching the surface of Org mode, so you should look into org layer with SPC h SPC org for more information. Googling for Org mode tutorials is also very helpful for finding out about the most useful features!

Version control means keeping track of the changes and edits you have made to your document. Often version control is done by saving different versions of the document with different names, such as "document version 13" and so on. This is crude in many ways: if you want to, for example, re-add something you deleted, you have to manually open several past versions of the document to find the one with the deleted part, and then copy-paste it to the most recent file. More complicated edits will be harder still. Fortunately, there is a much better way. Git is the most popular version control system for programmers, but it can be as useful for people that are writing school or scientific papers, fiction or blog posts as well.

Install the git layer, restart Spacemacs and open a file you want to version control. You can check the status of your file by pressing SPC g s. Select the folder your file is in. You will be prompted whether you want to create a repository in the folder. Select yes. You will see a list of "Untracked files": navigate to the file you want to track and press s to "stage changes". You might be prompted to save the file: save it if necessary. Now the new file needs to be committed: press c and c again. Two windows pop up: one showing the changes you've made since the last edit (in this case, the whole document) and another prompting for a commit message. Write "Initial commit", press ESC to exit back to normal mode and press , c confirm and quit the commit message. To abort, press , a.

Now you know how to make a commit. The commits are saved in the (hidden) .git folder in the same folder the tracked file(s) are in. You can make further commits the same way.

Emacs can be used in daemon mode: a daemon runs in the background and launches clients. This way new frames launch instantly without delay. Emacswiki tells more about the daemon and how to set it to launch automatically on startup.

This is useful outside of Spacemacs as well!

SPC ? shows you the key bindings in the current major mode, which is often helpful. For troubleshooting, please refer to the FAQ by pressing SPC h f. More help is found under SPC h, and with SPC h SPC you can access the comprehensive Spacemacs documentation, including this tutorial and the layer documents.

The Gitter chat can be used to ask questions if the answer cannot be found in the documentation. For a detailed review of Spacemacs's features one can also watch the Spacemacs ABC series by Eivind Fonn on Youtube. Some of the keybindings have changed since the videos were uploaded but seeing someone in action helps spot helpful tricks that would otherwise be missed.