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

Proofread docs

Browse Source
This commit is contained in:
John T. Wodder II
2021-10-05 12:14:42 -04:00
parent 2c7ac514e0
commit 60550424ca
27 changed files with 624 additions and 631 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/howto/append.md
View File

@@ -23,9 +23,9 @@ actions:
post:
append: "cat {0} >> {1}; rm -f {0}"
```
During installation, the `strip` action is executed before the installation and strips everything from the pattern `# my pattern` to the end of the file. Then the dotfile `somefile` is installed in a temporary location (here `tmpfile`) and finally the post action `append` will append the content of the `tmpfile` to the final dotfile pointed by `somefile_final`
During installation, the `strip` action is executed before the installation, and it strips everything from the pattern `# my pattern` to the end of the file. Then the dotfile `somefile` is installed in a temporary location (here `tmpfile`) and finally the post action `append` will append the contents of the `tmpfile` to the final dotfile pointed to by `somefile_final`.
Obviously the dotfile in the dotpath should start with a unique pattern (here `# my pattern`):
Obviously, the dotfile in the dotpath should start with a unique pattern (here `# my pattern`):
```
# my pattern
this is the end

20
docs/howto/create-special-files.md
View File

@@ -1,9 +1,9 @@
# Create files on install
One way for creating symlinks (or any other special files) is to use a combination of
One way to create symlinks (or any other special file) is to use a combination of
[actions](../config-details.md#entry-actions) and a *fake* dotfile.
Let's say for example you have a list of directories you want to link
Let's say, for example, you have a list of directories you want to link
from under `~/.original` to `~/symlinks`.
```bash
$ tree ~/.original
@@ -13,19 +13,19 @@ $ tree ~/.original
└── dir3
```
First you would store these directories names in a text file in your `<dotpath>/links.txt`
First you would store these directory names in a text file in your `<dotpath>/links.txt`:
```
dir1
dir2
dir3
```
The config file would contain different elements
The config file would contain different elements:
* a `dynvariables` that will read the above text file
* a few `variables` for the source and destination
* an action that will create the destination directory and symlink those directories
* a *fake* dotfile (with no `src` and no `dst` values) that will be always installed with the above action
* A `dynvariables` that will read the above text file
* A few `variables` for the source and destination
* An action that will create the destination directory and symlink those directories
* A *fake* dotfile (with no `src` and no `dst` values) that will be always installed with the above action
```yaml
dynvariables:
@@ -45,7 +45,7 @@ actions:
- symlink_them '{{@@ links_list @@}}' '{{@@ links_dst @@}}'
```
The result would be
The result would be:
```bash
$ tree ~/.symlinks
/home/user/.symlinks
@@ -54,4 +54,4 @@ $ tree ~/.symlinks
└── dir3 -> /home/user/.original/dir3
```
For reference, see [issue 243](https://github.com/deadc0de6/dotdrop/issues/243)
For reference, see [issue 243](https://github.com/deadc0de6/dotdrop/issues/243).

10
docs/howto/howto.md
View File

@@ -1,4 +1,4 @@
# HowTo
# How To
## Append text to a dotfile on install
@@ -20,13 +20,13 @@
[Handle special chars](special-chars.md)
## Improve git integration
## Improve Git integration
[Improve git integration](improve-git-integration.md)
[Improve Git integration](improve-git-integration.md)
## Include file or template in template
## Include files or templates in templates
[Include file or template in template](include-in-template.md)
[Include files or templates in templates](include-in-template.md)
## Manage system dotfiles

6
docs/howto/improve-git-integration.md
View File

@@ -1,6 +1,6 @@
# Improve git integration
# Improve Git integration
The below aliases can help with the process of updating your dotfiles between multiple hosts. Add those to your `~/.zshrc` or `~/.bashrc`. You can then simply run `dotsync` to push or pull from your dotfile repository.
The below aliases can help with the process of updating your dotfiles between multiple hosts. Add them to your `~/.zshrc` or `~/.bashrc`. You can then simply run `dotsync` to push or pull from your dotfile repository.
```
# Your dotdrop git repository location
@@ -11,4 +11,4 @@ alias dotgit="git -C $DOTREPO"
alias dotsync="dotgit pull && dotgit add -A && dotgit commit && dotgit push; dotdrop install"
```
Provided by [ReekyMarko](https://github.com/ReekyMarko)
Provided by [ReekyMarko](https://github.com/ReekyMarko).

4
docs/howto/include-in-template.md
View File

@@ -1,6 +1,6 @@
# Include file or template in template
# Include files or templates in templates
[Jinja2](https://jinja.palletsprojects.com/en/2.11.x/templates/) provides the ability to include an external file/template from within a template with the directive `include`. See the [related doc](https://jinja.palletsprojects.com/en/2.11.x/templates/#include) for more. The path must be relative to the `dotpath`.
[Jinja2](https://jinja.palletsprojects.com/en/2.11.x/templates/) provides the ability to include an external file/template from within a template with the directive `include`. See the [related docs](https://jinja.palletsprojects.com/en/2.11.x/templates/#include) for more. The path must be relative to the `dotpath`.
For example:
```yaml

