mirrors/dotdrop
1
0
Fork 0
mirror of https://github.com/deadc0de6/dotdrop.git synced 2026-02-09 11:49:14 +00:00
Code Activity

refactor readme

Browse Source
This commit is contained in:
deadc0de6
2018-02-07 16:49:33 +01:00
parent e85235c44f
commit 6b9606b920
1 changed files with 136 additions and 134 deletions
Download Patch File Download Diff File Expand all files Collapse all files

270
README.md
View File

@@ -58,20 +58,20 @@ why dotdrop rocks.
**Table of Contents** **Table of Contents**
* [Installation](#installation) * [Installation](#installation)
* [Config](#config)
* [Usage](#usage) * [Usage](#usage)
* How to
* [Installing dotfiles](#installing-dotfiles) * [Install dotfiles](#install-dotfiles)
* [Diffing your local dotfiles with dotdrop](#diffing-your-local-dotfiles-with-dotdrop) * [Compare dotfiles](#compare-dotfiles)
* [Import new dotfiles](#import-new-dotfiles) * [Import dotfiles](#import-dotfiles)
* [List the available profiles](#list-the-available-profiles) * [List profiles](#list-profiles)
* [List configured dotfiles](#list-configured-dotfiles) * [List dotfiles](#list-dotfiles)
* [Execute an action when deploying a dotfile](#execute-an-action-when-deploying-a-dotfile) * [Use actions](#use-actions)
* [All dotfiles for a profile](#all-dotfiles-for-a-profile) * [Use transformations](#use-transformations)
* [Include dotfiles from another profile](#include-dotfiles-from-another-profile)
* [Update dotdrop](#update-dotdrop) * [Update dotdrop](#update-dotdrop)
* [Update dotfiles](#update-dotfiles) * [Update dotfiles](#update-dotfiles)
* [Storing sensitive dotfiles](#storing-sensitive-dotfiles) * [Store sensitive dotfiles](#store-sensitive-dotfiles)
* [Transformations](#transformations)
* [Template](#template) * [Template](#template)
* [Example](#example) * [Example](#example)
@@ -136,6 +136,103 @@ by `dotdrop` if using the pypi solution.
Finally import your dotfiles as described [below](#usage). Finally import your dotfiles as described [below](#usage).
# Config
The config file (defaults to *config.yaml*) is a yaml file containing
the following entries:
* **config** entry: contains settings for the deployment
* `backup`: create a backup of the dotfile in case it differs from the
one that will be installed by dotdrop
* `create`: create directory hierarchy when installing dotfiles if
it doesn't exist
* `dotpath`: path to the directory containing the dotfiles to be managed
by dotdrop (absolute path or relative to the config file location)
* **dotfiles** entry: a list of dotfiles
* When `link` is true, dotdrop will create a symlink instead of copying. Template generation (as in [template](#template)) is not supported when `link` is true.
* `actions` contains a list of action keys that need to be defined in the **actions** entry below.
```
<dotfile-key-name>:
dst: <where-this-file-is-deployed>
src: <filename-within-the-dotpath>
# Optional
link: <true|false>
actions:
- <action-key>
trans:
- <transformation-key>
```
* **profiles** entry: a list of profiles with the different dotfiles that
need to be managed
* `dotfiles`: the dotfiles associated to this profile
* `include`: include all dotfiles from another profile (optional)
```
<some-name-usually-the-hostname>:
dotfiles:
- <some-dotfile-key-name-defined-above>
- <some-other-dotfile-key-name>
- ...
# Optional
include:
- <some-other-profile>
- ...
```
* **actions** entry: a list of action
```
<action-key>: <command-to-execute>
```
* **trans** entry: a list of transformations
```
<trans-key>: <command-to-execute>
```
## All dotfiles for a profile
To use all defined dotfiles for a profile, simply use
the keyword `ALL`.
For example:
```yaml
dotfiles:
f_xinitrc:
dst: ~/.xinitrc
src: xinitrc
f_vimrc:
dst: ~/.vimrc
src: vimrc
profiles:
host1:
dotfiles:
- ALL
host2:
dotfiles:
- f_vimrc
```
## Include dotfiles from another profile
If one profile is using the entire set of another profile, one can use
the `include` entry to avoid redundancy.
For example:
```yaml
profiles:
host1:
dotfiles:
- f_xinitrc
include:
- host2
host2:
dotfiles:
- f_vimrc
```
Here profile *host1* contains all the dotfiles defined for *host2* plus `f_xinitrc`.
# Usage # Usage
If starting fresh, the `import` command of dotdrop If starting fresh, the `import` command of dotdrop
@@ -225,62 +322,7 @@ Options:
For easy deployment the default profile used by dotdrop reflects the For easy deployment the default profile used by dotdrop reflects the
hostname of the host on which it runs. hostname of the host on which it runs.
## Config file details ## Install dotfiles
The config file (defaults to *config.yaml*) is a yaml file containing
the following entries:
* **config** entry: contains settings for the deployment
* `backup`: create a backup of the dotfile in case it differs from the
one that will be installed by dotdrop
* `create`: create directory hierarchy when installing dotfiles if
it doesn't exist
* `dotpath`: path to the directory containing the dotfiles to be managed
by dotdrop (absolute path or relative to the config file location)
* **dotfiles** entry: a list of dotfiles
* When `link` is true, dotdrop will create a symlink instead of copying. Template generation (as in [template](#template)) is not supported when `link` is true.
* `actions` contains a list of action keys that need to be defined in the **actions** entry below.
```
<dotfile-key-name>:
dst: <where-this-file-is-deployed>
src: <filename-within-the-dotpath>
# Optional
link: <true|false>
actions:
- <action-key>
trans:
- <transformation-key>
```
* **profiles** entry: a list of profiles with the different dotfiles that
need to be managed
* `dotfiles`: the dotfiles associated to this profile
* `include`: include all dotfiles from another profile (optional)
```
<some-name-usually-the-hostname>:
dotfiles:
- <some-dotfile-key-name-defined-above>
- <some-other-dotfile-key-name>
- ...
# Optional
include:
- <some-other-profile>
- ...
```
* **actions** entry: a list of action
```
<action-key>: <command-to-execute>
```
* **trans** entry: a list of transformations
```
<trans-key>: <command-to-execute>
```
## Installing dotfiles
Simply run Simply run
```bash ```bash
@@ -290,7 +332,7 @@ $ dotdrop.sh install
Use the `--profile` switch to specify a profile if not using Use the `--profile` switch to specify a profile if not using
the host's hostname. the host's hostname.
## Diffing your local dotfiles with dotdrop ## Compare dotfiles
Compare local dotfiles with dotdrop's defined ones: Compare local dotfiles with dotdrop's defined ones:
```bash ```bash
@@ -300,7 +342,7 @@ $ dotdrop.sh compare
The diffing is done by diff in the backend, one can provide specific The diffing is done by diff in the backend, one can provide specific
options to diff using the `-o` switch. options to diff using the `-o` switch.
## Import new dotfiles ## Import dotfiles
Dotdrop allows to import dotfiles directly from the Dotdrop allows to import dotfiles directly from the
filesystem. It will copy the dotfile and update the filesystem. It will copy the dotfile and update the
@@ -312,7 +354,7 @@ $ dotdrop.sh import ~/.xinitrc
``` ```
## List the available profiles ## List profiles
```bash ```bash
$ dotdrop.sh list $ dotdrop.sh list
@@ -322,7 +364,7 @@ Dotdrop allows to choose which profile to use
with the *--profile* switch if you use something with the *--profile* switch if you use something
else than the default (the hostname). else than the default (the hostname).
## List configured dotfiles ## List dotfiles
The following command lists the different dotfiles The following command lists the different dotfiles
configured for a specific profile: configured for a specific profile:
@@ -341,7 +383,7 @@ f_dunstrc (file: "config/dunst/dunstrc", link: False)
-> ~/.config/dunst/dunstrc -> ~/.config/dunst/dunstrc
``` ```
## Execute an action when deploying a dotfile ## Use actions
It is sometimes useful to execute some kind of action It is sometimes useful to execute some kind of action
when deploying a dotfile. For example let's consider when deploying a dotfile. For example let's consider
@@ -373,47 +415,35 @@ Thus when `f_vimrc` is installed, the command
`vim +VundleClean! +VundleInstall +VundleInstall! +qall` will `vim +VundleClean! +VundleInstall +VundleInstall! +qall` will
be executed. be executed.
## All dotfiles for a profile ## Use transformations
To use all defined dotfiles for a profile, simply use Transformation actions are used to transform a dotfile before it is
the keyword `ALL`. installed. They work like [actions](#use-actions) but have two arguments:
* **{0}** will be replaced with the dotfile to process
* **{1}** will be replaced with a temporary file to store the result
A typical use-case for transformations is when the dotfile needs to be
stored encrypted.
For example: For example:
```yaml
the transformation and the dotfile in `config.yaml`:
```
dotfiles: dotfiles:
f_xinitrc: f_secret:
dst: ~/.xinitrc dst: ~/.secret
src: xinitrc src: secret
f_vimrc: trans:
dst: ~/.vimrc - gpg
src: vimrc trans:
profiles: gpg: gpg2 -q --for-your-eyes-only --no-tty -d {0} > {1}
host1:
dotfiles:
- ALL
host2:
dotfiles:
- f_vimrc
``` ```
## Include dotfiles from another profile The above config allows to store the dotfile `~/.secret` encrypted in the *dotfiles*
directory and uses gpg to decrypt it when install is run.
If one profile is using the entire set of another profile, one can use
the `include` entry to avoid redundancy.
For example:
```yaml
profiles:
host1:
dotfiles:
- f_xinitrc
include:
- host2
host2:
dotfiles:
- f_vimrc
```
Here profile *host1* contains all the dotfiles defined for *host2* plus `f_xinitrc`.
## Update dotdrop ## Update dotdrop
@@ -446,39 +476,11 @@ There are two cases:
$ dotdrop.sh update ~/.vimrc $ dotdrop.sh update ~/.vimrc
``` ```
## Storing sensitive dotfiles ## Store sensitive dotfiles
Two solutions exist, the first one using an unversioned file (see [Environment variables](#Environment variables)) Two solutions exist, the first one using an unversioned file (see [Environment variables](#environment-variables))
and the second using transformation actions (see [Transformations](#transformations)). and the second using transformation actions (see [Transformations](#transformations)).
## Transformations
Transformation actions are used to transform a dotfile before it is
installed. They work like actions but have two arguments:
* **{0}** will be replaced with the dotfile to process
* **{1}** will be replaced with a temporary file to store the result
A typical use-case for transformations is when the dotfile needs to be
stored encrypted.
For example:
the transformation and the dotfile in `config.yaml`:
```
dotfiles:
f_secret:
dst: ~/.secret
src: secret
trans:
- gpg
trans:
gpg: gpg2 -q --for-your-eyes-only --no-tty -d {0} > {1}
```
The above config allows to store the dotfile `~/.secret` encrypted in the *dotfiles*
directory.
# Template # Template
Dotdrop leverage the power of [jinja2](http://jinja.pocoo.org/) to handle the Dotdrop leverage the power of [jinja2](http://jinja.pocoo.org/) to handle the