update man for v1.5.0

spot.1

@@ -1,4 +1,4 @@
-.TH "SPOT" 1  v1.4.0 spot manual
+.TH "SPOT" 1  1.5.0 spot manual
 .\" Automatically generated by Pandoc 3.1.2
 .\"
 .\" Define V font for inline verbatim, using C font in formats
@@ -212,6 +212,33 @@ messages.
 .IP \[bu] 2
 \f[V]-h\f[R] \f[V]--help\f[R]: Displays the help message, listing all
 available command-line options.
+.SS Basic Concepts
+.IP \[bu] 2
+\f[B]Playbook\f[R] is a YAML or TOML file that defines a list of tasks
+to be executed on one or more target hosts.
+Each task consists of a series of commands that can be executed on the
+target hosts.
+Playbooks can be used to automate deployment and configuration
+management tasks.
+.IP \[bu] 2
+\f[B]Task\f[R] is a named set of commands that can be executed on one or
+more target hosts.
+Tasks can be defined in a playbook and can be executed concurrently on
+multiple hosts.
+.IP \[bu] 2
+\f[B]Command\f[R] is an action that can be executed on a target host.
+Spot supports several built-in commands, including copy, sync, delete,
+script, echo and wait.
+.IP \[bu] 2
+\f[B]Target\f[R] is a host or group of hosts on which a task can be
+executed.
+Targets can be specified directly in a playbook or can be defined in an
+inventory file.
+Spot supports several inventory file formats.
+.IP \[bu] 2
+\f[B]Inventory\f[R] is a list of targets that can be used to define the
+hosts and groups of hosts on which a task can be executed.
+.SS Playbooks
 .SS Full playbook example
 .IP
 .nf
@@ -376,7 +403,7 @@ This is useful when user want to run the playbook on a single host only.
 The full playbook does not have this field.
 .PP
 Both types of playbooks support the remaining fields and options.
-.SS Task details
+.SS Tasks and Commands
 .PP
 Each task consists of a list of commands that will be executed on the
 remote host(s).
@@ -411,50 +438,6 @@ identify the task everywhere.
 Playbook with missing \f[V]name\f[R] field will fail to execute
 immediately.
 Duplicate task names are not allowed either.
