docs: Add dotfile description

README.md

@@ -19,7 +19,7 @@ For installation and usage, see our
 
 ## Why Rash
 
-Manage your docker entrypoints in a declarative style.
+Manage your scripts in a declarative style.
 
 If you:
 
@@ -85,6 +85,35 @@ Declarative: `entrypoint.rh`
     APP1_API_KEY: "{{ lookup('vault', env.VAULT_SECRET_PATH ) }}"
 ```
 
+### Docopts
+
+(docopt)[http://docopt.org/] implementation included:
+
+- Easy to define interfaces for command-line app.
+- Automatically generate a parser from doc.
+
+Example:
+
+```yaml
+#!/usr/bin/env -S rash --
+#
+# Copy files from source to dest dir
+#
+# Usage:
+#   copy.rh [options] <source>... <dest>
+#   copy.rh
+#
+# Options:
+#   -h --help    show this help message and exit
+#   --mode MODE  dest file permissions [default: 0644]
+
+- copy:
+    src: "{{ item }}"
+    dest: "{{ dest }}/{{ item | split(pat='/') | last }}"
+    mode: "{{ options.mode }}"
+  loop: "{{ source | default (value=[]) }}"
+```
+
 ### Lightness
 
 All you need to run Rash is a Linux kernel!
@@ -93,9 +122,4 @@ You can use it in your favorite IoT chips running Linux or in containers from sc
 
 ## Status
 
-Stable API with few modules. It will be growing, stay tuned.
-
-## Who is using `rash`
-
-- A production ready [php-fpm](https://github.com/dcarrillo/docker-phpfpm) docker image
-- [hs110 prometheus exporter](https://github.com/sdelrio/hs110-prometheus-exporter)
+Stable API with few modules.

examples/dotfiles/dots

@@ -0,0 +1,85 @@
+#!/usr/bin/env -S rash --diff
+#
+# dots easy manage of your dotfiles.
+# Usage:
+#   ./dots (install|update|help) <package_filters>...
+#
+# Arguments:
+#   package_filters   List of regex matching packages wanted.
+#
+# Options:
+#   -c,--check  dry-run mode
+#
+# Example:
+#   ./dots install --check '.*zsh.*'
+#
+# Subcommands:
+#   install      Copy files to host.
+#   update    Get files from host.
+#   help         Show this screen.
+#
+- name: set vars
+  set_vars:
+    dotfiles_dir: "{{ rash.dir }}/dotfiles"
+    templates_pattern: ".*\\.j2"
+
+- name: find dotfiles to copy
+  find:
+    paths: "{{ dotfiles_dir }}"
+    hidden: true
+    patterns: "{{ package_filters | default(value=omit()) | json_encode() }}"
+    excludes: "{{ templates_pattern }}"
+    recurse: true
+  changed_when: false
+  register: dotfiles
+
+- name: find dotfiles to render
+  find:
+    paths: "{{ dotfiles_dir }}"
+    hidden: true
+    patterns: "{{ templates_pattern }}"
+    recurse: true
+  changed_when: false
+  register: dotfile_templates
+  when: package_filters is not defined
+
+- name: find dotfiles directories to create dir structure
+  find:
+    paths: "{{ dotfiles_dir }}"
+    hidden: true
+    recurse: true
+    excludes: dotfiles
+    file_type: directory
+  changed_when: false
+  register: dotfiles_dirs
+
+- name: create dotfiles directories
+  file:
+    path: "{{ item | replace(from=dotfiles_dir, to=env.HOME) }}"
+    state: "directory"
+  loop: "{{ dotfiles_dirs.extra }}"
+  when: install
+
+- name: copy dotfiles
+  copy:
+    src: "{{ item }}"
+    dest: "{{ item | replace(from=dotfiles_dir, to=env.HOME) }}"
+    mode: preserve
+  loop: "{{ dotfiles.extra }}"
+  when: install
+
+- name: render dotfiles templates
+  template:
+    src: "{{ item }}"
+    dest: "{{ item | replace(from=dotfiles_dir, to=env.HOME) | replace(from='.j2', to='') }}"
+    mode: preserve
+  loop: "{{ dotfile_templates.extra | default(value=[]) }}"
+  when: install
+
+- name: update dotfiles
+  copy:
+    src: "{{ item | replace(from=dotfiles_dir, to=env.HOME) }}"
+    dest: "{{ item }}"
+    mode: preserve
+  loop: "{{ dotfiles.extra }}"
+  when: update