Playground for Emacs
Playground lets you try out
.emacs.d configuration repositories.
The basic idea behind Playground is to create an isolated directory called a sandbox and make it
$HOME of Emacs. Playground allows you to easily experiment with various Emacs configuration repositories available on GitHub, while keeping your current configuration untouched (almost, except for stuffs related to Playground). It can also simplify your workflow in Emacs by hiding irrelevant files and directories existing in your home directory.
For details on the mechanism of Playground, see how it works section.
- Two ways to checkout a sandbox: declarative configuration and interactively specifying a Git repository
- Configured with some popular and/or notable Emacs configuration repositories
- Support producing symbolic links for selectively mapping a directory structure between sandboxes and the home directory
- Support producing a wrapper script to replace Emacs for regular use of a sandbox
- Emacs (>= 25.1)
- UNIX-like operating system with a graphical environment (not on terminal)
- On Windows, Playground cannot generate a convenient shell script, but it still allows you to try a configuration
Playground is available on MELPA as
An alternative way is to clone this repository to somewhere and start Emacs using this command:
emacs -Q -l playground.el
Then select a configuration in the minibuffer.
Alternatively, there is also
playground-checkout-with-options command, which allows you to interactively specify detailed options such as a different name of the sandbox or a branch.
These settings are mostly for users who might want to use a sandbox regularly. If you just want to try Emacs configurations for a short period of time, you can skip this section and proceed to Usage.
To add configuration repositories suggested in
Each entry in the variable is a plist. The following keys are supported:
:repo: A Git repository URL to be used as ~/.emacs.d. Required.
:branch: A branch of the repository to check out. Optional, and the default is
:name: A name of the sandbox. This can be any directory name, Optional, and the default is produced from the user name of the repository.
:recursive: Recursively check out submodules in the repository. The default is true, and you can set this to
:depth: Limit the number of commits to fetch. The default is
1(only the latest commit), but you can set this to
nilto get all commits.
Location of wrapper scripts
By default, Playground installs wrapper scripts to
~/.local/bin when you run
playground-persist. If this directory is not included in your
$PATH, you can change the destination by setting
(setq playground-script-directory (expand-file-name "~/bin")) ; Install scripts to ~/bin
By default, Playground creates a symbolic link in sandboxes only for
~/.gnupg. You can produce more symbolic links by setting
(setq playground-inherited-contents '("Dropbox" ".gpg" "git"))
Each item in the list should be a relative path from the home directory. In the above example, the following three symbolic links are created (
~/ is the sandbox context):
These symbolic links are produced when a new sandbox is created. To update the mappings in previously created sandboxes, run
playground-update-symlinks command. This command creates missing symbolic links in existing sandboxes.
The main entry point to using Playground is
playground-checkout command. It allows you to check out a sandbox from the following sources:
- Existing sandboxes that you have checked out on the machine (via selection)
- A predefined list of sandbox configurations (via selection)
- Any Git repository that should be used as
~/.emacs.din the new sandbox context (by typing a URL in the mini buffer)
If you enter a URL, Playground asks you a name for the created sandbox. It can be any file name.
After you specify an existing sandbox or a sandbox configuration in
playground-checkout, Playground initializes the sandbox if it is not created yet and starts Emacs with the sandbox as its home. You can try it. You can also restart the last selected sandbox by
Replacing your Emacs
If you come to like a particular configuration and want to use it regularly, you can make it the default by running
playground-persist command in the parent Emacs session. It creates a wrapper script that effectively replaces your current Emacs configuration. The following is how it works: The script will have the same name as Emacs (normally
emacs), and it starts Emacs in the sandbox environment. Granted that this script is installed into a directory that have a higher precedence in
emacs command will always run Emacs on the sandbox.
In case you occasionally run Emacs in your original environment, Playground also creates
emacs-noplay wrapper script. It starts Emacs on the original directory.
If you don't like the configuration you have set as the default, you can roll back this change by running
playground-return command. The wrapper scripts will be deleted, and Emacs will run on the original home directory in all of its succeeding sessions.
How it works
The fundamental idea for Playground is to start Emacs with
$HOME environment variable set to a different location:
This command line starts Emacs with
/foo/bar as its home directory (
~). Emacs started in this way loads an initialization file from
/foo/bar/.emacs[.el], etc.) rather than from
~USER means the home directory of USER, which is usually
/home/USER). You can use this technique to try a configuration repository created by other people.
This technique causes another effect of 'hiding' a bunch of files and directories located in the original home directory. If you use Emacs alongside other desktop applications, your home directory is likely to contain files that will never be edited or browsed in Emacs. This can be a mess when you use Emacs. However, in an Emacs session in the modified home environment variable,
~ points to
/foo/bar. This applies to every situation inside the modified Emacs session, including caching downloaded packages, locating recent files and backup files, and interactive interfaces like
find-file. The modified home environment virtually serves as a sandbox for Emacs.
Meanwhile, you can still visit files and directories in the original home directory . In
find-file, you can browse files in your original home directory by typing
USER should be your login name) even on the modified environment. The same applies to other commands. You can save typing efforts for specific directories by creating symbolic links from inside the sandbox to corresponding locations in the original home directory, e.g.
~/path in the sandbox to
Playground helps you manage sandboxes of this kind. It creates a sandbox in the following steps:
- Create a new directory inside a fixed location (
~USER/.emacs-playby default). This will become your sandbox, a virtual
- Clone a given Git repository to
~/.emacs.din the sandbox context. You can specify any Git repository as your Emacs configuration for the sandbox.
- Create symbolic links from inside the sandbox to directories in the original home directory. This configuration is done globally, so you can enforce the same structure in all of your sandboxes.