-.SS Dynamic targets
-.PP
-Spot offers support for dynamic targets, allowing the list of targets to
-be defined dynamically using variables.
-This feature becomes particularly useful when users need to ascertain a
-destination address within one task, and subsequently use it in another
-task.
-Here is an illustrative example:
-.IP
-.nf
-\f[C]
-tasks:
-  - name: get host
-    targets: [\[dq]default\[dq]]
-    script: |
-      export thehost=$(curl -s http://example.com/next-host)
-    options: {local: true}
-
-  - name: run on host
-    targets: [\[dq]$thehost\[dq]]
-    script: |
-      echo \[dq]doing something on $thehost\[dq]
-\f[R]
-.fi
-.PP
-In this example, the host address is initially fetched from
-<http://example.com/next-host>.
-Following this, the task \[dq]run on host\[dq] is executed on the host
-that was just identified.
-This ability to use dynamic targets proves beneficial in a variety of
-scenarios, especially when the list of hosts is not predetermined.
-.PP
-A practical use case for dynamic targets arises during the provisioning
-of a new host, followed by the execution of commands on it.
-Since the IP address of the new host isn\[aq]t known beforehand, dynamic
-retrieval becomes essential.
-.PP
-\f[I]The reason the first task specifies
-\f[VI]targets: [\[dq]default\[dq]]\f[I] is because Spot requires some
-target to execute a task.
-In this case, all commands in \[dq]get host\[dq] tasks are local and
-won\[aq]t be invoked on a remote host.
-The \f[VI]default\f[I] target is utilized by Spot if no alternative
-target is specified via the command line.\f[R]
 .SS Relative paths resolution
 .PP
 Relative path resolution is a frequent issue in systems that involve
@@ -475,55 +458,124 @@ Alternatively, you can use absolute paths for even better results.
 .SS Command Types
 .PP
 Spot supports the following command types:
-.IP \[bu] 2
-\f[V]script\f[R]: can be any valid shell script.
+.SS \f[V]script\f[R]
+.PP
+Can be any valid shell script.
 The script will be executed on the remote host(s) using SSH, inside a
 shell.
-.IP \[bu] 2
-\f[V]copy\f[R]: copies a file from the local machine to the remote
-host(s).
-Example:
-\f[V]copy: {\[dq]src\[dq]: \[dq]testdata/conf.yml\[dq], \[dq]dst\[dq]: \[dq]/tmp/conf.yml\[dq], \[dq]mkdir\[dq]: true}\f[R].
+.IP
+.nf
+\f[C]
+script: |
+  ls -laR /tmp
+  du -hcs /srv
+  cat /tmp/conf.yml
+  echo all good, 123
+\f[R]
+.fi
+.SS \f[V]copy\f[R]
+.PP
+Copies a file from the local machine to the remote host(s).
 If \f[V]mkdir\f[R] is set to \f[V]true\f[R] the command will create the
 destination directory if it doesn\[aq]t exist, same as
 \f[V]mkdir -p\f[R] in bash.
-Note: \f[V]copy\f[R] command type supports multiple commands too, the
-same way as \f[V]mcopy\f[R] below.
-.IP \[bu] 2
-\f[V]mcopy\f[R]: copies multiple files from the local machine to the
-remote host(s).
-Example:
-\f[V]mcopy: [{\[dq]src\[dq]: \[dq]testdata/1.yml\[dq], \[dq]dst\[dq]: \[dq]/tmp/1.yml\[dq], \[dq]mkdir\[dq]: true}, {\[dq]src\[dq]: \[dq]testdata/1.txt\[dq], \[dq]dst\[dq]: \[dq]/tmp/1.txt\[dq]}]\f[R].
-This is just a shortcut for multiple \f[V]copy\f[R] commands.
-.IP \[bu] 2
-\f[V]sync\f[R]: syncs directory from the local machine to the remote
-host(s).
+The command also supports glob patterns in \f[V]src\f[R] field.
+.PP
+Copy command performs a quick check to see if the file already exists on
+the remote host(s) with the same size and modification time, and skips
+the copy if it does.
+This option can be disabled by setting \f[V]force: true\f[R] flag.
+.IP
+.nf
+\f[C]
+- name: copy file with mkdir
+  copy: {\[dq]src\[dq]: \[dq]testdata/conf.yml\[dq], \[dq]dst\[dq]: \[dq]/tmp/conf.yml\[dq], \[dq]mkdir\[dq]: true}\[ga]
+
+- name: copy files with glob
+  copy: {\[dq]src\[dq]: \[dq]testdata/*.csv\[dq], \[dq]dst\[dq]: \[dq]/tmp/things\[dq]}\[ga]
+
+
+- name: copy files with force flag
+  copy: {\[dq]src\[dq]: \[dq]testdata/*.csv\[dq], \[dq]dst\[dq]: \[dq]/tmp/things\[dq], \[dq]force\[dq]: true}\[ga]
+\f[R]
+.fi
+.PP
+Copy also supports list format to copy multiple files at once:
+.IP
+.nf
+\f[C]
+- name: copy files with glob
+  copy:
+    - {\[dq]src\[dq]: \[dq]testdata/*.csv\[dq], \[dq]dst\[dq]: \[dq]/tmp/things\[dq]}
+    - {\[dq]src\[dq]: \[dq]testdata/*.yml\[dq], \[dq]dst\[dq]: \[dq]/tmp/things\[dq]}
+\f[R]
+.fi
+.SS \f[V]sync\f[R]
+.PP
+Synchronises directory from the local machine to the remote host(s).
 Optionally supports deleting files on the remote host(s) that don\[aq]t
-exist locally.
-Example:
-\f[V]sync: {\[dq]src\[dq]: \[dq]testdata\[dq], \[dq]dst\[dq]: \[dq]/tmp/things\[dq], \[dq]delete\[dq]: true}\f[R].
+exist locally with \f[V]\[dq]delete\[dq]: true\f[R] flag.
 Another option is \f[V]exclude\f[R] which allows to specify a list of
 files to exclude from the sync.
-Example:
-\f[V]sync: {\[dq]src\[dq]: \[dq]testdata\[dq], \[dq]dst\[dq]: \[dq]/tmp/things\[dq], \[dq]exclude\[dq]: [\[dq]*.txt\[dq], \[dq]*.yml\[dq]]}\f[R]
-.IP \[bu] 2
-\f[V]delete\f[R]: deletes a file or directory on the remote host(s),
-optionally can remove recursively.
-Example:
-\f[V]delete: {\[dq]path\[dq]: \[dq]/tmp/things\[dq], \[dq]recur\[dq]: true}\f[R]
-.IP \[bu] 2
-\f[V]wait\f[R]: waits for the specified command to finish on the remote
-host(s) with 0 error code.
-This command is useful when you need to wait for a service to start
+.IP
+.nf
+\f[C]
+- name: sync directory
+  sync: {\[dq]src\[dq]: \[dq]testdata\[dq], \[dq]dst\[dq]: \[dq]/tmp/things\[dq]}
+
+- name: sync directory with delete
+  sync: {\[dq]src\[dq]: \[dq]testdata\[dq], \[dq]dst\[dq]: \[dq]/tmp/things\[dq], \[dq]delete\[dq]: true}
+
+- name: sync directory with exclude
+  sync: {\[dq]src\[dq]: \[dq]testdata\[dq], \[dq]dst\[dq]: \[dq]/tmp/things\[dq], \[dq]exclude\[dq]: [\[dq]*.txt\[dq], \[dq]*.yml\[dq]]}
+
+\f[R]
+.fi
+.PP
+Sync also supports list format to sync multiple paths at once.
+.SS \f[V]delete\f[R]
+.PP
+Deletes a file or directory on the remote host(s), optionally can remove
+recursively.
+.IP
+.nf
+\f[C]
+- name: delete file
+  delete: {\[dq]path\[dq]: \[dq]/tmp/things.csv\[dq]}
+- name: delete directory recursively
+  delete: {\[dq]path\[dq]: \[dq]/tmp/things\[dq], \[dq]recur\[dq]: true}
+\f[R]
+.fi
+.PP
+Delete also supports list format to remove multiple paths at once.
+.SS \f[V]wait\f[R]
+.PP
+Waits for the specified command to finish on the remote host(s) with 0
+error code.
+This command is useful when user needs to wait for a service to start
 before executing the next command.
 Allows to specify the timeout as well as check interval.
-Example:
-\f[V]wait: {\[dq]cmd\[dq]: \[dq]curl -s --fail localhost:8080\[dq], \[dq]timeout\[dq]: \[dq]30s\[dq], \[dq]interval\[dq]: \[dq]1s\[dq]}\f[R]
-.IP \[bu] 2
-\f[V]echo\f[R]: prints the specified message to the console.
-Example: \f[V]echo: \[dq]Hello World $some_var\[dq]\f[R].
+.IP
+.nf
+\f[C]
+- name: wait for service to start
+  wait: {\[dq]cmd\[dq]: \[dq]curl -s --fail localhost:8080\[dq], \[dq]timeout\[dq]: \[dq]30s\[dq], \[dq]interval\[dq]: \[dq]1s\[dq]}
+\f[R]
+.fi
+.SS \f[V]echo\f[R]
+.PP
+Prints the specified message to the console.
 This command is useful for debugging purposes and also to print the
 value of variables to the console.
+.IP
+.nf
+\f[C]
+- name: print message
+  echo: \[dq]hello world\[dq]
+- name: print variable
+  echo: $some_var
+\f[R]
+.fi
 .SS Command options
 .PP
 Each command type supports the following options:
@@ -802,6 +854,50 @@ if \f[V]--target\f[R] is not set, Spot will try check it
 If set, it will use it following the same logic as above.
 .IP \[bu] 2
 and finally, Spot will assume the \f[V]default\f[R] target.
+.SS Dynamic targets
+.PP
+Spot offers support for dynamic targets, allowing the list of targets to
+be defined dynamically using variables.
+This feature becomes particularly useful when users need to ascertain a
+destination address within one task, and subsequently use it in another
+task.
+Here is an illustrative example:
+.IP
+.nf
+\f[C]
+tasks:
+  - name: get host
+    targets: [\[dq]default\[dq]]
+    script: |
+      export thehost=$(curl -s http://example.com/next-host)
+    options: {local: true}
+
+  - name: run on host
+    targets: [\[dq]$thehost\[dq]]
+    script: |
+      echo \[dq]doing something on $thehost\[dq]
+\f[R]
+.fi
+.PP
+In this example, the host address is initially fetched from
+<http://example.com/next-host>.
+Following this, the task \[dq]run on host\[dq] is executed on the host
+that was just identified.
+This ability to use dynamic targets proves beneficial in a variety of
+scenarios, especially when the list of hosts is not predetermined.
+.PP
+A practical use case for dynamic targets arises during the provisioning
+of a new host, followed by the execution of commands on it.
+Since the IP address of the new host isn\[aq]t known beforehand, dynamic
+retrieval becomes essential.
+.PP
+\f[I]The reason the first task specifies
+\f[VI]targets: [\[dq]default\[dq]]\f[I] is because Spot requires some
+target to execute a task.
+In this case, all commands in \[dq]get host\[dq] tasks are local and
+won\[aq]t be invoked on a remote host.
+The \f[VI]default\f[I] target is utilized by Spot if no alternative
+target is specified via the command line.\f[R]
 .SS Inventory
 .PP
 The inventory file is a simple yml (or toml) what can represent a list
@@ -1320,6 +1416,9 @@ The project is currently in active development, and breaking changes may
 occur until the release of version 1.0.
 However, we strive to minimize disruptions and will only introduce
 breaking changes when there is a compelling reason to do so.
+.PP
+\f[I]Update: Version 1 has been released and is now considered stable.
+We do not anticipate any breaking changes for this version.\f[R]
 .SS Contributing
 .PP
 Please feel free to open a discussion, submit issues, fork the