14
docs/howto/merge-files-when-installing.md
View File

@@ -1,14 +1,14 @@
# Merge files on install
Dotdrop allows to merge multiple files into one using the jinja2's `include` directive.
Dotdrop allows you to merge multiple files into one using Jinja2's `include` directive.
For example let's consider you want to keep your `vimrc` split into multiple parts in dotdrop
For example, let's assume you want to keep your `.vimrc` split into multiple parts in dotdrop:
* `<dotpath>/vimrc.d/top`: top part of the file
* `<dotpath>/vimrc.d/bottom`: bottom part of the file
And you want dotdrop to merge all those files into `~/.vimrc` whenever you process your vimrc with dotdrop.
And you want dotdrop to merge all those files into `~/.vimrc` whenever you process your .vimrc with dotdrop.
First make sure `~/.vimrc` is present in your config file
First make sure `~/.vimrc` is present in your config file:
```yaml
...
dotfiles:
@@ -49,7 +49,7 @@ Dotdrop will then automagically include the files into your vimrc when handling
To include all files in a directory, a combination of
[dynvariables](../config-details.md#entry-dynvariables)
and [jinja2 directives](https://jinja.palletsprojects.com/en/2.11.x/) have to be used.
and [Jinja2 directives](https://jinja.palletsprojects.com/en/2.11.x/) have to be used.
Let's say all files in `<dotpath>/toinclude` need to be included into a dotfile.
@@ -61,9 +61,9 @@ dynvariables:
```
Note that `_dotdrop_dotpath` is part of the built-in variables
(for more see [template variables](../templating.md#template-variables)).
(For more, see [template variables](../templating.md#template-variables)).
And then use the generated list in the dotfile template:
Then use the generated list in the dotfile template:
```
{%@@ for f in allfiles.split() @@%}
{%@@ include f @@%}

2
docs/howto/prompt-user-for-variables.md
View File

@@ -8,7 +8,7 @@ The provided values are then automatically saved by dotdrop to `uservariables.ya
which can be included in the main config as a file from which variables are imported
using [import_variables](../config-details.md#entry-import_variables).
Let's say for example that you want to provide manually the email value
Let's say, for example, that you want to manually provide the email value
on new hosts you deploy your dotfiles to.
You'd add the following elements to your config:

16
docs/howto/sensitive-dotfiles.md
View File

@@ -19,33 +19,33 @@ trans_read:
_gpg: gpg2 -q --for-your-eyes-only --no-tty -d {0} > {1}
```
The above config allows to store the dotfile `~/.secret` encrypted in the *dotpath*
The above config allows you to store the dotfile `~/.secret` encrypted in the *dotpath*
directory and uses gpg to decrypt it when `install` is run.
Here's how to deploy above solution:
Here's how to deploy the above solution:
* import the clear dotfile (what creates the correct entries in the config file)
* Import the clear dotfile (what creates the correct entries in the config file):
```bash
$ dotdrop import ~/.secret
```
* encrypt the original dotfile
* Encrypt the original dotfile:
```bash
$ <some-gpg-command> ~/.secret
```
* overwrite the dotfile with the encrypted version
* Overwrite the dotfile with the encrypted version:
```bash
$ cp <encrypted-version-of-secret> dotfiles/secret
```
* edit the config file and add the transformation to the dotfile
* Edit the config file and add the transformation to the dotfile
(as shown in the example above)
* commit and push the changes
* Commit and push the changes
See [transformations](../config-details.md#entry-transformations).
@@ -59,7 +59,7 @@ trans_read:
_gpg: "gpg2 --batch --yes --passphrase-file <({{@@ gpg_password @@}}) -q --for-your-eyes-only --no-tty -d {0} > {1}"
```
Passphrase is stored in a file directly
Passphrase is stored in a file directly:
```yaml
variables:
gpg_password_file: "/tmp/the-password"

41
docs/howto/sharing-content.md
View File

@@ -3,9 +3,9 @@
There are cases in which two or more dotfiles are very similar. For example,
two files exporting environment variables for two projects built with the same
technology (eg. two node.js web servers deployed on AWS). In these cases it's
nice to share as much code as possible across the dotfiles, by leveraging
templating and merging them in the same dotfile in Dotdrop's `dotpath`. Here
are a few suggestions about how to achieve this.
nice to share as much code as possible across the dotfiles by leveraging
templating and merging them into the same dotfile in dotdrop's `dotpath`. Here
are a few suggestions about how to achieve this:
* [Brute force templating](#brute-force-templating)
* [Profile variables](#profile-variables)
@@ -13,7 +13,7 @@ are a few suggestions about how to achieve this.
## Brute force templating
The first approach is sheer use of templating and variables
The first approach is sheer use of templating and variables.
In order to do this, we need to:
1. Create the merged dotfile with an arbitrary name somewhere in `dotpath`.
@@ -38,7 +38,7 @@ export DB_HOST='{{@@ aws_db_host @@}}'
export DB_PORT='{{@@ aws_db_port @@}}'
```
Part of Dotdrop `config.yaml` file:
Part of dotdrop `config.yaml` file:
```yaml
# config.yaml
@@ -63,9 +63,9 @@ export DB_PORT='4521'
## Profile variables
Albeit flexible, the previous method is a bit cumbersome for some use cases.
The previous method, albeit flexible, is a bit cumbersome for some use cases.
For example, when the dotfiles belong to different profiles, the cleanest
solution consists in using
solution consists of using
[profile variables](../config-details.md#entry-profile-variables). This is achieved by:
1. Creating the merged dotfile with an arbitrary name somewhere in `dotpath`.
@@ -79,7 +79,7 @@ solution consists in using
An example:
The merged dotfile (`dotpath/projects/env`)
The merged dotfile (`dotpath/projects/env`):
```bash
# .env
@@ -87,7 +87,7 @@ export DB_HOST='{{@@ aws_db_host @@}}'
export DB_PORT='{{@@ aws_db_port @@}}'
```
Part of Dotdrop `config.yaml` file:
Part of dotdrop `config.yaml` file:
```yaml
# config.yaml
@@ -128,26 +128,26 @@ export DB_PORT='9632'
Even though it has cleaner dotfiles, the profile-variable-based procedure can't
be used in two scenarios: when the dotfiles belong to the same profile, and
when variable values require some complex computations. In both cases the brute
when variable values require some complex computations. In both cases, the brute
force templating approach can be used, but in the latter one it also makes the
dotfiles bloated with "bookkeeping" logic, thus hard to read.
A solution for this relies in leveraging Jinja macros. This method is a
variation of the brute force templating one, where the merged dotfile is
included from many different dotfiles in `dotpath` via jinja macros, rather
variation of the brute force templating one where the merged dotfile is
included from many different dotfiles in `dotpath` via Jinja macros rather
than via many `dotfile` entries with the same `src` attribute. This way, the
merged original dotfiles stays clean as in the profile variables solution,
merged original dotfiles stays clean as in the profile variables solution
because computations are in other files.
The steps to achieve this are:
1. Creating the merged dotfile with an arbitrary name somewhere in `dotpath`.
2. Wrapping the whole content of the merged dotfile in a jinja macro, with the
2. Wrapping the whole content of the merged dotfile in a Jinja macro with the
necessary parameters.
3. Calling the macro in each original dotfiles, computing the parameters there.
3. Calling the macro in each original dotfile, computing the parameters there.
**NOTE**: The merged dotfile will be empty, as it only contains a jinja macro.
If it needs not to be deployed, the `ignoreempty` entry can be set to
**NOTE**: The merged dotfile will be empty, as it only contains a Jinja macro.
If it needs to not be deployed, the `ignoreempty` entry can be set to
`true` in `config.yaml`.
As usual, an example:
@@ -162,7 +162,7 @@ export DB_PORT='{{@@ db_port @@}}'
{%@@ endmacro @@%}
```
Server0's environment file (`projects/server0/.env`)
Server0's environment file (`projects/server0/.env`):
```jinja2
{%@@ from projects/env import env @@%}
@@ -182,14 +182,14 @@ Server0's environment file (`projects/server0/.env`)
{{@@ env(db_host, db_port) @@}}
```
Server1's environment file (`projects/server1/.env`)
Server1's environment file (`projects/server1/.env`):
```jinja2
{%@@ from projects/env import env @@%}
{{@@ env('average-host.com', 9632) @@}}
```
Part of Dotdrop `config.yaml` file:
Part of dotdrop `config.yaml` file:
```yaml
# config.yaml
@@ -203,7 +203,6 @@ dotfiles:
server1-env:
src: projects/server1/.env
dst: ~/projects/server1/.env
```
With this configuration, installing the dotfile `server0-env-local-dbg` will

17
docs/howto/special-chars.md
View File

@@ -8,8 +8,8 @@
## Detect encoding
Text file encoding can be identified using for example `file -b <file-path>` or in vim
with `:set fileencoding`
Text file encoding can be identified using, for example, `file -b <file-path>` or in vim
with `:set fileencoding`.
Here's an example of encoding that will fully work with dotdrop:
```bash
@@ -27,19 +27,20 @@ ISO-8859 text, with escape sequences
### CRLF
The use of dotfiles with DOS/Windows line ending (CRLF, `\r\n`) will result in
the comparison (`compare`) returning a difference while there is none.
The use of dotfiles with DOS/Windows line endings (CRLF, `\r\n`) will result in
the comparison (`compare`) returning a difference where there is none.
This is due to Jinja2 stripping CRLF.
One solution is to use `dos2unix` to re-format the dotfiles before adding them to dotdrop.
One solution is to use `dos2unix` to re-format the dotfiles before adding them
to dotdrop.
See <https://github.com/deadc0de6/dotdrop/issues/42>.
### Non-unicode chars
### Non-Unicode chars
Jinja2 is not able to process non-unicode chars (<https://jinja.palletsprojects.com/en/2.11.x/api/>). This means that dotfiles using non-unicode chars can still be fully managed by dotdrop however when comparing the local file with the one stored in dotdrop, `compare` will return a difference even if there is none.
Jinja2 is not able to process non-Unicode chars (<https://jinja.palletsprojects.com/en/2.11.x/api/>). This means that dotfiles using non-Unicode chars can still be fully managed by dotdrop; however, when comparing the local file with the one stored in dotdrop, `compare` will return a difference even if there is none.
Either replace the non-unicode chars (see below [Re-encode](#re-encode)) or accept the fact the comparison shows a difference while there's none.
Either replace the non-Unicode chars (see below [Re-encode](#re-encode)) or accept the fact the comparison shows a difference while there's none.
See <https://github.com/deadc0de6/dotdrop/issues/42>.

8
docs/howto/store-compressed-directories.md
View File

@@ -1,6 +1,6 @@
# Handle compressed directories
This is an example on how to use transformations (`trans_read` and `trans_write`) to store
This is an example of how to use transformations (`trans_read` and `trans_write`) to store
compressed directories and deploy them with dotdrop.
Config file:
@@ -25,12 +25,12 @@ profiles:
- d_somedir
```
The *read* transformation `uncompress` is used to execute below command before deploying the dotfile (where `{0}` is the source and `{1}` the destination)
The *read* transformation `uncompress` is used to execute the below command before deploying the dotfile (where `{0}` is the source and `{1}` the destination):
```
mkdir -p {1} && tar -xf {0} -C {1}
```
And the *write* transformation `compress` is run when updating the dotfile directory by compressing it (where `{0}` is the source and `{1}` the destination)
And the *write* transformation `compress` is run when updating the dotfile directory by compressing it (where `{0}` is the source and `{1}` the destination):
```
tar -cf {1} -C {0} .
```
```

50
docs/howto/symlink-dotfiles.md
View File

@@ -1,34 +1,34 @@
# Symlink dotfiles
Dotdrop offers two ways to symlink a dotfile through its
config entry `link`
config entry `link`:
* setting `link: link` for a dotfile will symlink `dst` to `src`
* setting `link: link_children` will, for every direct children of `src`, symlink `dst/<childrenX>` to `src/<childrenX>` (see [Link children](#link-children))
* Setting `link: link` for a dotfile will symlink `dst` to `src`
* Setting `link: link_children` will, for every direct child of `src`, symlink `dst/<childrenX>` to `src/<childrenX>` (See [Link children](#link-children))
Where `src` is considered as the file stored in your *dotpath* and
`dst` as the file located in your `$HOME`.
where `src` is the file stored in your *dotpath* and
`dst` is the file located in your `$HOME`.
Note that if the dotfile is using template directives, it will be symlinked into
Note that if the dotfile uses template directives, it will be symlinked into
`~/.config/dotdrop` instead of directly into your *dotpath*
(see [Templating symlinked dotfiles](#templating-symlinked-dotfiles))
Although the config entries `link_on_import` and `link_dotfile_default` can be set to the value `link_children`,
it is not recommended since operations on a dotfile that is not a directory with the option `link_children`
it is not recommended, since operations on a dotfile that is not a directory with the option `link_children`
will fail.
## Symlink a dotfile
Below is the ad-hoc way when [link_dotfile_default](https://dotdrop.readthedocs.io/en/latest/config-format/#config-entry)
Below is an ad-hoc way to symlink a dotfile when [link_dotfile_default](https://dotdrop.readthedocs.io/en/latest/config-format/#config-entry)
and [link_on_import](https://dotdrop.readthedocs.io/en/latest/config-format/#config-entry) use their default values.
import the file
Import the file:
```bash
$ ./dotdrop.sh import ~/.bashrc
-> "/home/user/.bashrc" imported
```
edit the `config.yaml` and set the `link` value to `link`
Edit the `config.yaml` and set the `link` value to `link`:
```yaml
dotfiles:
f_bashrc:
@@ -37,7 +37,7 @@ dotfiles:
link: link
```
install the dotfile what will remove your `~/.bashrc` and replace it with a link to the file stored in dotdrop
Install the dotfile, which will remove your `~/.bashrc` and replace it with a link to the file stored in dotdrop:
```bash
$ ./dotdrop.sh install
Remove "/home/user/.bashrc" for link creation? [y/N] ? y
@@ -46,7 +46,7 @@ Remove "/home/user/.bashrc" for link creation? [y/N] ? y
1 dotfile(s) installed.
```
The dotfile then points to the file in dotdrop
The dotfile then points to the file in dotdrop:
```bash
$ readlink ~/.bashrc
/home/user/dotdrop/dotfiles/bashrc
@@ -55,16 +55,16 @@ $ readlink ~/.bashrc
## Link children
The `link_children` option can be very useful for dotfiles when you don't want the entire
directory to be symlink but still want to keep a clean config files (with a
directory to be symlinked but still want to keep a clean config file (with a
limited number of entries).
This option set on a file that is not a directory will make any operation on the dotfile fail.
Setting this option on a file that is not a directory will make any operation on the dotfile fail.
*Make sure to do a backup of your dotfiles with something like `cp -r <my-important-dotfile>{,.bak}`*
*Make sure to do a backup of your dotfiles with something like `cp -r <my-important-dotfile>{,.bak}`.*
A good example of its use is when managing `~/.vim` with dotdrop.
Here's what it looks like when using `link: link`.
Here's what it looks like when using `link: link`:
```yaml
config:
dotpath: dotfiles
@@ -75,7 +75,7 @@ dotfiles:
link: link
```
The top directory `~/.vim` is symlinked to the `<dotpath>/vim` location
The top directory `~/.vim` is symlinked to the `<dotpath>/vim` location:
```bash
$ readlink ~/.vim
~/.dotfiles/vim/
@@ -84,12 +84,12 @@ after autoload plugged plugin snippets spell swap vimrc
```
As a result, all files under `~/.vim` will be managed by
dotdrop (including unwanted directories like `spell`, `swap`, etc).
dotdrop (including unwanted directories like `spell`, `swap`, etc.).
A cleaner solution is to use `link_children` which allows to only symlink
A cleaner solution is to use `link_children` which allows you to only symlink
files under the dotfile directory. Let's say only `after`, `plugin`, `snippets`, and `vimrc`
need to be managed in dotdrop. `~/.vim` is imported in dotdrop, cleaned off all unwanted
files/directories and then the `link` entry is set to `link_children` in the config file.
need to be managed in dotdrop. `~/.vim` is imported in dotdrop and cleaned of all unwanted
files/directories, and then the `link` entry is set to `link_children` in the config file:
```yaml
config:
dotpath: dotfiles
@@ -120,15 +120,15 @@ $ tree -L 1 ~/.vim
## Templating symlinked dotfiles
For dotfiles not using any templating directives, those are directly linked
Dotfiles not using any templating directives are directly linked
to dotdrop's `dotpath` directory (see [Config](../config.md)).
When using templating directives however the dotfiles are first installed into
`workdir` (defaults to *~/.config/dotdrop*, see [Config](../config.md))
When using templating directives, however, the dotfiles are first installed into
`workdir` (defaults to *~/.config/dotdrop*; see [Config format](../config-format.md))
and then symlinked there.
This applies to both dotfiles with `link: link` and `link: link_children`.
For example
For example:
```bash
# with template
/home/user/.xyz -> /home/user/.config/dotdrop/.xyz

14
docs/howto/system-config-files.md
View File

@@ -1,18 +1,18 @@
# Manage system dotfiles
Dotdrop doesn't allow to handle file owernership (at least not directly). Every file operations (create/copy file/directory, create symlinks, etc) are executed with the rights of the user calling dotdrop.
Dotdrop doesn't allow you to handle file owernership (at least not directly). Every file operation (create/copy file/directory, create symlinks, etc.) is executed with the rights of the user calling dotdrop.
Using dotdrop with `sudo` to unprivileged and privileged files in the same *session* is a bad idea as the resulting files will all have messed up owners.
Using dotdrop with `sudo` to manage unprivileged and privileged files in the same *session* is a bad idea as the resulting files will all have messed-up owners.
It is therefore recommended to have two different config files (and thus two different *dotpath*)
It is therefore recommended to have two different config files (and thus two different *dotpath*s)
for handling these two uses cases:
For example:
* one `config-user.yaml` for the local/user dotfiles (with its dedicated *dotpath*, for example `dotfiles-user`)
* one `config-root.yaml` for the system/root dotfiles (with its dedicated *dotpath*, for example `dotfiles-root`)
* One `config-user.yaml` for the local/user dotfiles (with its dedicated *dotpath*, for example `dotfiles-user`)
* One `config-root.yaml` for the system/root dotfiles (with its dedicated *dotpath*, for example `dotfiles-root`)
`config-user.yaml` is used when managing the user's dotfiles
`config-user.yaml` is used when managing the user's dotfiles:
```bash
## user config file is config-user.yaml
$ ./dotdrop.sh import --cfg config-user.yaml <some-dotfile>
@@ -20,7 +20,7 @@ $ ./dotdrop.sh install --cfg config-user.yaml
...
```
`config-root.yaml` is used when managing system's dotfiles and is to be used with `sudo` or directly by the root user
`config-root.yaml` is used when managing the system's dotfiles and is to be used with `sudo` or directly by the root user:
```bash
## root config file is config-root.yaml
$ sudo ./dotdrop.sh import --cfg=config-root.yaml <some-dotfile>