diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 01c6cf2..776cd05 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -127,7 +127,7 @@ Potential *included* entries: * Profile's *include* Variables are then used to resolve different elements in the config file: -see [this](docs/config.md#variables). +see [this](docs/config-file.md#variables). ## Rules diff --git a/README.md b/README.md index ed66ee9..379cfff 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ It allows you to store your dotfiles in Git and automagically deploy different versions of the same file on different setups. -It also allows you to manage different *sets* of dotfiles. +It also allows to manage different *sets* of dotfiles. For example, you can have a set of dotfiles for your home laptop and a different set for your office desktop. Those sets may overlap, and different versions of the same dotfiles can be deployed using different predefined *profiles*. @@ -68,8 +68,8 @@ A mirror of this repository is available on GitLab under : +``` + +*pre* actions: +```yaml +actions: + pre: + : +``` + +*post* actions: +```yaml +actions: + post: + : +``` + +Actions can be either `post` or `pre`. + +* `post` action will be executed after the dotfile deployment. +* `pre` action will be executed before the dotfile deployment. + +If you don't specify either `post` or `pre`, the action will be executed +after the dotfile deployment (which is equivalent to `post`). +Actions cannot obviously be named `pre` or `post`. + +Four types of actions can be defined: + +* [Dotfiles actions](config-dotfiles.md#dotfile-actions) +* [Default actions](config-config.md#default_actions-entry) +* [Profile actions](config-profiles.md#profile-actions-entry) +* [Fake dotfiles and actions](config-actions.md#fake-dotfile-and-actions) + +**Notes**: + +* Any action with a key starting with an underscore (`_`) won't be shown in output. This can be useful when working with sensitive data containing passwords, for example. +* Make sure to quote your actions to avoid bad surprises +* Actions are executed using the default shell (`$SHELL`) +* To use shell variables in your actions, you need to escape the curly brackets (`${HOME}` becomes `${{HOME}}`) + +## Fake dotfile and actions + +*Fake* dotfile can be created by specifying no `dst` and no `src` (see [Fake dotfiles and actions](config-actions.md#fake-dotfile-and-actions)). +By binding an action to such a *fake* dotfile, you make sure the action is always executed since +*fake* dotfile are always considered installed. + +```yaml +actions: + always_action: 'date > ~/.dotdrop.log' +dotfiles: + fake: + src: + dst: + actions: + - always_action +``` + +## Dynamic actions + +Variables ([config variables and dynvariables](config-file.md#variables) +and [template variables](templating.md#template-variables)) can be used +in actions for more advanced use-cases. + +```yaml +dotfiles: + f_test: + dst: ~/.test + src: test + actions: + - cookie_mv_somewhere "/tmp/moved-cookie" +variables: + cookie_dir_available: (test -d /tmp/cookiedir || mkdir -p /tmp/cookiedir) + cookie_header: "{{@@ cookie_dir_available @@}} && echo 'header' > /tmp/cookiedir/cookie" + cookie_mv: "{{@@ cookie_header @@}} && mv /tmp/cookiedir/cookie" +actions: + cookie_mv_somewhere: "{{@@ cookie_mv @@}} {0}" +``` + +or even something like this: +```yaml +actions: + log: "echo {0} >> {1}" +config: + default_actions: + - preaction '{{@@ _dotfile_key @@}} installed' "/tmp/log" +... +``` + +Make sure to quote the actions using variables. \ No newline at end of file diff --git a/docs/config-config.md b/docs/config-config.md new file mode 100644 index 0000000..4f0b865 --- /dev/null +++ b/docs/config-config.md @@ -0,0 +1,215 @@ +# Config entry + +The **config** entry (mandatory) contains global settings. + +Entry | Description | Default +-------- | ------------- | ------------ +`backup` | Create a backup of the dotfile in case it differs from the one that will be installed by dotdrop | true +`banner` | Display the banner | true +`check_version` | Check if a new version of dotdrop is available on github | false +`chmod_on_import` | Always add a chmod entry on newly imported dotfiles (see `--preserve-mode`) | false +`clear_workdir` | On `install` clear the `workdir` before installing dotfiles (see `--workdir-clear`) | false +`compare_workdir` | On `compare` notify on files in `workdir` not tracked by dotdrop | false +`cmpignore` | List of patterns to ignore when comparing, applied to all dotfiles (enclose in quotes when using wildcards; see [ignore patterns](config-file.md#ignore-patterns)) | - +`create` | Create a directory hierarchy when installing dotfiles if it doesn't exist | true +`default_actions` | List of action keys to execute for all installed dotfiles (See [actions](config-actions.md)) | - +`diff_command` | The diff command to use for diffing files | `diff -r -u {0} {1}` +`dotpath` | Path to the directory containing the dotfiles to be managed by dotdrop (absolute path or relative to the config file location) | `dotfiles` +`filter_file` | List of paths to load templating filters from (See [Templating available filters](templating.md#template-filters)) | - +`force_chmod` | If true, do not ask confirmation to apply permissions on install | false +`func_file` | List of paths to load templating functions from (See [Templating available methods](templating.md#template-methods)) | - +`ignore_missing_in_dotdrop` | Ignore missing files in dotdrop when comparing and importing (See [Ignore missing](config-file.md#ignore-missing)) | false +`ignoreempty` | Do not deploy template if empty | false +`impignore` | List of patterns to ignore when importing (enclose in quotes when using wildcards; see [ignore patterns](config-file.md#ignore-patterns)) | - +`import_actions` | List of paths to load actions from (absolute path or relative to the config file location; see [Import actions from file](config-config.md#import_actions-entry)) | - +`import_configs` | List of config file paths to be imported into the current config (absolute paths or relative to the current config file location; see [Import config files](config-config.md#import_configs-entry)) | - +`import_variables` | List of paths to load variables from (absolute paths or relative to the config file location; see [Import variables from file](config-config.md#import_variables-entry)) | - +`instignore` | List of patterns to ignore when installing, applied to all dotfiles (enclose in quotes when using wildcards; see [ignore patterns](config-file.md#ignore-patterns)) | - +`keepdot` | Preserve leading dot when importing hidden file in the `dotpath` | false +`key_prefix` | Prefix dotfile key on `import` with `f` for file and `d` for directory | true +`key_separator` | Separator to use on dotfile key generation on `import` | `_` +`link_dotfile_default` | Set a dotfile's `link` attribute to this value when undefined. Possible values: *nolink*, *link* (See [Symlinking dotfiles](config-file.md#symlinking-dotfiles)) | `nolink` +`link_on_import` | Set a dotfile's `link` attribute to this value when importing. Possible values: *nolink*, *link* [Symlinking dotfiles](config-file.md#symlinking-dotfiles)) | `nolink` +`longkey` | Use long keys for dotfiles when importing (See [Import dotfiles](usage.md#import-dotfiles)) | false +`minversion` | (*for internal use, do not modify*) Provides the minimal dotdrop version to use | - +`showdiff` | On install, show a diff before asking to overwrite (See `--showdiff`) | false +`template_dotfile_default` | Disable templating on all dotfiles when set to false | true +`upignore` | List of patterns to ignore when updating, appled to all dotfiles (enclose in quotes when using wildcards; see [ignore patterns](config-file.md#ignore-patterns)) | - +`workdir` | Path to the directory where templates are installed before being symlinked when using `link:link` or `link:link_children` (absolute path or relative to the config file location) | `~/.config/dotdrop` +link_by_default | When importing a dotfile, set `link` to this value by default | false + + +## import_variables entry + +It is possible to load variables/dynvariables from external files by providing their +paths in the config entry `import_variables`. + +The paths can be absolute or relative to the config file location. + +`config.yaml` +```yaml +config: + backup: true + create: true + dotpath: dotfiles + import_variables: + - variables.d/myvars.yaml +``` + +`variables.d/myvars.yaml` +```yaml +variables: + var1: "extvar1" +dynvariables: + dvar1: "echo extdvar1" +``` + +Dotdrop will fail if an imported path points to a non-existing file. +It is possible to make non-existing paths not fatal by appending `:optional` to the path: +```yaml +import_variables: +- variables.d/myvars.yaml:optional +``` + +## import_actions entry + +It is possible to load actions from external files by providing their +paths in the config entry `import_actions`. + +The paths can be absolute or relative to the config file location. + +`config.yaml` +```yaml +config: + backup: true + create: true + dotpath: dotfiles + import_actions: + - actions.d/myactions.yaml +dotfiles: + f_abc: + dst: ~/.abc + src: abc + actions: + - dateme +``` + +`actions.d/myactions.yaml` +```yaml +actions: + dateme: date > /tmp/timestamp +``` + +External/imported variables will take precedence over variables defined +inside the main config file. + +Dotdrop will fail if an imported path points to a non-existing file. +It is possible to make non-existing paths not fatal by appending `:optional` to the path: +```yaml +import_actions: +- actions.d/myactions.yaml:optional +``` + +## import_configs entry + +Entire config files can be imported using the `import_configs` entry. +This means making the following available from the imported config file in the original config file: + +* dotfiles +* profiles +* actions +* read/write transformations +* variables/dynvariables + +Paths to import can be absolute or relative to the importing config file +location. + +`config.yaml` +```yaml +config: + backup: true + create: true + dotpath: dotfiles + import_configs: + - other-config.yaml +dotfiles: + f_abc: + dst: ~/.abc + src: abc + actions: + - show +profiles: + my-host: + dotfiles: + - f_abc + - f_def + my-haskell: + include: + - other-host +``` + +`other-config.yaml` +```yaml +config: + backup: true + create: true + dotpath: dotfiles-other + import_actions: + - actions.yaml +dotfiles: + f_def: + dst: ~/.def + src: def + f_ghci: + dst: ~/.ghci + src: ghci +profiles: + other-host: + dotfiles: + - f_gchi +``` + +`actions.yaml` +```yaml +actions: + post: + show: less +``` + +In this example, `config.yaml` imports `other-config.yaml`. The dotfile `f_def` +used in the profile `my-host` is defined in `other-config.yaml`, and so is the +profile `other-host` included from `my-haskell`. The action `show` is defined +in `actions.yaml`, which is in turn imported by `other-config.yaml`. + +Dotdrop will fail if an imported path points to a non-existing file. +It is possible to make non-existing paths not fatal by appending `:optional` to the path. +```yaml +import_configs: +- other-config.yaml:optional +``` + +## default_actions entry + +Dotdrop allows to execute an action for any dotfile installation. These actions work as any other action (`pre` or `post`). + +For example, the below action will log each dotfile installation to a file. + +```yaml +actions: + post: + loginstall: "echo {{@@ _dotfile_abs_src @@}} installed to {{@@ _dotfile_abs_dst @@}} >> {0}" +config: + backup: true + create: true + dotpath: dotfiles + default_actions: + - loginstall "/tmp/dotdrop-installation.log" +dotfiles: + f_vimrc: + dst: ~/.vimrc + src: vimrc +profiles: + hostname: + dotfiles: + - f_vimrc +``` \ No newline at end of file diff --git a/docs/config-details.md b/docs/config-details.md deleted file mode 100644 index 310e793..0000000 --- a/docs/config-details.md +++ /dev/null @@ -1,713 +0,0 @@ -# Config details - -## actions entry - -Actions can be either `post` or `pre`. - -* `post` action will be executed after the dotfile deployment. -* `pre` action will be executed before the dotfile deployment. - -If you don't specify either `post` or `pre`, the action will be executed -after the dotfile deployment (which is equivalent to `post`). -Actions cannot obviously be named `pre` or `post`. - -Four types of actions can be defined: - -* [Dotfiles actions](#dotfile-actions) -* [Default actions](#default-actions) -* [Profile actions](#profile-actions) -* [Fake dotfiles and actions](#fake-dotfile-and-actions) - -**Notes**: - -* Any action with a key starting with an underscore (`_`) won't be shown in output. This can be useful when working with sensitive data containing passwords, for example. -* Make sure to quote your actions to avoid bad surprises -* Actions are executed using the default shell (`$SHELL`) -* To use shell variables in your actions, you need to escape the curly brackets (`${HOME}` becomes `${{HOME}}`) - -### Dotfile actions - -It is sometimes useful to execute some kind of action -when deploying a dotfile. - -Note that a dotfile's actions are only -executed when the dotfile is installed (that is, when -the version present in dotdrop differs from the one -in the filesystem). - -For example, let's consider -[Vundle](https://github.com/VundleVim/Vundle.vim), used -to manage Vim's plugins. The following action could -be set to update and install the plugins when `vimrc` is -deployed: - -```yaml -actions: - vundle: vim +VundleClean! +VundleInstall +VundleInstall! +qall -config: - backup: true - create: true - dotpath: dotfiles -dotfiles: - f_vimrc: - dst: ~/.vimrc - src: vimrc - actions: - - vundle -profiles: - home: - dotfiles: - - f_vimrc -``` - -Thus, when `f_vimrc` is installed, the command -`vim +VundleClean! +VundleInstall +VundleInstall! +qall` will -be executed. - -Sometimes, you may even want to execute some action prior to deploying a dotfile. -Let's take another example with -[vim-plug](https://github.com/junegunn/vim-plug): - -```yaml -actions: - pre: - vim-plug-install: test -e ~/.vim/autoload/plug.vim || (mkdir -p ~/.vim/autoload; curl - -fLo ~/.vim/autoload/plug.vim https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim) - vim-plug: vim +PlugInstall +qall -config: - backup: true - create: true - dotpath: dotfiles -dotfiles: - f_vimrc: - dst: ~/.vimrc - src: vimrc - actions: - - vim-plug-install - - vim-plug -profiles: - home: - dotfiles: - - f_vimrc -``` - -This way, we make sure [vim-plug](https://github.com/junegunn/vim-plug) -is installed prior to deploying the `~/.vimrc` dotfile. - -You can also define `post` actions like this: - -```yaml -actions: - post: - some-action: echo "Hello, World!" >/tmp/log -``` - -Actions can even be parameterized. For example: - -```yaml -actions: - echoaction: echo '{0}' > {1} -config: - backup: true - create: true - dotpath: dotfiles -dotfiles: - f_vimrc: - dst: ~/.vimrc - src: vimrc - actions: - - echoaction "vim installed" /tmp/mydotdrop.log - f_xinitrc: - dst: ~/.xinitrc - src: xinitrc - actions: - - echoaction "xinitrc installed" /tmp/myotherlog.log -profiles: - home: - dotfiles: - - f_vimrc - - f_xinitrc -``` - -The above will execute `echo 'vim installed' > /tmp/mydotdrop.log` when -vimrc is installed and `echo 'xinitrc installed' > /tmp/myotherlog.log'` -when xinitrc is installed. - -### Default actions - -Dotdrop allows you to execute an action for any dotfile installation. These actions work as any other action (`pre` or `post`). - -For example, the below action will log each dotfile installation to a file. - -```yaml -actions: - post: - loginstall: "echo {{@@ _dotfile_abs_src @@}} installed to {{@@ _dotfile_abs_dst @@}} >> {0}" -config: - backup: true - create: true - dotpath: dotfiles - default_actions: - - loginstall "/tmp/dotdrop-installation.log" -dotfiles: - f_vimrc: - dst: ~/.vimrc - src: vimrc -profiles: - hostname: - dotfiles: - - f_vimrc -``` - -### Profile actions - -A profile action can be either a `pre` or `post` action (see [actions](config-details.md#actions-entry)). -These are executed before any dotfile installation (for `pre`) and after all dotfile installations (for `post`) -only if at least one dotfile has been installed. - -### Fake dotfile and actions - -*Fake* dotfile can be created by specifying no `dst` and no `src` (see [config format](config-format.md)). -By binding an action to such a *fake* dotfile, you make sure the action is always executed since -*fake* dotfile are always considered installed. - -```yaml -actions: - always_action: 'date > ~/.dotdrop.log' -dotfiles: - fake: - src: - dst: - actions: - - always_action -``` - -## transformations entry - -For examples of transformation uses, see: - -* [Handle compressed directories](howto/store-compressed-directories.md) -* [Handle secrets](howto/sensitive-dotfiles.md) - -**Notes**: - -* Any transformation with a key starting with an underscore (`_`) won't be shown in output. This can be useful when working with sensitive data containing passwords, for example. -* Make sure to quote your transformations to avoid bad surprises -* Transformations are executed using the default shell (`$SHELL`) -* To use shell variables in your transformations you need to escape the curly brackets (`${HOME}` becomes `${{HOME}}`) - -There are two types of transformations available: - -* **Read transformations**: used to transform dotfiles before they are installed ([format](config-format.md) key `trans_read`) - * Used for commands `install` and `compare` - * They have two arguments: - * **{0}** will be replaced with the dotfile to process - * **{1}** will be replaced with a temporary file to store the result of the transformation - * This Happens **before** the dotfile is templated (see [templating](templating.md)) - -* **Write transformations**: used to transform files before updating a dotfile ([format](config-format.md) key `trans_write`) - * Used for command `update` - * They have two arguments: - * **{0}** will be replaced with the file path to update the dotfile with - * **{1}** will be replaced with a temporary file to store the result of the transformation - -A typical use-case for transformations is when dotfiles need to be -stored encrypted or compressed. For more, see [the howto](howto/howto.md). - -Note that transformations cannot be used if the dotfile is to be linked (when `link: link` or `link: link_children`). - -Transformations also support additional positional arguments that must start from 2 (since `{0}` and `{1}` are added automatically). The transformations themselves as well as their arguments can also be templated. - -For example: -```yaml -trans_read: - targ: echo "$(basename {0}); {{@@ _dotfile_key @@}}; {2}; {3}" > {1} -dotfiles: - f_abc: - dst: /tmp/abc - src: abc - trans_read: targ "{{@@ profile @@}}" lastarg -profiles: - p1: - dotfiles: - - f_abc -``` - -will result in `abc; f_abc; p1; lastarg`. - -## variables entry - -Variables defined in the `variables` entry are made available within the config file. - -Config variables are recursively evaluated, which means that -a config like the below: -```yaml -variables: - var1: "var1" - var2: "{{@@ var1 @@}} var2" - var3: "{{@@ var2 @@}} var3" - var4: "{{@@ dvar4 @@}}" -dynvariables: - dvar1: "echo dvar1" - dvar2: "{{@@ dvar1 @@}} dvar2" - dvar3: "{{@@ dvar2 @@}} dvar3" - dvar4: "echo {{@@ var3 @@}}" -``` - -will result in the following available variables: - -* var1: `var1` -* var2: `var1 var2` -* var3: `var1 var2 var3` -* var4: `echo var1 var2 var3` -* dvar1: `dvar1` -* dvar2: `dvar1 dvar2` -* dvar3: `dvar1 dvar2 dvar3` -* dvar4: `var1 var2 var3` - -## dynvariables entry - -It is also possible to have *dynamic* variables, in the sense that their -content will be interpreted by the shell before being substituted. - -These need to be defined in the config file under the entry `dynvariables`. - -For example: -```yaml -dynvariables: - dvar1: head -1 /proc/meminfo - dvar2: "echo 'this is some test' | rev | tr ' ' ','" - dvar3: /tmp/my_shell_script.sh - user: "echo $USER" - config_file: test -f "{{@@ user_config @@}}" && echo "{{@@ user_config @@}}" || echo "{{@@ dfl_config @@}}" -variables: - user_config: "profile_{{@@ user @@}}_uid.yaml" - dfl_config: "profile_default.yaml" -``` - -They have the same properties as [Variables](config.md#variables). - -## uservariables entry - -If you want to manually enter variables' values, you can use the -`uservariables` entry. Each variable will be prompted to the user. - -For example: -```yaml -uservariables: - emailvar: "email" -``` - -will prompt the user to enter a value for the variable `emailvar`: -``` -Please provide the value for "email": -``` - -And store the entered text as the value for the variable `email`. -The variable can then be used as any other [variable](config.md#variables). - -`uservariables` are eventually saved to `uservariables.yaml` (relatively to the -config file). -This allows you to use the following construct to prompt once for some specific variables and -then store them in a file. You might also want to add `uservariables.yaml` to your `.gitignore`. -```yaml -uservariables: - emailvar: "email" -config: - import_variables: - - uservariables.yaml:optional -``` - -For an example, see [prompt user for variables](howto/prompt-user-for-variables.md). - -## Profile variables entry - -Profile variables will take precedence over globally defined variables. -This means that you could do something like this: -```yaml -variables: - git_email: home@email.com -dotfiles: - f_gitconfig: - dst: ~/.gitconfig - src: gitconfig -profiles: - work: - dotfiles: - - f_gitconfig - variables: - git_email: work@email.com - private: - dotfiles: - - f_gitconfig -``` - -## Profile include entry - -If one profile is using the entire set of another profile, one can use -the `include` entry to avoid redundancy. - -Note that everything from the included profile is made available -(actions, variables/dynvariables, etc). - -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`. - -For more advanced use-cases, variables -([variables](config.md#variables) and [dynvariables](#dynvariables-entry)) -can be used to specify the profile to include in a profile: - -For example: -```yaml -variables: - var1: "john" -dynvariables: - d_user: "echo $USER" -profiles: - profile_john: - dotfiles: - - f_john_dotfile - profile_bill: - dotfiles: - - f_bill_dotfile - p1: - include: - - "profile_{{@@ d_user @@}}" - p2: - include: - - "profile_{{@@ var1 @@}}" -``` - -Note that profiles cannot include other profiles defined above in -the import tree (for example, when a profile exists in another file and is imported using `import_configs`). - -## Profile import entry - -A profile's dotfiles list can be loaded from external files -by specifying their paths in the config entry `import` under the specific profile. - -The paths can be absolute or relative to the config file location. - -`config.yaml` -```yaml -dotfiles: - f_abc: - dst: ~/.abc - src: abc - f_def: - dst: ~/.def - src: def - f_xyz: - dst: ~/.xyz - src: xyz -profiles: - p1: - dotfiles: - - f_abc - import: - - somedotfiles.yaml -``` - -`somedotfiles.yaml` -``` -dotfiles: - - f_def - - f_xyz -``` - -Variables can be used in `import`, which allow you to do something like: -```yaml -import: -- profiles.d/{{@@ profile @@}}.yaml -``` - -## import_variables entry - -It is possible to load variables/dynvariables from external files by providing their -paths in the config entry `import_variables`. - -The paths can be absolute or relative to the config file location. - -`config.yaml` -```yaml -config: - backup: true - create: true - dotpath: dotfiles - import_variables: - - variables.d/myvars.yaml -``` - -`variables.d/myvars.yaml` -```yaml -variables: - var1: "extvar1" -dynvariables: - dvar1: "echo extdvar1" -``` - -Dotdrop will fail if an imported path points to a non-existing file. -It is possible to make non-existing paths not fatal by appending `:optional` to the path: -```yaml -import_variables: -- variables.d/myvars.yaml:optional -``` - -## import_actions entry - -It is possible to load actions from external files by providing their -paths in the config entry `import_actions`. - -The paths can be absolute or relative to the config file location. - -`config.yaml` -```yaml -config: - backup: true - create: true - dotpath: dotfiles - import_actions: - - actions.d/myactions.yaml -dotfiles: - f_abc: - dst: ~/.abc - src: abc - actions: - - dateme -``` - -`actions.d/myactions.yaml` -```yaml -actions: - dateme: date > /tmp/timestamp -``` - -External/imported variables will take precedence over variables defined -inside the main config file. - -Dotdrop will fail if an imported path points to a non-existing file. -It is possible to make non-existing paths not fatal by appending `:optional` to the path: -```yaml -import_actions: -- actions.d/myactions.yaml:optional -``` - -## import_configs entry - -Entire config files can be imported using the `import_configs` entry. -This means making the following available from the imported config file in the original config file: - -* dotfiles -* profiles -* actions -* read/write transformations -* variables/dynvariables - -Paths to import can be absolute or relative to the importing config file -location. - -`config.yaml` -```yaml -config: - backup: true - create: true - dotpath: dotfiles - import_configs: - - other-config.yaml -dotfiles: - f_abc: - dst: ~/.abc - src: abc - actions: - - show -profiles: - my-host: - dotfiles: - - f_abc - - f_def - my-haskell: - include: - - other-host -``` - -`other-config.yaml` -```yaml -config: - backup: true - create: true - dotpath: dotfiles-other - import_actions: - - actions.yaml -dotfiles: - f_def: - dst: ~/.def - src: def - f_ghci: - dst: ~/.ghci - src: ghci -profiles: - other-host: - dotfiles: - - f_gchi -``` - -`actions.yaml` -```yaml -actions: - post: - show: less -``` - -In this example, `config.yaml` imports `other-config.yaml`. The dotfile `f_def` -used in the profile `my-host` is defined in `other-config.yaml`, and so is the -profile `other-host` included from `my-haskell`. The action `show` is defined -in `actions.yaml`, which is in turn imported by `other-config.yaml`. - -Dotdrop will fail if an imported path points to a non-existing file. -It is possible to make non-existing paths not fatal by appending `:optional` to the path. -```yaml -import_configs: -- other-config.yaml:optional -``` - -## Dynamic dotfile paths - -Dotfile source (`src`) and destination (`dst`) paths can be dynamically constructed using -defined variables ([variables and dynvariables](config.md#variables)). - -For example, to have a dotfile deployed on a unique Firefox profile where the -profile path is dynamically found using a shell oneliner stored in a dynvariable: -```yaml -dynvariables: - mozpath: find ~/.mozilla/firefox -name '*.default' -dotfiles: - f_somefile: - dst: "{{@@ mozpath @@}}/somefile" - src: firefox/somefile -profiles: - home: - dotfiles: - - f_somefile -``` - -Or when you need to select the dotfile to deploy depending on -the profile used (`ssh_config.perso` for the profile `perso` and -`ssh_config.work` for the `work` profile): -```yaml -dotfiles: - f_ssh_config: - src: "{{@@ ssh_config_file @@}}" - dst: ~/.ssh/config -profiles: - perso: - dotfiles: - - f_ssh_config - variables: - - ssh_config_file: "ssh_config.perso" - work: - dotfiles: - - f_ssh_config - variables: - - ssh_config_file: "ssh_config.work" -``` - -## Dynamic dotfile link value - -Dotfile `link` values can be dynamically constructed using -defined variables ([variables and dynvariables](config.md#variables)). - -For example: -```yaml -variables: - link_value: "nolink" -dotfiles: - f_test: - src: test - dst: ~/.test - link: "{{@@ link_value @@}}" -profiles: - linux: - dotfiles: - - f_test - variables: - link_value: "link" - windows: - dotfiles: - - f_test -``` - -Make sure to quote the link value in the config file. - -## Dynamic actions - -Variables ([config variables and dynvariables](config.md#variables) -and [template variables](templating.md#template-variables)) can be used -in actions for more advanced use-cases. - -```yaml -dotfiles: - f_test: - dst: ~/.test - src: test - actions: - - cookie_mv_somewhere "/tmp/moved-cookie" -variables: - cookie_dir_available: (test -d /tmp/cookiedir || mkdir -p /tmp/cookiedir) - cookie_header: "{{@@ cookie_dir_available @@}} && echo 'header' > /tmp/cookiedir/cookie" - cookie_mv: "{{@@ cookie_header @@}} && mv /tmp/cookiedir/cookie" -actions: - cookie_mv_somewhere: "{{@@ cookie_mv @@}} {0}" -``` - -or even something like this: -```yaml -actions: - log: "echo {0} >> {1}" -config: - default_actions: - - preaction '{{@@ _dotfile_key @@}} installed' "/tmp/log" -... -``` - -Make sure to quote the actions using variables. - -## Dynamic transformations - -As for [dynamic actions](#dynamic-actions), transformations support -the use of variables ([variables and dynvariables](config.md#variables) -and [template variables](templating.md#template-variables)). - -A very dumb example: -```yaml -trans_read: - r_echo_abs_src: echo "{0}: {{@@ _dotfile_abs_src @@}}" > {1} - r_echo_var: echo "{0}: {{@@ r_var @@}}" > {1} -trans_write: - w_echo_key: echo "{0}: {{@@ _dotfile_key @@}}" > {1} - w_echo_var: echo "{0}: {{@@ w_var @@}}" > {1} -variables: - r_var: readvar - w_var: writevar -dotfiles: - f_abc: - dst: ${tmpd}/abc - src: abc - trans_read: r_echo_abs_src - trans_write: w_echo_key - f_def: - dst: ${tmpd}/def - src: def - trans_read: r_echo_var - trans_write: w_echo_var -``` diff --git a/docs/config-dotfiles.md b/docs/config-dotfiles.md new file mode 100644 index 0000000..8bf1355 --- /dev/null +++ b/docs/config-dotfiles.md @@ -0,0 +1,218 @@ +# Dotfiles entry + +The **dotfiles** entry (mandatory) contains a YAML object with sub-objects for the dotfiles managed by dotdrop. The entries in the sub-objects are as follows: + +Entry | Description +-------- | ------------- +`dst` | Where this dotfile needs to be deployed (dotfiles with empty `dst` are ignored and considered installed, can use `variables`, make sure to quote) +`src` | Dotfile path within the `dotpath` (dotfiles with empty `src` are ignored and considered installed, can use `variables`, make sure to quote) +`link` | Defines how this dotfile is installed. Possible values: *nolink*, *link*, *link_children* (See [Symlinking dotfiles](config-file.md#symlinking-dotfiles)) (defaults to value of `link_dotfile_default`) +`actions` | List of action keys that need to be defined in the **actions** entry below (See [actions](config-actions.md)) +`chmod` | Defines the file permissions in octal notation to apply during installation (See [permissions](config-file.md#permissions)) +`cmpignore` | List of patterns to ignore when comparing (enclose in quotes when using wildcards; see [ignore patterns](config-file.md#ignore-patterns)) +`ignore_missing_in_dotdrop` | Ignore missing files in dotdrop when comparing and importing (see [Ignore missing](config-file.md#ignore-missing)) +`ignoreempty` | If true, an empty template will not be deployed (defaults to the value of `ignoreempty`) +`instignore` | List of patterns to ignore when installing (enclose in quotes when using wildcards; see [ignore patterns](config-file.md#ignore-patterns)) +`template` | If false, disable templating for this dotfile (defaults to the value of `template_dotfile_default`) +`trans_read` | Transformation key to apply when installing this dotfile (must be defined in the **trans_read** entry below; see [transformations](config-transformations.md)) +`trans_write` | Transformation key to apply when updating this dotfile (must be defined in the **trans_write** entry below; see [transformations](config-transformations.md)) +`upignore` | List of patterns to ignore when updating (enclose in quotes when using wildcards; see [ignore patterns](config-file.md#ignore-patterns)) +link_children | Replaced by `link: link_children` +trans | Replaced by `trans_read` + +```yaml +: + dst: + src: + ## Optional + link: (nolink|link|link_children) + ignoreempty: (true|false) + cmpignore: + - "" + upignore: + - "" + instignore: + - "" + actions: + - + template: (true|false) + chmod: '' + trans_read: + trans_write: +``` + +## Dotfile actions + +It is sometimes useful to execute some kind of action +when deploying a dotfile. + +Note that a dotfile's actions are only +executed when the dotfile is installed (that is, when +the version present in dotdrop differs from the one +in the filesystem). + +For example, let's consider +[Vundle](https://github.com/VundleVim/Vundle.vim), used +to manage Vim's plugins. The following action could +be set to update and install the plugins when `vimrc` is +deployed: + +```yaml +actions: + vundle: vim +VundleClean! +VundleInstall +VundleInstall! +qall +config: + backup: true + create: true + dotpath: dotfiles +dotfiles: + f_vimrc: + dst: ~/.vimrc + src: vimrc + actions: + - vundle +profiles: + home: + dotfiles: + - f_vimrc +``` + +Thus, when `f_vimrc` is installed, the command +`vim +VundleClean! +VundleInstall +VundleInstall! +qall` will +be executed. + +Sometimes, you may even want to execute some action prior to deploying a dotfile. +Let's take another example with +[vim-plug](https://github.com/junegunn/vim-plug): + +```yaml +actions: + pre: + vim-plug-install: test -e ~/.vim/autoload/plug.vim || (mkdir -p ~/.vim/autoload; curl + -fLo ~/.vim/autoload/plug.vim https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim) + vim-plug: vim +PlugInstall +qall +config: + backup: true + create: true + dotpath: dotfiles +dotfiles: + f_vimrc: + dst: ~/.vimrc + src: vimrc + actions: + - vim-plug-install + - vim-plug +profiles: + home: + dotfiles: + - f_vimrc +``` + +This way, we make sure [vim-plug](https://github.com/junegunn/vim-plug) +is installed prior to deploying the `~/.vimrc` dotfile. + +You can also define `post` actions like this: + +```yaml +actions: + post: + some-action: echo "Hello, World!" >/tmp/log +``` + +Actions can even be parameterized. For example: + +```yaml +actions: + echoaction: echo '{0}' > {1} +config: + backup: true + create: true + dotpath: dotfiles +dotfiles: + f_vimrc: + dst: ~/.vimrc + src: vimrc + actions: + - echoaction "vim installed" /tmp/mydotdrop.log + f_xinitrc: + dst: ~/.xinitrc + src: xinitrc + actions: + - echoaction "xinitrc installed" /tmp/myotherlog.log +profiles: + home: + dotfiles: + - f_vimrc + - f_xinitrc +``` + +The above will execute `echo 'vim installed' > /tmp/mydotdrop.log` when +vimrc is installed and `echo 'xinitrc installed' > /tmp/myotherlog.log'` +when xinitrc is installed. + +## Dynamic dotfile paths + +Dotfile source (`src`) and destination (`dst`) paths can be dynamically constructed using +defined variables ([variables and dynvariables](config-file.md#variables)). + +For example, to have a dotfile deployed on a unique Firefox profile where the +profile path is dynamically found using a shell oneliner stored in a dynvariable: +```yaml +dynvariables: + mozpath: find ~/.mozilla/firefox -name '*.default' +dotfiles: + f_somefile: + dst: "{{@@ mozpath @@}}/somefile" + src: firefox/somefile +profiles: + home: + dotfiles: + - f_somefile +``` + +Or when you need to select the dotfile to deploy depending on +the profile used (`ssh_config.perso` for the profile `perso` and +`ssh_config.work` for the `work` profile): +```yaml +dotfiles: + f_ssh_config: + src: "{{@@ ssh_config_file @@}}" + dst: ~/.ssh/config +profiles: + perso: + dotfiles: + - f_ssh_config + variables: + - ssh_config_file: "ssh_config.perso" + work: + dotfiles: + - f_ssh_config + variables: + - ssh_config_file: "ssh_config.work" +``` + +## Dynamic dotfile link value + +Dotfile `link` values can be dynamically constructed using +defined variables ([variables and dynvariables](config-file.md#variables)). + +For example: +```yaml +variables: + link_value: "nolink" +dotfiles: + f_test: + src: test + dst: ~/.test + link: "{{@@ link_value @@}}" +profiles: + linux: + dotfiles: + - f_test + variables: + link_value: "link" + windows: + dotfiles: + - f_test +``` + +Make sure to quote the link value in the config file. \ No newline at end of file diff --git a/docs/config-dynvars.md b/docs/config-dynvars.md new file mode 100644 index 0000000..1652cc7 --- /dev/null +++ b/docs/config-dynvars.md @@ -0,0 +1,25 @@ +# Dynvariables entry + +The **dynvariables** entry (optional) contains an interpreted variables mapping. + +```yaml +dynvariables: + : +``` + +Dynvariables (*dynamic* variables) will be interpreted by the shell before being substituted. + +For example: +```yaml +dynvariables: + dvar1: head -1 /proc/meminfo + dvar2: "echo 'this is some test' | rev | tr ' ' ','" + dvar3: /tmp/my_shell_script.sh + user: "echo $USER" + config_file: test -f "{{@@ user_config @@}}" && echo "{{@@ user_config @@}}" || echo "{{@@ dfl_config @@}}" +variables: + user_config: "profile_{{@@ user @@}}_uid.yaml" + dfl_config: "profile_default.yaml" +``` + +They have the same properties as [Variables](config-file.md#variables). \ No newline at end of file diff --git a/docs/config.md b/docs/config-file.md similarity index 66% rename from docs/config.md rename to docs/config-file.md index d07c27e..b973f5d 100644 --- a/docs/config.md +++ b/docs/config-file.md @@ -1,8 +1,8 @@ -# Config +# Config file ## Location -The config file used by dotdrop is +The default config file used by dotdrop is [config.yaml](https://github.com/deadc0de6/dotdrop/blob/master/config.yaml). Unless specified otherwise, dotdrop will look in the following places for its config file @@ -22,25 +22,25 @@ or by defining the `DOTDROP_CONFIG` environment variable. Multiple variables can be used within the config file to parametrize the following elements of the config: -* Dotfile `src` and `dst` paths (See [Dynamic dotfile paths](config-details.md#dynamic-dotfile-paths)) -* External path specifications - * `import_variables` - * `import_actions` - * `import_configs` - * Profiles' `import` - * Profiles' `include` +* Dotfile `src` and `dst` paths (See [Dynamic dotfile paths](config-dotfiles.md#dynamic-dotfile-paths)) +* External paths + * `import_variables` + * `import_actions` + * `import_configs` + * Profiles' `import` + * Profiles' `include` `actions` and `transformations` also support the use of variables, but those are resolved when the action/transformation is executed -(See [Dynamic actions](config-details.md#dynamic-actions), -[Dynamic transformations](config-details.md#dynamic-transformations) and [Templating](templating.md)). +(See [Dynamic actions](config-actions.md#dynamic-actions), +[Dynamic transformations](config-transformations.md#dynamic-transformations) and [Templating](templating.md)). The following variables are available in the config files: -* [Variables defined in the config](config-details.md#variables-entry) -* [Interpreted variables defined in the config](config-details.md#dynvariables-entry) -* [User variables defined in the config](config-details.md#uservariables-entry) -* [Profile variables defined in the config](config-details.md#profile-variables-entry) +* [Variables defined in the config](config-variables.md) +* [Interpreted variables defined in the config](config-dynvars.md) +* [User variables defined in the config](config-variables.md) +* [Profile variables defined in the config](config-profiles.md#profile-variables-entry) * Environment variables: `{{@@ env['MY_VAR'] @@}}` * Dotdrop header: `{{@@ header() @@}}` (see [Dotdrop header](templating.md#dotdrop-header)) @@ -51,24 +51,24 @@ then be available during [templating](templating.md). Here are some rules on the use of variables in configs: -* [Interpreted variables](config-details.md#dynvariables-entry) are executed in their own file. -* [Interpreted variables](config-details.md#dynvariables-entry) and - [variables](config-details.md#variables-entry) are templated before - [interpreted variables](config-details.md#dynvariables-entry) are executed. +* [Interpreted variables](config-dynvars.md) are executed in their own file. +* [Interpreted variables](config-dynvars.md) and + [variables](config-dynvars.md) are templated before + [interpreted variables](config-dynvars.md) are executed. * Config files do not have access to variables defined above in the import tree. * `dynvariables` take precedence over `variables`. * Profile `(dyn)variables` take precedence over any other `(dyn)variables`. * Profile `(dyn)variables` take precedence over profile's included `(dyn)variables`. * External/imported `(dyn)variables` take precedence over `(dyn)variables` defined inside the main config file. -* [User variables](config-details.md#uservariables-entry) are ignored if +* [User variables](config-uservars.md) are ignored if any other variable with the same key is defined. ## Permissions -Dotdrop allows you to control the permissions applied to a dotfile using the -config dotfile entry [chmod](config-format.md#dotfiles-entry). -A [chmod](config-format.md#dotfiles-entry) entry on a directory +Dotdrop allows to control the permissions applied to a dotfile using the +config dotfile entry [chmod](config-dotfiles.md). +A [chmod](config-dotfiles.md) entry on a directory is applied to the directory only, not recursively. For example: @@ -100,7 +100,7 @@ On `install`, the following rules are applied: * If the global setting `force_chmod` is set to true, dotdrop will not ask for confirmation to apply permissions. -On `update`: +On `update`, the following rule is applied: * If the permissions of the file in the filesystem differ from the dotfile in the `dotpath`, then the dotfile entry `chmod` is added/updated accordingly. @@ -119,21 +119,21 @@ For more, see [this how-to](howto/symlink-dotfiles.md). ## Template config entries -Some entries in the config can use the templating feature (See [templating](templating.md)): +Some entries in the config can be templated (See [templating](templating.md)): Entry | Related doc -------- | ------------- -dotfile src | [Dynamic dotfile paths](config-details.md#dynamic-dotfile-paths) -dotfile dst | [Dynamic dotfile paths](config-details.md#dynamic-dotfile-paths) -dotfile link | [Dynamic dotfile link value](config-details.md#dynamic-dotfile-link-value) -variables | [variables](config-details.md#variables-entry) -dynvariables | [dynvariables](config-details.md#dynvariables-entry) -actions | [dynamic actions](config-details.md#dynamic-actions) -profile include | [Profile include](config-details.md#profile-include-entry) -profile import | [Profile import](config-details.md#profile-import-entry) -import_variables | [import_variables](config-details.md#import_variables-entry) -import_actions | [import_actions](config-details.md#import_actions-entry) -import_configs | [import_configs](config-details.md#import_configs-entry) +dotfile src | [Dynamic dotfile paths](config-dotfiles.md#dynamic-dotfile-paths) +dotfile dst | [Dynamic dotfile paths](config-dotfiles.md#dynamic-dotfile-paths) +dotfile link | [Dynamic dotfile link value](config-dotfiles.md#dynamic-dotfile-link-value) +variables | [variables](config-variables.md) +dynvariables | [dynvariables](config-dynvars.md) +actions | [dynamic actions](config-dynvars.md) +profile include | [Profile include](config-profiles.md#profile-include-entry) +profile import | [Profile import](config-profiles.md#profile-import-entry) +import_variables | [import_variables](config-config.md#import_variables-entry) +import_actions | [import_actions](config-config.md#import_actions-entry) +import_configs | [import_configs](config-config.md#import_configs-entry) ## All dotfiles for a profile @@ -200,7 +200,7 @@ Patterns used for a specific dotfile can be specified relative to the dotfile de Similar to a `.gitignore` file, you can prefix ignore patterns with an exclamation point (`!`). This so-called "negative ignore pattern" will cause any files that match that pattern to __not__ be ignored, provided they *would have* been ignored by an earlier ignore pattern (dotdrop will warn if that is not the -case). This feature allows you to, for example, ignore all files within a certain directory, except for a +case). This feature allows to, for example, ignore all files within a certain directory, except for a particular one (See examples below). To completely ignore comparison of a specific dotfile: @@ -252,3 +252,32 @@ dotfiles: - '!file' - '[a-zA-Z0-9]*' ``` + +## Ignore missing + +Sometimes, it is nice to have [update](usage.md#update-dotfiles) not copy all the files in the installed directory +or [compare](usage.md#compare-dotfiles) diff them. + +For example, +maybe you only want to include a single configuration file in your repository +and don't want to include other files the program uses, +such as a cached files. +Maybe you only want to change one file and don't want the others cluttering your repository. +Maybe the program changes these files quite often and creates unnecessary diffs in your dotfiles. + +In these cases, you can use the [ignore-missing](config-config.md) option. +This option is available as a flag (`--ignore-missing` or `-z`) to the `update` and `compare` commands, +or [as ignore-missing in the config](config-config.md). + +To configure globally, place the following in `config.yaml`: +```yaml +config: + ignore_missing_in_dotdrop: true +``` + +To configure per dotfile: +```yaml +dotfiles: + f_abc: + ignore_missing_in_dotdrop: true +``` \ No newline at end of file diff --git a/docs/config-format.md b/docs/config-format.md deleted file mode 100644 index e6f1a3d..0000000 --- a/docs/config-format.md +++ /dev/null @@ -1,195 +0,0 @@ -# Config format - -The dotdrop config file uses [YAML](https://yaml.org/) syntax. - -Here is a minimal config file to start with: -[config.yaml](https://github.com/deadc0de6/dotdrop/blob/master/config.yaml). - -## config entry - -The **config** entry (mandatory) contains settings for the deployment. - -Entry | Description | Default --------- | ------------- | ------------ -`backup` | Create a backup of the dotfile in case it differs from the one that will be installed by dotdrop | true -`banner` | Display the banner | true -`check_version` | Check if a new version of dotdrop is available on github | false -`chmod_on_import` | Always add a chmod entry on newly imported dotfiles (see `--preserve-mode`) | false -`clear_workdir` | On `install` clear the `workdir` before installing dotfiles (see `--workdir-clear`) | false -`compare_workdir` | On `compare` notify on files in `workdir` not tracked by dotdrop | false -`cmpignore` | List of patterns to ignore when comparing, applied to all dotfiles (enclose in quotes when using wildcards; see [ignore patterns](config.md#ignore-patterns)) | - -`create` | Create a directory hierarchy when installing dotfiles if it doesn't exist | true -`default_actions` | List of action keys to execute for all installed dotfiles (See [actions](config-details.md#actions-entry)) | - -`diff_command` | The diff command to use for diffing files | `diff -r -u {0} {1}` -`dotpath` | Path to the directory containing the dotfiles to be managed by dotdrop (absolute path or relative to the config file location) | `dotfiles` -`filter_file` | List of paths to load templating filters from (See [Templating available filters](templating.md#template-filters)) | - -`force_chmod` | If true, do not ask confirmation to apply permissions on install | false -`func_file` | List of paths to load templating functions from (See [Templating available methods](templating.md#template-methods)) | - -`ignore_missing_in_dotdrop` | Ignore missing files in dotdrop when comparing and importing (See [Ignore missing](usage.md#ignore-missing)) | false -`ignoreempty` | Do not deploy template if empty | false -`impignore` | List of patterns to ignore when importing (enclose in quotes when using wildcards; see [ignore patterns](config.md#ignore-patterns)) | - -`import_actions` | List of paths to load actions from (absolute path or relative to the config file location; see [Import actions from file](config-details.md#import_actions-entry)) | - -`import_configs` | List of config file paths to be imported into the current config (absolute paths or relative to the current config file location; see [Import config files](config-details.md#import_configs-entry)) | - -`import_variables` | List of paths to load variables from (absolute paths or relative to the config file location; see [Import variables from file](config-details.md#import_variables-entry)) | - -`instignore` | List of patterns to ignore when installing, applied to all dotfiles (enclose in quotes when using wildcards; see [ignore patterns](config.md#ignore-patterns)) | - -`keepdot` | Preserve leading dot when importing hidden file in the `dotpath` | false -`key_prefix` | Prefix dotfile key on `import` with `f` for file and `d` for directory | true -`key_separator` | Separator to use on dotfile key generation on `import` | `_` -`link_dotfile_default` | Set a dotfile's `link` attribute to this value when undefined. Possible values: *nolink*, *link* (See [Symlinking dotfiles](config.md#symlinking-dotfiles)) | `nolink` -`link_on_import` | Set a dotfile's `link` attribute to this value when importing. Possible values: *nolink*, *link* [Symlinking dotfiles](config.md#symlinking-dotfiles)) | `nolink` -`longkey` | Use long keys for dotfiles when importing (See [Import dotfiles](usage.md#import-dotfiles)) | false -`minversion` | (*for internal use, do not modify*) Provides the minimal dotdrop version to use | - -`showdiff` | On install, show a diff before asking to overwrite (See `--showdiff`) | false -`template_dotfile_default` | Disable templating on all dotfiles when set to false | true -`upignore` | List of patterns to ignore when updating, appled to all dotfiles (enclose in quotes when using wildcards; see [ignore patterns](config.md#ignore-patterns)) | - -`workdir` | Path to the directory where templates are installed before being symlinked when using `link:link` or `link:link_children` (absolute path or relative to the config file location) | `~/.config/dotdrop` -link_by_default | When importing a dotfile, set `link` to this value by default | false - -## dotfiles entry - -The **dotfiles** entry (mandatory) contains a YAML object with sub-objects for the dotfiles managed by dotdrop. The entries in the sub-objects are as follows: - -Entry | Description --------- | ------------- -`dst` | Where this dotfile needs to be deployed (dotfiles with empty `dst` are ignored and considered installed, can use `variables`, make sure to quote) -`src` | Dotfile path within the `dotpath` (dotfiles with empty `src` are ignored and considered installed, can use `variables`, make sure to quote) -`link` | Defines how this dotfile is installed. Possible values: *nolink*, *link*, *link_children* (See [Symlinking dotfiles](config.md#symlinking-dotfiles)) (defaults to value of `link_dotfile_default`) -`actions` | List of action keys that need to be defined in the **actions** entry below (See [actions](config-details.md#actions-entry)) -`chmod` | Defines the file permissions in octal notation to apply during installation (See [permissions](config.md#permissions)) -`cmpignore` | List of patterns to ignore when comparing (enclose in quotes when using wildcards; see [ignore patterns](config.md#ignore-patterns)) -`ignore_missing_in_dotdrop` | Ignore missing files in dotdrop when comparing and importing (see [Ignore missing](usage.md#ignore-missing)) -`ignoreempty` | If true, an empty template will not be deployed (defaults to the value of `ignoreempty`) -`instignore` | List of patterns to ignore when installing (enclose in quotes when using wildcards; see [ignore patterns](config.md#ignore-patterns)) -`template` | If false, disable templating for this dotfile (defaults to the value of `template_dotfile_default`) -`trans_read` | Transformation key to apply when installing this dotfile (must be defined in the **trans_read** entry below; see [transformations](config-details.md#transformations-entry)) -`trans_write` | Transformation key to apply when updating this dotfile (must be defined in the **trans_write** entry below; see [transformations](config-details.md#transformations-entry)) -`upignore` | List of patterns to ignore when updating (enclose in quotes when using wildcards; see [ignore patterns](config.md#ignore-patterns)) -link_children | Replaced by `link: link_children` -trans | Replaced by `trans_read` - -```yaml -: - dst: - src: - ## Optional - link: (nolink|link|link_children) - ignoreempty: (true|false) - cmpignore: - - "" - upignore: - - "" - instignore: - - "" - actions: - - - template: (true|false) - chmod: '' - trans_read: - trans_write: -``` - -## profiles entry - -The **profiles** entry (mandatory) contains a YAML object with sub-objects for the profiles for the different dotfiles that need to be managed. The entries in the sub-objects are as follows: - -Entry | Description --------- | ------------- -`dotfiles` | The dotfiles associated with this profile -`import` | List of paths containing dotfile keys for this profile (absolute path or relative to the config file location; see [Import profile dotfiles from file](config-details.md#profile-import-entry)). -`include` | Include all elements (dotfiles, actions, (dyn)variables, etc) from another profile (See [Include dotfiles from another profile](config-details.md#profile-include-entry)) -`variables` | Profile-specific variables (See [Variables](config.md#variables)) -`dynvariables` | Profile-specific interpreted variables (See [Interpreted variables](config-details.md#dynvariables-entry)) -`actions` | List of action keys that need to be defined in the **actions** entry below (See [actions](config-details.md#actions-entry)) - -```yaml -: - dotfiles: - - - - - - ... - ## Optional - include: - - - - ... - variables: - : - dynvariables: - : - actions: - - - - ... - import: - - - - ... -``` - -## actions entry - -The **actions** entry (optional) contains an actions mapping (See [actions](config-details.md#actions-entry)). - -```yaml -actions: - : -``` - -*pre* actions: -```yaml -actions: - pre: - : -``` - -*post* actions: -```yaml -actions: - post: - : -``` - -## trans_read entry - -The **trans_read** entry (optional) contains a transformations mapping (See [transformations](config-details.md#transformations-entry)). - -```yaml -trans_read: - : -``` - -## trans_write entry - -The **trans_write** entry (optional) contains a write transformations mapping (See [transformations](config-details.md#transformations-entry)). - -```yaml -trans_write: - : -``` - -## variables entry - -The **variables** entry (optional) contains a variables mapping (See [variables](config.md#variables)). - -```yaml -variables: - : -``` - -## dynvariables entry - -The **dynvariables** entry (optional) contains an interpreted variables mapping -(See [Interpreted variables](config-details.md#dynvariables-entry)). - -```yaml -dynvariables: - : -``` - -## uservariables entry - -The **uservariables** entry (optional) contains a collection of variables -whose values are queried from the user -(See [User variables](config-details.md#uservariables-entry)). - -```yaml -uservariables: - : -``` diff --git a/docs/config-profiles.md b/docs/config-profiles.md new file mode 100644 index 0000000..bf8a47a --- /dev/null +++ b/docs/config-profiles.md @@ -0,0 +1,152 @@ +# Profiles entry + +The **profiles** entry (mandatory) contains a YAML object with sub-objects for the profiles for the different dotfiles that need to be managed. The entries in the sub-objects are as follows: + +Entry | Description +-------- | ------------- +`dotfiles` | The dotfiles associated with this profile +`import` | List of paths containing dotfile keys for this profile (absolute path or relative to the config file location; see [Import profile dotfiles from file](config-profiles.md#profile-import-entry)). +`include` | Include all elements (dotfiles, actions, (dyn)variables, etc) from another profile (See [Include dotfiles from another profile](config-profiles.md#profile-include-entry)) +`variables` | Profile-specific variables (See [Variables](config-file.md#variables)) +`dynvariables` | Profile-specific interpreted variables (See [Interpreted variables](config-dynvars.md)) +`actions` | List of action keys that need to be defined in the **actions** entry below (See [actions](config-actions.md)) + +```yaml +: + dotfiles: + - + - + - ... + ## Optional + include: + - + - ... + variables: + : + dynvariables: + : + actions: + - + - ... + import: + - + - ... +``` + +## Profile include entry + +If one profile is using the entire set of another profile, one can use +the `include` entry to avoid redundancy. + +Note that everything from the included profile is made available +(actions, variables/dynvariables, etc). + +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`. + +For more advanced use-cases, variables +([variables](config-variables.md) and [dynvariables](config-dynvars.md)) +can be used to specify the profile to include in a profile: + +For example: +```yaml +variables: + var1: "john" +dynvariables: + d_user: "echo $USER" +profiles: + profile_john: + dotfiles: + - f_john_dotfile + profile_bill: + dotfiles: + - f_bill_dotfile + p1: + include: + - "profile_{{@@ d_user @@}}" + p2: + include: + - "profile_{{@@ var1 @@}}" +``` + +Note that profiles cannot include other profiles defined above in +the import tree (for example, when a profile exists in another file and is imported using `import_configs`). + +## Profile import entry + +A profile's dotfiles list can be loaded from external files +by specifying their paths in the config entry `import` under the specific profile. + +The paths can be absolute or relative to the config file location. + +`config.yaml` +```yaml +dotfiles: + f_abc: + dst: ~/.abc + src: abc + f_def: + dst: ~/.def + src: def + f_xyz: + dst: ~/.xyz + src: xyz +profiles: + p1: + dotfiles: + - f_abc + import: + - somedotfiles.yaml +``` + +`somedotfiles.yaml` +``` +dotfiles: + - f_def + - f_xyz +``` + +Variables can be used in `import`, what allows to do something like: +```yaml +import: +- profiles.d/{{@@ profile @@}}.yaml +``` + +## Profile variables entry + +Profile variables will take precedence over globally defined variables. +This means that you could do something like this: +```yaml +variables: + git_email: home@email.com +dotfiles: + f_gitconfig: + dst: ~/.gitconfig + src: gitconfig +profiles: + work: + dotfiles: + - f_gitconfig + variables: + git_email: work@email.com + private: + dotfiles: + - f_gitconfig +``` + +## Profile actions entry + +A profile action can be either a `pre` or `post` action (see [actions](config-actions.md)). +These are executed before any dotfile installation (for `pre`) and after all dotfile installations (for `post`) +only if at least one dotfile has been installed. \ No newline at end of file diff --git a/docs/config-transformations.md b/docs/config-transformations.md new file mode 100644 index 0000000..955f940 --- /dev/null +++ b/docs/config-transformations.md @@ -0,0 +1,100 @@ +# Transformations entry + +For examples of transformation uses, see: + +* [Handle compressed directories](howto/store-compressed-directories.md) +* [Handle secrets](howto/sensitive-dotfiles.md) + +**Notes**: + +* Any transformation with a key starting with an underscore (`_`) won't be shown in output. This can be useful when working with sensitive data containing passwords, for example. +* Make sure to quote your transformations to avoid bad surprises +* Transformations are executed using the default shell (`$SHELL`) +* To use shell variables in your transformations you need to escape the curly brackets (`${HOME}` becomes `${{HOME}}`) + +There are two types of transformations available: + +* **Read transformations**: used to transform dotfiles before they are installed ([config](config-config.md) key `trans_read`) + * Used for commands `install` and `compare` + * They have two arguments: + * **{0}** will be replaced with the dotfile to process + * **{1}** will be replaced with a temporary file to store the result of the transformation + * This Happens **before** the dotfile is templated (see [templating](templating.md)) + +* **Write transformations**: used to transform files before updating a dotfile ([config](config-config.md) key `trans_write`) + * Used for command `update` + * They have two arguments: + * **{0}** will be replaced with the file path to update the dotfile with + * **{1}** will be replaced with a temporary file to store the result of the transformation + +A typical use-case for transformations is when dotfiles need to be +stored encrypted or compressed. For more, see [the howto](howto/howto.md). + +Note that transformations cannot be used if the dotfile is to be linked (when `link: link` or `link: link_children`). + +Transformations also support additional positional arguments that must start from 2 (since `{0}` and `{1}` are added automatically). The transformations themselves as well as their arguments can also be templated. + +For example: +```yaml +trans_read: + targ: echo "$(basename {0}); {{@@ _dotfile_key @@}}; {2}; {3}" > {1} +dotfiles: + f_abc: + dst: /tmp/abc + src: abc + trans_read: targ "{{@@ profile @@}}" lastarg +profiles: + p1: + dotfiles: + - f_abc +``` + +will result in `abc; f_abc; p1; lastarg`. + +## trans_read entry + +The **trans_read** entry (optional) contains a transformations mapping (See [transformations](config-transformations.md)). + +```yaml +trans_read: + : +``` + +## trans_write entry + +The **trans_write** entry (optional) contains a write transformations mapping (See [transformations](config-transformations.md)). + +```yaml +trans_write: + : +``` + +## Dynamic transformations + +As for [dynamic actions](config-actions.md#dynamic-actions), transformations support +the use of variables ([variables and dynvariables](config-file.md#variables) +and [template variables](templating.md#template-variables)). + +A very dumb example: +```yaml +trans_read: + r_echo_abs_src: echo "{0}: {{@@ _dotfile_abs_src @@}}" > {1} + r_echo_var: echo "{0}: {{@@ r_var @@}}" > {1} +trans_write: + w_echo_key: echo "{0}: {{@@ _dotfile_key @@}}" > {1} + w_echo_var: echo "{0}: {{@@ w_var @@}}" > {1} +variables: + r_var: readvar + w_var: writevar +dotfiles: + f_abc: + dst: ${tmpd}/abc + src: abc + trans_read: r_echo_abs_src + trans_write: w_echo_key + f_def: + dst: ${tmpd}/def + src: def + trans_read: r_echo_var + trans_write: w_echo_var +``` diff --git a/docs/config-uservars.md b/docs/config-uservars.md new file mode 100644 index 0000000..9c77676 --- /dev/null +++ b/docs/config-uservars.md @@ -0,0 +1,41 @@ +# Uservariables entry + +The **uservariables** entry (optional) contains a collection of variables +whose values are queried from the user +(See [User variables](config-variables.md)). + +```yaml +uservariables: + : +``` + +If you want to manually enter variables' values, you can use the +`uservariables` entry. Each variable will be prompted to the user. + +For example: +```yaml +uservariables: + emailvar: "email" +``` + +will prompt the user to enter a value for the variable `emailvar`: +``` +Please provide the value for "email": +``` + +And store the entered text as the value for the variable `email`. +The variable can then be used as any other [variable](config-file.md#variables). + +`uservariables` are eventually saved to `uservariables.yaml` (relatively to the +config file). +This allows to use the following construct to prompt once for some specific variables and +then store them in a file. You might also want to add `uservariables.yaml` to your `.gitignore`. +```yaml +uservariables: + emailvar: "email" +config: + import_variables: + - uservariables.yaml:optional +``` + +For an example, see [prompt user for variables](howto/prompt-user-for-variables.md). diff --git a/docs/config-variables.md b/docs/config-variables.md new file mode 100644 index 0000000..38e310a --- /dev/null +++ b/docs/config-variables.md @@ -0,0 +1,36 @@ +# Variables entry + +The **variables** entry (optional) contains a variables mapping (See [variables](config-file.md#variables)). + +```yaml +variables: + : +``` + +Variables defined in the `variables` entry are made available within the config file. + +Config variables are recursively evaluated, which means that +a config like the below: +```yaml +variables: + var1: "var1" + var2: "{{@@ var1 @@}} var2" + var3: "{{@@ var2 @@}} var3" + var4: "{{@@ dvar4 @@}}" +dynvariables: + dvar1: "echo dvar1" + dvar2: "{{@@ dvar1 @@}} dvar2" + dvar3: "{{@@ dvar2 @@}} dvar3" + dvar4: "echo {{@@ var3 @@}}" +``` + +will result in the following available variables: + +* var1: `var1` +* var2: `var1 var2` +* var3: `var1 var2 var3` +* var4: `echo var1 var2 var3` +* dvar1: `dvar1` +* dvar2: `dvar1 dvar2` +* dvar3: `dvar1 dvar2 dvar3` +* dvar4: `var1 var2 var3` \ No newline at end of file diff --git a/docs/repository-setup.md b/docs/getting-started.md similarity index 58% rename from docs/repository-setup.md rename to docs/getting-started.md index c6e18ee..231cc41 100644 --- a/docs/repository-setup.md +++ b/docs/getting-started.md @@ -1,4 +1,6 @@ -# Repository setup +# Getting started + +## Repository setup Either create a Git repository on your prefered platform and clone it or create one locally. This repository will contain two main elements, dotdrop's config file (`config.yaml`) @@ -21,7 +23,7 @@ $ wget https://raw.githubusercontent.com/deadc0de6/dotdrop/master/config.yaml ``` It is recommended to store your config file directly within your repository (*my-dotfiles* in the example above), but you could save it in different places if you wish; -see [config location](config.md#location) for more. +see [config location](config-file.md#location) for more. ```bash $ tree my-dotfiles @@ -36,7 +38,20 @@ in your preferred shell to call dotdrop with the config file path argument. alias dotdrop='dotdrop --cfg=' ``` -For more info on the config file format, see [the config doc](config.md). +For more info on the config file format, see [the config file doc](config-file.md). -Finally start using dotdrop with `dotdrop --help`. See the [usage doc](usage.md) -and [the example](https://github.com/deadc0de6/dotdrop/blob/master/README.md#getting-started). +## Basic usage + +The basic use of dotdrop is: + +* Import a file/directory to manage (this will copy the files from the filesystem to your `dotpath`): `dotdrop import ` +* Install the dotfiles (this will *copy/link* them from your `dotpath` to the filesystem): `dotdrop install` + +Then if you happen to update the file/directory directly on the filesystem (add a new file/dir, edit content, etc.) you can use the `update` command to mirror back those changes in dotdrop. + +For more advanced uses: + +* `dotdrop --help` for the CLI usage. +* [The usage doc](usage.md) +* [The example](https://github.com/deadc0de6/dotdrop#getting-started) +* [The howto](howto/howto.md) \ No newline at end of file diff --git a/docs/howto/append.md b/docs/howto/append.md index 61fa6f3..a8cd00c 100644 --- a/docs/howto/append.md +++ b/docs/howto/append.md @@ -2,7 +2,7 @@ Sometimes it might be useful to be able to append some text to a file. Dotdrop is able to do that with the help of -[actions](../config-details.md#actions-entry) and a temporary file. +[actions](../config-actions.md) and a temporary file. Below is a config example to append to a file: ```yaml diff --git a/docs/howto/create-special-files.md b/docs/howto/create-special-files.md index 7e556ef..b684825 100644 --- a/docs/howto/create-special-files.md +++ b/docs/howto/create-special-files.md @@ -1,7 +1,7 @@ # Create files on install One way to create symlinks (or any other special file) is to use a combination of -[actions](../config-details.md#actions-entry) and a *fake* dotfile. +[actions](../config-actions.md) and a *fake* dotfile. Let's say, for example, you have a list of directories you want to link from under `~/.original` to `~/symlinks`. diff --git a/docs/howto/merge-files-when-installing.md b/docs/howto/merge-files-when-installing.md index 52dabbf..bc36955 100644 --- a/docs/howto/merge-files-when-installing.md +++ b/docs/howto/merge-files-when-installing.md @@ -1,6 +1,6 @@ # Merge files on install -Dotdrop allows you to merge multiple files into one using Jinja2's `include` directive. +Dotdrop allows to merge multiple files into one using Jinja2's `include` directive. For example, let's assume you want to keep your `.vimrc` split into multiple parts in dotdrop: * `/vimrc.d/top`: top part of the file @@ -48,12 +48,12 @@ Dotdrop will then automagically include the files into your vimrc when handling ## Merge all files in a directory To include all files in a directory, a combination of -[dynvariables](../config-details.md#dynvariables-entry) +[dynvariables](../config-dynvars.md) and [Jinja2 directives](https://jinja.palletsprojects.com/en/2.11.x/) have to be used. Let's say all files in `/toinclude` need to be included into a dotfile. -First define a [dynvariables](../config-details.md#dynvariables-entry) +First define a [dynvariables](../config-dynvars.md) in the config file which will look for files to include in the above directory: ```yaml dynvariables: diff --git a/docs/howto/prompt-user-for-variables.md b/docs/howto/prompt-user-for-variables.md index 9b1c91d..6958906 100644 --- a/docs/howto/prompt-user-for-variables.md +++ b/docs/howto/prompt-user-for-variables.md @@ -1,12 +1,12 @@ # Prompt user for variables -With the use of [uservariables](../config-details.md#uservariables-entry), +With the use of [uservariables](../config-uservars.md), one can define specific variables that need to be initially filled in manually by the user on first run. The provided values are then automatically saved by dotdrop to `uservariables.yaml`, which can be included in the main config as a file from which variables are imported -using [import_variables](../config-details.md#import_variables-entry). +using [import_variables](../config-config.md). Let's say, for example, that you want to manually provide the email value on new hosts you deploy your dotfiles to. diff --git a/docs/howto/sensitive-dotfiles.md b/docs/howto/sensitive-dotfiles.md index 9468929..56ccdf0 100644 --- a/docs/howto/sensitive-dotfiles.md +++ b/docs/howto/sensitive-dotfiles.md @@ -19,7 +19,7 @@ trans_read: _gpg: gpg2 -q --for-your-eyes-only --no-tty -d {0} > {1} ``` -The above config allows you to store the dotfile `~/.secret` encrypted in the *dotpath* +The above config allows 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 the above solution: @@ -47,7 +47,7 @@ $ cp dotfiles/secret * Commit and push the changes -See [transformations](../config-details.md#transformations-entry). +See [transformations](../config-transformations.md). ## Load passphrase from file @@ -67,4 +67,4 @@ trans_read: _gpg: "gpg2 --batch --yes --passphrase-file <(cat {{@@ gpg_password_file @@}}) -q --for-your-eyes-only --no-tty -d {0} > {1}" ``` -See [transformations](../config-details.md#transformations-entry). +See [transformations](../config-transformations.md). diff --git a/docs/howto/sharing-content.md b/docs/howto/sharing-content.md index 8f4ea73..435816e 100644 --- a/docs/howto/sharing-content.md +++ b/docs/howto/sharing-content.md @@ -66,7 +66,7 @@ export DB_PORT='4521' 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 of using -[profile variables](../config-details.md#profile-variables-entry). This is achieved by: +[profile variables](../config-profiles.md#profile-variables-entry). This is achieved by: 1. Creating the merged dotfile with an arbitrary name somewhere in `dotpath`. 2. Adding some variables in the merged dotfile via templating. diff --git a/docs/howto/symlink-dotfiles.md b/docs/howto/symlink-dotfiles.md index bbc2f3b..f155c8b 100644 --- a/docs/howto/symlink-dotfiles.md +++ b/docs/howto/symlink-dotfiles.md @@ -86,7 +86,7 @@ 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.). -A cleaner solution is to use `link_children` which allows you to only symlink +A cleaner solution is to use `link_children` which allows 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 and cleaned of all unwanted files/directories, and then the `link` entry is set to `link_children` in the config file: @@ -121,10 +121,10 @@ $ tree -L 1 ~/.vim ## Templating symlinked dotfiles Dotfiles not using any templating directives are directly linked -to dotdrop's `dotpath` directory (see [Config](../config.md)). +to dotdrop's `dotpath` directory (see [the config file doc](../config-file.md)). When using templating directives, however, the dotfiles are first installed into -`workdir` (defaults to *~/.config/dotdrop*; see [Config format](../config-format.md)) +`workdir` (defaults to *~/.config/dotdrop*; see [the doc](../config-config.md)) and then symlinked there. This applies to both dotfiles with `link: link` and `link: link_children`. diff --git a/docs/howto/system-config-files.md b/docs/howto/system-config-files.md index fa43584..b9e8e20 100644 --- a/docs/howto/system-config-files.md +++ b/docs/howto/system-config-files.md @@ -1,6 +1,6 @@ # Manage system dotfiles -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. +Dotdrop doesn't allow 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 manage unprivileged and privileged files in the same *session* is a bad idea as the resulting files will all have messed-up owners. diff --git a/docs/installation.md b/docs/installation.md index ec6bbfc..40d2915 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -38,9 +38,9 @@ shell with the config file path; for example: alias dotdrop= --cfg=' ``` -## As a submodule in a virtualenv +### As a submodule in a virtualenv -To install in a [virtualenv](https://virtualenv.pypa.io): +To install it in a [virtualenv](https://virtualenv.pypa.io): ```bash ## create the repository $ mkdir dotfiles; cd dotfiles @@ -66,6 +66,46 @@ $ ./dotdrop.sh --help Then follow the instructions under [As a submodule](#as-a-submodule). +### Upgrade dotdrop submodule + +If using dotdrop as a submodule, one can control if dotdrop +is auto-updated through the [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/dotdrop.sh) +script by defining the environment variable `DOTDROP_AUTOUPDATE=yes`. +If undefined, `DOTDROP_AUTOUPDATE` will take the value `yes`. + +If used as a submodule, update it with: +```bash +$ git submodule update --init --recursive +$ git submodule update --remote dotdrop +``` + +You will then need to commit the changes with: +```bash +$ git add dotdrop +$ git commit -m 'update dotdrop' +$ git push +``` + +### Downgrade dotdrop submodule + +If you wish to get a specific version of dotdrop when using +it as a submodule, the following operations can be done. + +Here dotdrop is downgraded to the latest stable version: +```bash +## enter the repository containing the dotdrop submodule +$ cd my-dotfiles +## enter the dotdrop submodule +$ cd dotdrop +## update the list of tags +$ git fetch --tags +## checkout the latest stable version +$ git checkout `git tag -l | tail -1` +``` + +If using the `dotdrop.sh` script, make sure it doesn't +automatically update dotdrop back to the latest commit. + ## PyPI package Install dotdrop: @@ -73,9 +113,7 @@ Install dotdrop: $ pip3 install dotdrop --user ``` -and then [set up your repository](repository-setup.md). - -## PyPI package in a virtualenv +### PyPI package in a virtualenv Install dotdrop from PyPI in a virtualenv: ```bash @@ -109,8 +147,6 @@ Dotdrop is available on aur: Make sure to install the [python-magic-ahupp](https://aur.archlinux.org/packages/python-magic-ahupp/) from aur. -Then follow the [doc to setup your repository](repository-setup.md). - ## Snap package Dotdrop is available as a snap package: . @@ -120,8 +156,6 @@ Install it with: snap install dotdrop ``` -Then follow the [doc to setup your repository](repository-setup.md). - If you encounter warnings like `Warning: using regular magic file`, try defining the following environment variable: ```bash @@ -148,7 +182,7 @@ $ ./dotdrop.sh --cfg files Beside the Python dependencies defined in [requirements.txt](https://github.com/deadc0de6/dotdrop/blob/master/requirements.txt), dotdrop depends on the following tools: -* `diff` (unless a different tool is used, see [diff_command](config-format.md#config-entry)) +* `diff` (unless a different tool is used, see [diff_command](config-config.md#config-entry)) * `git` (only if using the entry point script [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/dotdrop.sh)) * `readlink` or `realpath` (only if using the entry point script [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/dotdrop.sh)) @@ -162,46 +196,6 @@ For WSL (Windows Subsystem for Linux), make sure to install `python-magic-bin`: pip install python-magic-bin ``` -## Update dotdrop submodule - -If using dotdrop as a submodule, one can control if dotdrop -is auto-updated through the [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/dotdrop.sh) -script by defining the environment variable `DOTDROP_AUTOUPDATE=yes`. -If undefined, `DOTDROP_AUTOUPDATE` will take the value `yes`. - -If used as a submodule, update it with: -```bash -$ git submodule update --init --recursive -$ git submodule update --remote dotdrop -``` - -You will then need to commit the changes with: -```bash -$ git add dotdrop -$ git commit -m 'update dotdrop' -$ git push -``` - -## Downgrade dotdrop submodule - -If you wish to get a specific version of dotdrop when using -it as a submodule, the following operations can be done. - -Here dotdrop is downgraded to the latest stable version: -```bash -## enter the repository containing the dotdrop submodule -$ cd my-dotfiles -## enter the dotdrop submodule -$ cd dotdrop -## update the list of tags -$ git fetch --tags -## checkout the latest stable version -$ git checkout `git tag -l | tail -1` -``` - -If using the `dotdrop.sh` script, make sure it doesn't -automatically update dotdrop back to the latest commit. - ## Shell completion Completion scripts exist for `bash`, `zsh` and `fish`; diff --git a/docs/templating.md b/docs/templating.md index 5450218..9870877 100644 --- a/docs/templating.md +++ b/docs/templating.md @@ -6,9 +6,9 @@ or the below sections for more information on how to template your dotfiles. ## Templating or not templating -The dotfile config entry [template](config-format.md#dotfiles-entry) -and the global config entry [template_dotfile_default](config-format.md#config-entry) -allow you to control whether a dotfile is processed by the templating engine. +The dotfile config entry [template](config-dotfiles.md#dotfiles-entry) +and the global config entry [template_dotfile_default](config-config.md) +allow to control whether a dotfile is processed by the templating engine. Obviously, if the dotfile uses template directives, it needs to be templated. However, if it is not, disabling templating will speed up its installation (since it won't have to be @@ -38,16 +38,16 @@ The following variables are available in templates: * `{{@@ profile @@}}` contains the profile provided to dotdrop. * `{{@@ env['MY_VAR'] @@}}` contains environment variables (see [Environment variables](#environment-variables)). * `{{@@ header() @@}}` contains the dotdrop header (see [Dotdrop header](#dotdrop-header)). -* `{{@@ _dotdrop_dotpath @@}}` contains the [dotpath](config-format.md) absolute path. -* `{{@@ _dotdrop_cfgpath @@}}` contains the absolute path to the [config file](config.md). -* `{{@@ _dotdrop_workdir @@}}` contains the [workdir](config-format.md) absolute path. +* `{{@@ _dotdrop_dotpath @@}}` contains the [dotpath](config-config.md) absolute path. +* `{{@@ _dotdrop_cfgpath @@}}` contains the absolute path to the [config file](config-file.md). +* `{{@@ _dotdrop_workdir @@}}` contains the [workdir](config-config.md) absolute path. * Dotfile specific variables (see [Dotfile variables](#dotfile-variables)) -* All defined config variables (see [Variables](config.md#variables)) -* All defined config interpreted variables (see [Interpreted variables](config-details.md#dynvariables-entry)) +* All defined config variables (see [Variables](config-file.md#variables)) +* All defined config interpreted variables (see [Interpreted variables](config-dynvars.md#dynvariables-entry)) ## Dotfile variables -When a dotfile is handled by dotdrop, the following variables are added: +When a dotfile is handled by dotdrop, the following variables are also available for templating: * `{{@@ _dotfile_abs_src @@}}` contains the processed dotfile absolute source path. * `{{@@ _dotfile_abs_dst @@}}` contains the processed dotfile absolute destination path. @@ -73,7 +73,7 @@ It's possible to access environment variables inside the templates: ``` This allows for storing host-specific properties and/or secrets in environment variables. -It is recommended to use `variables` (see [config variables](config.md#variables)) +It is recommended to use `variables` (see [config variables](config-file.md#variables)) instead of environment variables unless these contain sensitive information that shouldn't be versioned in Git. @@ -192,7 +192,7 @@ For more information, see the [dedicated Jinja2 docs](https://jinja.palletsproje ## Dotdrop header -Dotdrop is able to insert a header in the generated dotfiles. This allows you +Dotdrop is able to insert a header in the generated dotfiles. This allows to remind anyone opening the file for editing that this file is managed by dotdrop. Here's what it looks like: diff --git a/docs/usage.md b/docs/usage.md index 2923be5..8b1ceee 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -2,21 +2,6 @@ Run `dotdrop --help` to see all available options. -## Basic usage - -The basic use of dotdrop is: - -* Import a file/directory to manage (this will copy the files from the filesystem to your `dotpath`): `dotdrop import ` -* Install the dotfiles (this will *copy/link* them from your `dotpath` to the filesystem): `dotdrop install` - -Then if you happen to update the file/directory directly on the filesystem (add a new file/dir, edit content, etc.) you can use the `update` command to mirror back those changes in dotdrop. - -For more advanced uses: - -* `dotdrop --help` for the CLI usage. -* [The example](https://github.com/deadc0de6/dotdrop#getting-started) -* [The howto](howto/howto.md) - ## Profile The default profile used by dotdrop is the *hostname* of the host you are running dotdrop on. @@ -26,6 +11,20 @@ It can be changed: * Using the command line switch `-p`/`--profile=` * By defining it in the env variable `DOTDROP_PROFILE` +## List profiles + +The `profiles` command lists the profiles defined in the config file. +```bash +$ dotdrop profiles +``` + +Dotdrop allows to choose which profile to use +with the `--profile` switch if you use something +other than the default (the hostname). + +The default profile can also be changed by defining the +`DOTDROP_PROFILE` environment variable. + ## Import dotfiles The `import` command imports dotfiles to be managed by dotdrop. @@ -42,11 +41,11 @@ $ dotdrop import ~/.xinitrc ``` You can control how the dotfile key is generated in the config file -with the following config entries: +with the following [config entries](config-config.md): * `longkey` - * *short format* (default): take the shortest unique path - * *long format*: take the full path + * `false` (default): take the shortest unique path + * `true` take the full path * `key_prefix`: defines if the key is prefixed with `f` for file and `d` for directory * `key_separator`: defines the separator to use (defaults to `_`) @@ -69,7 +68,7 @@ dotfile management. $ dotdrop import ~/.zshrc --as=~/.zshrc.test ``` -To ignore specific patterns during import, see [the ignore patterns](config.md#ignore-patterns). +To ignore specific patterns during import, see [the ignore patterns](config-file.md#ignore-patterns). For more options, see the usage with `dotdrop --help`. @@ -86,11 +85,11 @@ Some available options: * `-t`/`--temp`: Install the dotfile(s) to a temporary directory for review (helping to debug templating issues, for example). Note that actions are not executed in this mode. -* `-a`/`--force-actions`: Force the execution of actions even if the dotfiles are not installed +* `-a`/`--force-actions`: Force the execution of actions even if the dotfiles are not installed (see [Fake dotfile and actions](config-actions.md#fake-dotfile-and-actions) as an alternative) * `-f`/`--force`: Do not ask for any confirmation -* `-W`/`--workdir-clear`: Clear the `workdir` before installing dotfiles (see config entry `clear_workdir`) +* `-W`/`--workdir-clear`: Clear the `workdir` before installing dotfiles (see [the config entry](config-config.md) `clear_workdir`) -To ignore specific patterns during installation, see [the ignore patterns](config.md#ignore-patterns). +To ignore specific patterns during installation, see [the ignore patterns](config-file.md#ignore-patterns). For more options, see the usage with `dotdrop --help`. @@ -102,36 +101,22 @@ $ dotdrop compare ``` The diffing is done with the UNIX tool `diff` as the backend; one can provide a specific -diff command using the config entry `diff_command`. +diff command using [the config entry](config-config.md) `diff_command`. You can specify against which destination file to compare: ```bash $ dotdrop compare -C ~/.vimrc ``` -To ignore specific patterns, see [the ignore patterns](config.md#ignore-patterns). +To ignore specific patterns, see [the ignore patterns](config-file.md#ignore-patterns). -To completely ignore all files not present in `dotpath` see [Ignore missing](#ignore-missing). +To completely ignore all files not present in `dotpath` see [Ignore missing](config-file.md#ignore-missing). If you want to get notified on files present in the `workdir` but not tracked -by dotdrop see the [compare_workdir](config-format.md). +by dotdrop see the [compare_workdir](config-config.md). For more options, see the usage with `dotdrop --help`. -## List profiles - -The `profiles` command lists the profiles defined in the config file. -```bash -$ dotdrop profiles -``` - -Dotdrop allows you to choose which profile to use -with the `--profile` switch if you use something -other than the default (the hostname). - -The default profile can also be changed by defining the -`DOTDROP_PROFILE` environment variable. - ## List dotfiles The `files` command lists the dotfiles declared for a specific profile. @@ -180,13 +165,16 @@ $ dotdrop update --key f_vimrc If not argument is provided, all dotfiles for the selected profile are updated. -To ignore specific patterns, see [the dedicated page](config.md#ignore-patterns). +To ignore specific patterns, see [the dedicated page](config-file.md#ignore-patterns). -To completely ignore all files not present in `dotpath`, see [Ignore missing](#ignore-missing). +To completely ignore all files not present in `dotpath`, see [Ignore missing](config-file.md#ignore-missing). There are two cases when updating a dotfile: -### The dotfile doesn't use [templating](templating.md) +* [The dotfile does not use templating](#the-dotfile-does-not-use-templating) +* [The dotfile uses templating](#the-dotfile-uses-templating) + +### The dotfile does not use [templating](templating.md) The new version of the dotfile is copied to the *dotpath* directory and overwrites the old version. If Git is used to version the dotfiles stored by dotdrop, the Git command @@ -229,17 +217,17 @@ $ diff ~/.vimrc /tmp/dotdrop-6ajz7565/home/user/.vimrc ## Remove dotfiles -The command `remove` allows you to stop managing a specific dotfile with +The command `remove` allows to stop managing a specific dotfile with dotdrop. It will: * remove the entry from the config file (under `dotfiles` and `profile`) -* remove the file from the `dotpath` +* delete the file from the `dotpath` For more options, see the usage with `dotdrop --help`. ## Concurrency -The command line switch `-w`/`--workers`, if set to a value greater than one, allows you to use +The command line switch `-w`/`--workers`, if set to a value greater than one, allowing to use multiple concurrent workers to execute an operation. It can be applied to the following commands: @@ -296,32 +284,3 @@ export DOTDROP_WORKDIR="/tmp/dotdrop-workdir" ```bash export DOTDROP_WORKERS="10" ``` - -## Ignore missing - -Sometimes, it is nice to have [`update`](#update-dotfiles) not copy all the files in the installed directory -or [`compare`](#compare-dotfiles) diff them. - -For example, -maybe you only want to include a single configuration file in your repository -and don't want to include other files the program uses, -such as a cache. -Maybe you only want to change one file and don't want the others cluttering your repository. -Maybe the program changes these files quite often and creates unnecessary diffs in your dotfiles. - -In these cases, you can use the [ignore-missing](config-format.md) option. -This option is available as a flag (`--ignore-missing` or `-z`) to the `update` and `compare` commands, -or [as a configuration option either globally or on a specific dotfile](config-format.md). - -To configure globally, place the following in `config.yaml`: -```yaml -config: - ignore_missing_in_dotdrop: true -``` - -To configure per dotfile: -```yaml -dotfiles: - f_abc: - ignore_missing_in_dotdrop: true -``` diff --git a/mkdocs.yml b/mkdocs.yml index b05fb4e..8a670cc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -9,15 +9,24 @@ theme: collapse_navigation: false use_directory_urls: true nav: - - Dotdrop: 'README.md' - - Installation: 'installation.md' - - 'Repository setup': 'repository-setup.md' - - Usage: 'usage.md' - - Config: 'config.md' - - 'Config format': 'config-format.md' - - 'Config details': 'config-details.md' - - Templating: 'templating.md' - - HowTo: 'howto/howto.md' + - 'Dotdrop': 'README.md' + - 'Installation': 'installation.md' + - 'Getting started': 'getting-started.md' + - 'Usage': 'usage.md' + - 'Config': + - 'Config file': 'config-file.md' + - 'Config': 'config-config.md' + - 'Dotfiles': 'config-dotfiles.md' + - 'Profiles': 'config-profiles.md' + - 'Actions': 'config-actions.md' + - 'Transformations': 'config-transformations.md' + - 'Variables': 'config-variables.md' + - 'Dynvariables': 'config-dynvars.md' + - 'Uservariables': 'config-uservars.md' + - 'Templating': + - 'Templating': 'templating.md' + - 'More': + - 'HowTo': 'howto/howto.md' markdown_extensions: - meta - tables