05a2256cff
As `SPC L` has moved to `SPC l` and avy is now on `SPC y`, the FAQ has to be updated because the evil-leader example doesn't make sense any longer. The question is also moved to "How do I …" where it belongs. The code has also been updated to be a little bit cleaner.
293 lines
13 KiB
Org Mode
293 lines
13 KiB
Org Mode
#+TITLE: Frequently Asked Questions
|
|
|
|
* FAQ :TOC_4_org:noexport:
|
|
- [[Common][Common]]
|
|
- [[Which version of Spacemacs am I running?][Which version of Spacemacs am I running?]]
|
|
- [[What is the official pronunciation of Spacemacs?][What is the official pronunciation of Spacemacs?]]
|
|
- [[Why are packages installed with =package-install= automatically deleted by Spacemacs when it boots?][Why are packages installed with =package-install= automatically deleted by Spacemacs when it boots?]]
|
|
- [[The Spacemacs banner is ugly, what should I do?][The Spacemacs banner is ugly, what should I do?]]
|
|
- [[The powerline separators are ugly, how can I fix them?][The powerline separators are ugly, how can I fix them?]]
|
|
- [[The powerline separators have no anti-aliasing, what can I do?][The powerline separators have no anti-aliasing, what can I do?]]
|
|
- [[Why is after-init-hook not executed?][Why is after-init-hook not executed?]]
|
|
- [[What is the difference between =spacemacs-base= and =spacemacs= distributions?][What is the difference between =spacemacs-base= and =spacemacs= distributions?]]
|
|
- [[Should I place my settings in =user-init= or =user-config=?][Should I place my settings in =user-init= or =user-config=?]]
|
|
- [[Why do some of my =org=-related settings cause problems?][Why do some of my =org=-related settings cause problems?]]
|
|
- [[Why is Spacemacs hanging on startup?][Why is Spacemacs hanging on startup?]]
|
|
- [[How do I...][How do I...]]
|
|
- [[Disable a package completely?][Disable a package completely?]]
|
|
- [[Disable a package only for a specific major-mode?][Disable a package only for a specific major-mode?]]
|
|
- [[Disable company for a specific major-mode?][Disable company for a specific major-mode?]]
|
|
- [[Change special buffer rules?][Change special buffer rules?]]
|
|
- [[Enable navigation by visual lines?][Enable navigation by visual lines?]]
|
|
- [[Disable evilification of a mode?][Disable evilification of a mode?]]
|
|
- [[Include underscores in word motions?][Include underscores in word motions?]]
|
|
- [[Setup =$PATH=?][Setup =$PATH=?]]
|
|
- [[Change or define an alias for an =evil-leader= prefix?][Change or define an alias for an =evil-leader= prefix?]]
|
|
- [[Windows][Windows]]
|
|
- [[Why do the fonts look crappy on Windows?][Why do the fonts look crappy on Windows?]]
|
|
- [[Why is there no Spacemacs logo in the startup buffer?][Why is there no Spacemacs logo in the startup buffer?]]
|
|
- [[Why are all packages unavailable?][Why are all packages unavailable?]]
|
|
- [[OS X][OS X]]
|
|
- [[Why are the powerline colors not correct on OS X?][Why are the powerline colors not correct on OS X?]]
|
|
|
|
* Common
|
|
** Which version of Spacemacs am I running?
|
|
The version is displayed on the upper right corner of the loading screen. You
|
|
may also just type ~SPC f e v~.
|
|
|
|
** What is the official pronunciation of Spacemacs?
|
|
As it is written, that is _space_ then _macs_.
|
|
|
|
** Why are packages installed with =package-install= automatically deleted by Spacemacs when it boots?
|
|
To declare new packages you have to create a new configuration layer, see the
|
|
[[file:QUICK_START.org][quick start guide]].
|
|
|
|
** The Spacemacs banner is ugly, what should I do?
|
|
Install the default font supported by Spacemacs or choose a fixed width font.
|
|
More information in the font section of the [[file:DOCUMENTATION.org][documentation]].
|
|
|
|
** The powerline separators are ugly, how can I fix them?
|
|
Use the property =:powerline-scale= of the variable =dotspacemacs-default-font=.
|
|
See font section of the [[file:DOCUMENTATION.org][documentation]] for more details.
|
|
|
|
** The powerline separators have no anti-aliasing, what can I do?
|
|
Emacs powerline uses XMP images to draw the separators in a graphical
|
|
environment. You can have anti-aliasing if you use the =utf8= separator. Note
|
|
that by default the =utf8= separator is used in a terminal. See the powerline
|
|
section in the font section of the [[file:DOCUMENTATION.org][documentation]].
|
|
|
|
** Why is after-init-hook not executed?
|
|
Don't launch Spacemacs with =emacs -q -l init.el= command. This command will run
|
|
the hooked function in =after-init-hook= before the evaluation of the passed =-l
|
|
init.el= file.
|
|
|
|
** What is the difference between =spacemacs-base= and =spacemacs= distributions?
|
|
The =distribution= concept was introduced in 0.104.x. You can now choose
|
|
between two distributions =spacemacs= or =spacemacs-base=.
|
|
=spacemacs-base= contains only a minimal set of packages; whereas =spacemacs=
|
|
is the full Spacemacs experience.
|
|
Set the distribution with =dotspacemacs-distribution= variable. The default is
|
|
=spacemacs=. For more information as to what is included,
|
|
check out the =packages.el= file in the respective folders in the
|
|
=+distribution= folder of the =layers/= directory.
|
|
|
|
** Should I place my settings in =user-init= or =user-config=?
|
|
Any variable that layer configuration code will *read* and *act on* must be set
|
|
in =user-init=, and any variable that Spacemacs explicitly sets but you wish to
|
|
*override* must be set in =user-config=.
|
|
|
|
Anything that isn't just setting a variable should 99% be in =user-config=.
|
|
|
|
** Why do some of my =org=-related settings cause problems?
|
|
Since version 0.104, spacemacs uses the `org` version from the org ELPA
|
|
repository instead of the one shipped with emacs. Then, any `org` related code
|
|
should not be loaded before `dotspacemacs/user-config`, otherwise both versions
|
|
will be loaded and will conflict.
|
|
|
|
** Why is Spacemacs hanging on startup?
|
|
This is probably related to Helm using Tramp which tries to figure out some
|
|
SSH/DNS settings at startup. The root cause is probably your ISP redirecting
|
|
non-existing addresses to their own servers.
|
|
|
|
Try using these settings in the ~user-init~ function in your ~.spacemacs~
|
|
configuration:
|
|
|
|
#+BEGIN_SRC elisp
|
|
(setq tramp-ssh-controlmaster-options
|
|
"-o ControlMaster=auto -o ControlPath='tramp.%%C' -o ControlPersist=no")
|
|
#+END_SRC
|
|
|
|
See [[https://github.com/syl20bnr/spacemacs/issues/3422#issuecomment-148919047][issue #3422]] and [[https://github.com/emacs-helm/helm/issues/1000#issuecomment-119487649][helm issue #1000]] for details.
|
|
|
|
* How do I...
|
|
** Disable a package completely?
|
|
To completely disable a package and effectively uninstalling it even if
|
|
it is part of your used layers, look for the variable
|
|
=dotspacemacs-excluded-packages= in your dotfile and add the package
|
|
name to it:
|
|
|
|
#+begin_src emacs-lisp
|
|
(setq-default dotspacemacs-excluded-packages '(package1 package2 ...))
|
|
#+end_src
|
|
|
|
** Disable a package only for a specific major-mode?
|
|
This is done by removing the hook added by Spacemacs. For example to
|
|
remove =flycheck= support in python buffers, look for the function
|
|
=dotspacemacs/user-config= in your dotfile and add the following code:
|
|
|
|
#+begin_src emacs-lisp
|
|
(remove-hook 'python-mode-hook 'flycheck-mode)
|
|
#+end_src
|
|
|
|
*Hint* to know the name of the major-mode of the current buffer press:
|
|
~SPC h d v major-mode RET~
|
|
|
|
** Disable company for a specific major-mode?
|
|
It may be handy to disable =company= for a given mode if you plan on
|
|
configuring =auto-complete= instead. On easy way to do it is to use the
|
|
macro =spacemacs|disable-company= in the function =dotspacemacs/user-config=
|
|
of your dotfile. The following snippet disables company for
|
|
=python-mode=:
|
|
|
|
#+begin_src emacs-lisp
|
|
(spacemacs|disable-company python-mode)
|
|
#+end_src
|
|
|
|
** Change special buffer rules?
|
|
To change the way spacemacs marks buffers as useless, you can customize
|
|
=spacemacs-useless-buffers-regexp= which marks buffers matching the
|
|
regexp as useless. The variable =spacemacs-useful-buffers-regexp= marks
|
|
buffers matching the regexp as useful buffers. Both can be customized
|
|
the same way.
|
|
|
|
Examples:
|
|
#+begin_src emacs-lisp
|
|
;; Only mark helm buffers as useless
|
|
(setq spacemacs-useless-buffers-regexp '("\\*helm\.\+\\*"))
|
|
|
|
;; Marking the *Messages* buffer as useful
|
|
(push "\\*Messages\\*" spacemacs-useful-buffers-regexp)
|
|
#+end_src
|
|
|
|
** Enable navigation by visual lines?
|
|
Add the following snippet to your =dostpacemacs/config= function:
|
|
|
|
#+begin_src emacs-lisp
|
|
;; Make evil-mode up/down operate in screen lines instead of logical lines
|
|
(define-key evil-motion-state-map "j" 'evil-next-visual-line)
|
|
(define-key evil-motion-state-map "k" 'evil-previous-visual-line)
|
|
;; Also in visual mode
|
|
(define-key evil-visual-state-map "j" 'evil-next-visual-line)
|
|
(define-key evil-visual-state-map "k" 'evil-previous-visual-line)
|
|
#+end_src
|
|
|
|
** Disable evilification of a mode?
|
|
You can ensure a mode opens in emacs state by using =evil-set-initial-state=.
|
|
|
|
#+begin_src emacs-lisp
|
|
(evil-set-initial-state 'magit-status-mode 'emacs)
|
|
#+end_src
|
|
|
|
You can also do this using buffer name regular expressions. E.g. for magit,
|
|
which has a number of different major modes, you can catch them all with
|
|
|
|
#+begin_src emacs-lisp
|
|
(push '("*magit" . emacs) evil-buffer-regexps)
|
|
#+end_src
|
|
|
|
This should make all original magit bindings work in the major modes in
|
|
question. To enable the leader key in this case, you may have to define a
|
|
binding in the mode's map, e.g. for =magit-status-mode=,
|
|
|
|
#+begin_src emacs-lisp
|
|
(with-eval-after-load 'magit
|
|
(define-key magit-status-mode-map
|
|
(kbd dotspacemacs-leader-key) evil-leader--default-map))
|
|
#+end_src
|
|
|
|
** Include underscores in word motions?
|
|
You can modify the syntax table of the mode in question. For example, for Python
|
|
mode:
|
|
|
|
#+begin_src emacs-lisp
|
|
(with-eval-after-load 'python
|
|
(modify-syntax-entry ?_ "w" python-mode-syntax-table))
|
|
#+end_src
|
|
|
|
** Setup =$PATH=?
|
|
Some layers require certain tools to be available on your =$PATH=. This means
|
|
that your =$PATH= must contain the installation paths for those tools. For
|
|
example, if you have installed some tools to =~/.local/bin= and want them to be
|
|
available in Spacemacs, you need to add =~/.local/bin= to your =$PATH=.
|
|
|
|
Users of =bash=, =zsh=, =sh= and other similar shells should add following line
|
|
to their =.bashrc= (=.zshrc=, =.profile= or your shell's equivalent). Note that
|
|
the =export= part is very important.
|
|
|
|
#+BEGIN_SRC sh
|
|
export PATH=~/.local/bin:$PATH
|
|
#+END_SRC
|
|
|
|
Users of =fish= should add following line to their =config.fish= file (should be
|
|
in =$XDG_CONFIG_HOME= or its default value - =~/.config/fish=). Note that =-x=
|
|
part is very important.
|
|
|
|
#+BEGIN_SRC fish
|
|
set -x PATH ~/.local/bin $PATH
|
|
#+END_SRC
|
|
|
|
Users of other shells should consult its documentation on how to setup =$PATH=
|
|
variable (with export to environment).
|
|
|
|
So now, =~/.local/bin= should be available in your =$PATH=. You can verify this
|
|
by calling =echo $PATH=. But you also should verify that =$PATH= is set properly
|
|
in your environment. To do so call following command in your terminal.
|
|
|
|
#+BEGIN_SRC sh
|
|
$ env | grep "PATH"
|
|
#+END_SRC
|
|
|
|
This is the value that will be used by Emacs. So it must contain =~/.local/bin=.
|
|
|
|
After that you can run Spacemacs and check that it properly gets the value of
|
|
=$PATH= by running =M-: (getenv "PATH")=.
|
|
|
|
Note that having =~/.local.bin= in your =$PATH= also means that it's possible to
|
|
run terminal and call tools from =~/.local/bin= without specifying their full
|
|
path. Under certain conditions you might want to avoid modifying your =$PATH=.
|
|
In that case you have the option of updating the value of =exec-path= in the
|
|
=dotspacemacs/user-config= function of your =.spacemacs= file.
|
|
|
|
#+BEGIN_SRC emacs-lisp
|
|
(add-to-list 'exec-path "~/.local/bin/")
|
|
#+END_SRC
|
|
|
|
** Change or define an alias for an =evil-leader= prefix?
|
|
It is possible to change an =evil-leader= prefix by binding its keymap to
|
|
another sequence. For instance, if you want to switch ~SPC S~ (spelling) with
|
|
~SPC d~ (used by dash) to make the former easier to reach, you can use:
|
|
|
|
#+begin_src emacs-lisp
|
|
(defun my-evil-leader/swap-keys (key1 key2)
|
|
(let ((map1 (lookup-key evil-leader--default-map key1))
|
|
(map2 (lookup-key evil-leader--default-map key2)))
|
|
(evil-leader/set-key key1 map2 key2 map1)))
|
|
(my-evil-leader/swap-keys "S" "d")
|
|
#+end_src
|
|
|
|
If you want to define your own alias, like using ~SPC é~ (because it's an
|
|
unmapped key on your keyboard-layout for instance) for accessing ~SPC w~
|
|
(windows management), you can use this:
|
|
|
|
#+begin_src emacs-lisp
|
|
(defun my-evil-leader/alias-of (key1 key2)
|
|
(let ((map (lookup-key evil-leader--default-map key2)))
|
|
(evil-leader/set-key key1 map)))
|
|
(my-evil-leader/alias-of "é" "w")
|
|
#+end_src
|
|
|
|
* Windows
|
|
** Why do the fonts look crappy on Windows?
|
|
You can install [[https://code.google.com/p/mactype/][MacType]] on Windows to get very nice looking fonts. It is
|
|
also recommended to disable smooth scrolling on Windows.
|
|
|
|
** Why is there no Spacemacs logo in the startup buffer?
|
|
A GUI build of emacs supporting image display is required.
|
|
You can follow the instructions [[http://stackoverflow.com/questions/2650041/emacs-under-windows-and-png-files][here]]. Alternatively you can download binaries
|
|
of emacs with image support included such as [[http://emacsbinw64.sourceforge.net/][this one]].
|
|
|
|
** Why are all packages unavailable?
|
|
Check if your Emacs has HTTPS capabilities by doing =M-:= and then:
|
|
|
|
#+begin_src emacs-lisp
|
|
(gnutls-available-p)
|
|
#+end_src
|
|
|
|
If this returns =nil=, you need to install the GnuTLS DDL file in the same
|
|
directory as Emacs. See [[https://www.gnu.org/software/emacs/manual/html_mono/emacs-gnutls.html#Help-For-Users][here]] for instructions.
|
|
|
|
* OS X
|
|
** Why are the powerline colors not correct on OS X?
|
|
This is a [[https://github.com/milkypostman/powerline/issues/54][known issue]] as of Emacs 24.4 due to =ns-use-srgb-colorspace=
|
|
defaulting to true. It is recommended to use the [[http://github.com/railwaycat/homebrew-emacsmacport][emacs-mac-port]] build. See the
|
|
install section in the [[file:../README.md][README]] for more details.
|