From 18cd41e7277c82e66bc9f5ca5d0b38b606127c23 Mon Sep 17 00:00:00 2001 From: syl20bnr Date: Tue, 25 Nov 2014 22:28:13 -0500 Subject: [PATCH] Add documentation about private layers management --- DOCUMENTATION.md | 36 ++++++++++++++++++++++++++++++++++++ README.md | 15 +++++++++++++-- 2 files changed, 49 insertions(+), 2 deletions(-) diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md index 201762e22..1f2c1aa9c 100644 --- a/DOCUMENTATION.md +++ b/DOCUMENTATION.md @@ -21,6 +21,10 @@ - [Types of configuration layers](#types-of-configuration-layers) - [Submitting a configuration layer upstream](#submitting-a-configuration-layer-upstream) - [Example: Themes Megapack example](#example-themes-megapack-example) + - [Managing private configuration layers](#managing-private-configuration-layers) + - [Using the private directory](#using-the-private-directory) + - [Using an external Git repository](#using-an-external-git-repository) + - [Using a personal branch](#using-a-personal-branch) - [Dotfile Configuration](#dotfile-configuration) - [Installation](#installation) - [Content](#content) @@ -41,6 +45,7 @@ - [Mode-line](#mode-line) - [Flycheck integration](#flycheck-integration) - [Anzu integration](#anzu-integration) + - [Battery status integration](#battery-status-integration) - [Powerline separators](#powerline-separators) - [Minor Modes](#minor-modes) - [Base packages](#base-packages) @@ -325,6 +330,37 @@ you can find it [here][themes-megapack]. To install it, just add `themes-megapack` to your `~/.spacemacs`. You have now installed around 100 themes you are free to try with ` h t` (helm-themes). +## Managing private configuration layers + +`Spacemacs` configuration system is flexible enough to let you manage your +private layers in different ways. + +### Using the private directory + +Everything in the private directory is ignored by Git so it is a good place +to store private layers. There is a huge drawback to this approach though: +_your layers are not source controlled_. + +### Using an external Git repository + +This is the recommended way to manage your private layers. + +The best approach is to store all your private layers into an external Git +repository. It is especially a good practice to store them in your `dotfiles` +repository if you have one along with your `~/.spacemacs` file. + +Then you are free to symlink your layers into `~/emacs.d/private` _or_ let +them anywhere you want and reference the parent directory in the variable +`dotspacemacs-configuration-layer-path` of your `~/.spacemacs`. + +Note that you could also have a dedicated repository for all your private +layers and then directly clone this repository in `~/.emacs.d/private`. + +### Using a personal branch + +The final main way to manage your private layers is to push them is a personal +branch that you keep up to date with upstream `master` or `develop`. + # Dotfile Configuration User configuration can be stored in your `~/.spacemacs` file. diff --git a/README.md b/README.md index a666c7121..a239535f2 100644 --- a/README.md +++ b/README.md @@ -124,11 +124,21 @@ configuration layer: : config-system/create-layer RET After entering a name, a layer skeleton will be created in the [private][] -directory. The `private` directory is ignored by Git. +directory where you'll find the following files: +- `packages.el` to list the elpa packages +- `exentsions.el` for any other package that is not available in a elpa +repository. + +The `private` directory is ignored by Git. To use your newly created configuration layer, add it to your `~/.spacemacs` file (see next section). +Note that this approach leaves your layer not source controlled. To get more +info on the different approaches to manage your layers, refer to the +[Managing private configuration layers][manage_config] section of the +documentation. + ## Dotfile ~/.spacemacs `Spacemacs` has a convenient dotfile. You have to install it by invoking the @@ -187,7 +197,8 @@ first. [screenshots]: https://github.com/syl20bnr/spacemacs/blob/master/DOCUMENTATION.md#screenshots [config]: https://github.com/syl20bnr/spacemacs/blob/master/DOCUMENTATION.md#configuration-layers [dotfile]: https://github.com/syl20bnr/spacemacs/blob/master/DOCUMENTATION.md#dotfile-configuration -[achievements]: https://github.com/syl20bnr/spacemacs/blob/master/DOCUMENTATION.md#achievements +[manage_config]: https://github.com/syl20bnr/spacemacs/blob/master/DOCUMENTATION.md#managing-private-configuration-layers +[achievements]: https://github.com/syl20bnr/spacemacs/blob/master/DOCUMENTATION.md#achievements [troubleshoot]: https://github.com/syl20bnr/spacemacs/blob/master/DOCUMENTATION.md#troubleshoot [contrib layers]: https://github.com/syl20bnr/spacemacs/blob/master/DOCUMENTATION.md#using-configuration-layers [Git support]: https://github.com/syl20bnr/spacemacs/blob/master/DOCUMENTATION.md#working-with-git