mirrors/dotdrop
1
0
Fork 0
mirror of https://github.com/deadc0de6/dotdrop.git synced 2026-02-04 18:34:48 +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**
* [Installation](#installation)
* [Config](#config)
* [Usage](#usage)
* How to
* [Installing dotfiles](#installing-dotfiles)
* [Diffing your local dotfiles with dotdrop](#diffing-your-local-dotfiles-with-dotdrop)
* [Import new dotfiles](#import-new-dotfiles)
* [List the available profiles](#list-the-available-profiles)
* [List configured dotfiles](#list-configured-dotfiles)
* [Execute an action when deploying a dotfile](#execute-an-action-when-deploying-a-dotfile)
* [All dotfiles for a profile](#all-dotfiles-for-a-profile)
* [Include dotfiles from another profile](#include-dotfiles-from-another-profile)
* [Install dotfiles](#install-dotfiles)
* [Compare dotfiles](#compare-dotfiles)
* [Import dotfiles](#import-dotfiles)
* [List profiles](#list-profiles)
* [List dotfiles](#list-dotfiles)
* [Use actions](#use-actions)
* [Use transformations](#use-transformations)
* [Update dotdrop](#update-dotdrop)
* [Update dotfiles](#update-dotfiles)
* [Storing sensitive dotfiles](#storing-sensitive-dotfiles)
* [Transformations](#transformations)
* [Store sensitive dotfiles](#store-sensitive-dotfiles)
* [Template](#template)
* [Example](#example)
@@ -136,6 +136,103 @@ by `dotdrop` if using the pypi solution.
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
If starting fresh, the `import` command of dotdrop
@@ -225,62 +322,7 @@ Options:
For easy deployment the default profile used by dotdrop reflects the
hostname of the host on which it runs.
## Config file details
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
## Install dotfiles
Simply run
```bash
@@ -290,7 +332,7 @@ $ dotdrop.sh install
Use the `--profile` switch to specify a profile if not using
the host's hostname.
## Diffing your local dotfiles with dotdrop
## Compare dotfiles
Compare local dotfiles with dotdrop's defined ones:
```bash
@@ -300,7 +342,7 @@ $ dotdrop.sh compare
The diffing is done by diff in the backend, one can provide specific
options to diff using the `-o` switch.
## Import new dotfiles
## Import dotfiles
Dotdrop allows to import dotfiles directly from 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
$ dotdrop.sh list
@@ -322,7 +364,7 @@ Dotdrop allows to choose which profile to use
with the *--profile* switch if you use something
else than the default (the hostname).
## List configured dotfiles
## List dotfiles
The following command lists the different dotfiles
configured for a specific profile:
@@ -341,7 +383,7 @@ f_dunstrc (file: "config/dunst/dunstrc", link: False)
-> ~/.config/dunst/dunstrc
```
## Execute an action when deploying a dotfile
## Use actions
It is sometimes useful to execute some kind of action
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
be executed.
## All dotfiles for a profile
## Use transformations
To use all defined dotfiles for a profile, simply use
the keyword `ALL`.
Transformation actions are used to transform a dotfile before it is
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:
```yaml
the transformation and the dotfile in `config.yaml`:
```
dotfiles:
f_xinitrc:
dst: ~/.xinitrc
src: xinitrc
f_vimrc:
dst: ~/.vimrc
src: vimrc
profiles:
host1:
dotfiles:
- ALL
host2:
dotfiles:
- f_vimrc
f_secret:
dst: ~/.secret
src: secret
trans:
- gpg
trans:
gpg: gpg2 -q --for-your-eyes-only --no-tty -d {0} > {1}
```
## 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
@@ -446,39 +476,11 @@ There are two cases:
$ 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)).
## 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
Dotdrop leverage the power of [jinja2](http://jinja.pocoo.org/) to handle the