Modifier keys

These are used frequently in Emacs documentation.

Here are some examples showing how these modifiers are used in documentation, and how they map to keystrokes:

• C-x C-c: Press and hold Ctrl; press x; press c. Now release Ctrl. This will quit Spacemacs, using Emacs key bindings.
• M-x shell Enter: Press and hold Esc; press x. Release keys. Type shell and press Enter. This will launch the shell inside Spacemacs.

Other common keys

This guide on how keystrokes are denoted in Emacs is a useful reference.

General commands

• SPC q q: Quit.
• SPC f e R: Reload .spacemacs configuration file.
• SPC f e D: Compare (diff) current .spacemacs configuration file against the default.
• SPC f f: Find a file. Opens the file browser.
  • C-h: Up a folder.
  • C-l: Open a folder.
  • C-j: Up.
  • C-k: Down.
• SPC f s: Save a file.
• SPC w /: Split window vertically.
• SPC w: Split window horizontally.
• SPC 1: Switch to window 1.
• SPC 2: Switch to window 2.
• SPC w c: Delete current window.
• SPC TAB: Switch to previous buffer.
• SPC b b: Switch buffers.
• SPC w p m: Open messages buffer. Particularly useful for debugging messages that pop up during launch.
• SPC p p: Open project.
• SPC p f: Open the root of project (counsel-projectile-find-file). This will enable a fuzzy file finder, similar to fzf.
• SPC p h: Find a file in current project.
• SPC b d: Kill current buffer.
• SPC b M: Move buffer to another window.
• SPC v: Enter expand-region mode.
• SPC b b: Helm mini; lists buffers and recent files.
• SPC b B: Interactive buffer (ibuffer).
• SPC /: Searches through project.
• SPC s s: Search in a file.
• SPC s l: Find all function definitons in a file.
• SPC v: Expand region.
• SPC V: Contract region.
• s (: Put parens around a region.
• SPC s e: Multiple cursors.
  • n: Jump.
  • N: Jump.
• SPC h d: Help describe.
• SPC f e h: Help.
• SPC h d f: Help describe functions.
• SPC h d v: Help describe variables.
• ALT /: Snippet completion.
• SPC t s: Syntax checking.
• SPC e: Syntax checking options.
• SPC a r: Ranger.
• SPC a d: Deer.

Find and replace

• ALT %: Query-replace; active region, or cursor point to end.
• y: Do the replacement.
• n: Skip.
• !: Do this and all remaining replacements without asking.
• C-g: Cancel.

Toggle settings

• SPC t n: Toggle line numbers.
• SPC t r: Toggle relative line numbers.
• SPC t f: Toggle fill column (e.g. margin line).
• SPC t w: Toggle whitespace characters.
• SPC T n: Toggle through themes.

Fill to right margin

Use M-q to automatically fill paragraphs to fill-column value. Refer to turn-on-fci-mode, fill-column for details.

Layers (plugins)

• SPC ': Shell layer.
• SPC m s i: Python layer.
• SPC a i n: iPython Notebook layer. Now referred to as Jupyter Notebook, but the layer recipe still uses “iPython”.

Git

Spacemacs uses Magit by default to manage Git repositories.

Spacemacs uses evil-magit for key bindings in magit buffers (unless your editing style is set to emacs, in which case you get the default magit bindings), which are the standard magit key bindings with some minimal changes to make them comfortable for evil users.

Highlight by age of commit or last update time is provided by smeargle. Git time machine is provided by git-timemachine. Git last commit message per line is provided by git-messenger.

Common commands

• SPC g s: Open status buffer (inside of Git repository).
• SPC g b: Open a magit blame.
• SPC g B: Quit magit blame.
• SPC g c: Commit changes.
• SPC g C: Checkout branches.
• SPC g d: Show diff prompt.
• SPC g D: Show diff against current head.
• SPC g e: Show ediff comparison.
• SPC g E: Show ediff against current head.
• SPC g f: Show fetch prompt.
• SPC g F: Show pull prompt.
• SPC g H c: Clear highlights.
• SPC g H h: Highlight regions by age of commits.
• SPC g H t: Highlight regions by last updated time.
• SPC g i: Git init a given directory.
• SPC g I: Open helm-gitignore.
• SPC g l: Open a magit log.
• SPC g L: Display the log for a file.
• SPC g P: Show push prompt.
• SPC g s: Open a magit status window.
• SPC g S: Stage current file.
• SPC g m: Display the last commit message of the current line.
• SPC g t: Launch the git time machine.
• SPC g U: Unstage current file.

Bindings inside status buffer

• /: Search (evil-search).
• $: Open command output buffer.
• c c: Open a commit message buffer.
• b b: Checkout a branch.
• b c: Create a branch.
• f f: Fetch changes.
• F (r) u: Pull tracked branch and rebase.
• gr: Refresh.
• j: Go to next magit section.
• C-j: Next visual line.
• k: Go to previous magit section.
• C-k: Previous visual line.
• l l: Open log buffer.
• n: Next search occurrence.
• N: Previous search occurrence.
• o: Revert item at point.
• P u: Push to tracked branch.
• P m: Push to matching branch (e.g. upstream/develop to origin/develop).
• q: Quit.
• s on a file or hunk in a diff: Stage the file or hunk.
• x: Discard changes.
• + on a hunk: Increase hunk size.
• - on a hunk: Decrease hunk size.
• S: Stage all.
• TAB on a file: Expand/collapse diff.
• u on a staged file: Unstage.
• U: Unstage all staged files.
• v; V: Select multiple lines.
• z z: Stash changes.

Staging lines

Magit allows you to stage specific lines by selecting them in a diff and hitting s to stage. Due to inconsistencies between Vim and Emacs editing styles, if you enter visual line state with V, you will stage one more line than intended. To work around this, you can use v instead (since Magit only stages whole lines, in any case).

Commit message editing buffer

• ~,c~; C-c C-c: Commit the changes with the entered message.
• ~,a~; C-c C-k: Discard the commit message.

Interactive rebase buffer

• c; p: Pick.
• e: Edit.
• f: Fixup.
• j: Go down.
• gj: Move line down.
• k: Go up.
• gk: Move line up.
• d; x: Kill line.
• r: Reword.
• s: Squash.
• u: Undo.
• y: Insert.
• !: Execute.

Time machine

git-timemachine allows to quickly browse the commits of the current buffer.

• SPC g t: Start git time machine and initiate micro-state.
• c: Show current commit.
• n: Show next commit.
• N: Show previous commit.
• p: Show previous commit.
• q: Leave micro-state and quit git time machine.
• Y: Copy current commit hash.

Quick guide for recurring use cases in Magit

Amend a commit:

1. l l: Open the log buffer.
2. c a: Amend the commit.
3. ~,c~; C-c C-c: Submit the changes.

Squash last commit:

1. l l: Open the log buffer.
2. r e on the second to last commit; it opens the rebase buffer.
3. j: Put point on last commit.
4. s: Squash it.
5. ~,c~; C-c C-c: Continue to the commit message buffer.
6. ~,c~; C-c C-c (again): Edit the commit message.

Add upstream remote (the parent repository you have forked):

1. M: Open the remote popup.
2. a: Add a remote, type the name (i.e. upstream) and the URL.

Pull changes from upstream (the parent repository you have forked) and push:

1. F -r C-u F: Choose upstream or the name you gave to it.
2. P P: Push the commit to origin.

ESS

Emacs speaks statistics (ESS) is an incredibly useful interface for R programming on a remote server where RStudio is not available.

The Emacs documentation frequently refers to REPL, which stands for read-eval-print loop. You’ll see this in the ESS documentation for spacemacs.

The standard Ctrl+Enter console command will work when ESS major-mode keybindings are defined. Note that this might not be configured properly for spacemacs on a fresh install.

Switch between console and source code windows using M-1 here. Note that SPC 1 doesn’t work when focused on the R console.

Key bindings

Send code to an inferior REPL process with these commands:

Helpers

Helpers for inspecting objects at point are available in R buffers only.

Refer to the ESS layer documentation for more information.

TRAMP

TRAMP is a very useful package for editing remote files over SSH from within a local emacs instance. Drowzy’s Medium post has useful additional details.

unimpaired

Pairs of handy bracket mappings with unimpaired.

• [e: Move line up.
• ]e: Move line down.
• [SPC: Insert space above.
• ]SPC: Insert space below.
• [p: Paste above current line.
• ]p: Paste below current line.

Note that spacemacs contains an internal port of unimpaired.

evil-mc

evil-mc enables the use of multiple cursors.

• grm: Make all cursors.
• gru: Undo all cursors.
• grs: Pause cursors.
• grr: Resume cursors.
• grf: Make and go to first cursor.
• grl: Make and go to last cursor.
• grh: Make cursor here.
• grN: Skip and go to next cursor.
• grP: Skip and go to prev cursor.
• grn: Skip and go to next match.
• grp: Skip and go to prev match.
• M-n: Make and go to next cursor.
• M-p: Make and go to prev cursor.
• C-n: Make and go to next match.
• C-t: Skip and goto next match.
• C-p: Make and goto prev match.

eyebrowse

eyebrowse is a workspace manager.

• gt: Go to next workspace.
• gT: Go to previous workspace.
• SPC l w n: Create or switch to workspace n.
• SPC l w TAB: Switch to last active workspace.
• SPC l w c: Close current workspace.
• SPC l w n; SPC l w l: Switch to next workspace.
• SPC l w N; SPC l w p; SPC l w h: Switch to previous workspace.
• SPC l w r: Set a tag to the current workspace.
• SPC l w w: Switched to tagged workspace.

Troubleshooting

Fix for org-projectile warning:

Error (use-package): org-projectile/:config: Symbol’s function definition is
void: org-projectile:per-repo

rm -fv ~/.emacs.d/elpa/org-projectile-*/org-projectile.elc

References

• Actually getting spacemacs to do stuff
• An introduction to Spacemacs
• Beginner’s tutorial
• Default template
• robphoenix’s gist.

Configurations:

• roryk’s config
• mattnedrich’s config
• practicalli’s config
• jsmestad’s config
• benmarwick’s config
• yousufinternet’s config

See also:

• shell layer
• ess layer
• Right margin indicator issue