From 70de944abc3b598e00357c19981da22b9d770611 Mon Sep 17 00:00:00 2001
From: Alexander Gil <pando855@gmail.com>
Date: Tue, 27 Jun 2023 16:09:52 +0200
Subject: [PATCH] docs: Add dotfile description

Signed-off-by: Alexander Gil <pando855@gmail.com>
---
 README.md                                     | 38 +++++++--
 examples/dotfiles/dotfiles/.home_config_files |  0
 examples/dotfiles/dots                        | 85 +++++++++++++++++++
 3 files changed, 116 insertions(+), 7 deletions(-)
 create mode 100644 examples/dotfiles/dotfiles/.home_config_files
 create mode 100755 examples/dotfiles/dots

diff --git a/README.md b/README.md
index 8f05cc20..ee4f7be9 100644
--- a/README.md
+++ b/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.
diff --git a/examples/dotfiles/dotfiles/.home_config_files b/examples/dotfiles/dotfiles/.home_config_files
new file mode 100644
index 00000000..e69de29b
diff --git a/examples/dotfiles/dots b/examples/dotfiles/dots
new file mode 100755
index 00000000..0ba8ad09
--- /dev/null
+++ b/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