diff --git a/docs/10_Installation.md b/docs/10_Installation.md
index 87785ce0b378a87cd05a45954bebd1e9d1a8a162..5e4b21a3c710778c7ed08fb7c5c9b80b47edd505 100644
--- a/docs/10_Installation.md
+++ b/docs/10_Installation.md
@@ -1,25 +1,25 @@
-# Installation
+## Installation
-# Manual installation
+### Manual installation
In short a manual way:
* Copy the bash script somewhere you like.
* set execute permissions `chmod 0755 onfilechange.sh`
-# Use git
+### Use git
If you have git and want to update the files with a simple git pull
you can do it that way.
-## Get the files
+#### Get the files
```shell
cd /opt
git clone https://gitlab.iml.unibe.ch/iml-open-source/onfilechange.git
```
-## Make script available anywhere
+#### Make script available anywhere
To have a single file in /usr/local/bin you can create a softlink
@@ -28,7 +28,7 @@ cd /usr/local/bin
ln -s /opt/onfilechange/onfilechange
```
-## Update
+#### Update script
To start an update you can use
diff --git a/docs/20_Usage.md b/docs/20_Usage.md
index 0c2be6702699e3d0ade37d38df9014559d0d7d15..0faae15d7e5574cd7b52e37af6775c1679e1be06 100644
--- a/docs/20_Usage.md
+++ b/docs/20_Usage.md
@@ -1,51 +1,133 @@
-# Usage
+## Usage
Start `./onfilechange.sh -h` to get the help
```txt
______________________________________________________________________________
- T R I G G E R C O M M A N D O N A F I L E C H A N G E
-______________________________________________________________________________
- v1.04
+ T R I G G E R C O M M A N D O N A F I L E C H A N G E
+_______________________________________________________________________| v1.06
+
-INFO: stat command detected
HELP:
- This script checks the change of a given file and triggers
- a command if it changes
+
+onfilechange.sh checks the change of a given fileobjects and triggers
+a command on file changes.
+It can use stat or inotifywait to watch a file change. Default is stat because
+it can be used for non existing files.
+
+SYNTAX:
+
+ onfilechange.sh OPTIONS [FILE] [[... FILE N]]
PRAMETERS:
- -c [command]
- command to execute on a file change
- -f [filename(s)]
- filenames to watch; separate multiple files with space and put all in quotes
- -h
- show this help
- -i
- force inotifywait command
- -s
- force stat command (default mode)
- -v
- verbose mode; enable showing debug output
- -w [integer]
- for stat mode: wait time in seconds betweeen each test or on missing file; default: 5 sec
+
+ -c|--command COMMAND
+ A command to execute on a file change
+
+ -f|--file FILENAME
+ Filenames or directories to watch; separate multiple files with
+ space and put all in quotes
+ DEPRECATED: add all files to watch as parameters
+
+ -h|--help
+ show this help
+
+ -i|--inotifywait
+ force inotifywait command
+
+ -s|--stat
+ force stat command (default mode)
+
+ -v
+ verbose mode; enable showing debug output; it should be the first option
+ to see handling of other options
+
+ -w|--wait SLEEPTIME
+ for stat mode: wait time in seconds betweeen each test or on
+ missing file; default: 5 sec
EXAMPLES:
- onfilechange.sh -f /home/me/touchfile.txt -c "ls -l"
- watch touchfile.txt and make a file listing on change
- onfilechange.sh -f "/home/me/touchfile.txt home/me/touchfile2.txt" -c "ls -l"
- watch touchfile.txt and touchfile2.txt
+ onfilechange.sh -c "ls -l" /home/me/touchfile.txt
+ watch touchfile.txt and make a file listing on change
+
+ onfilechange.sh -c "ls -l" "/home/me/touchfile.txt" "home/me/touchfile2.txt"
+ watch touchfile.txt and touchfile2.txt
+
+ onfilechange.sh -s -w 10 -c "echo hello" /home/me/touchfile.txt
+ watch touchfile.txt every 10 sec with stat and show "hello" on a change
- onfilechange.sh -f /home/me/touchfile.txt -s -w 10 -c "echo hello"
- watch touchfile.txt every 10 sec with stat and show "hello" on a change
```
-# Test on command line
+## Test on command line
To make a test on commandline touch a testfile `touch /tmp/mytestfile`.
The start the script with enabled debugging (-d) in a 2nd terminal:
-`/usr/local/bin/onfilechange.sh -v -f "/tmp/mytestfile" -c 'echo "hello"'`
+`/usr/local/bin/onfilechange.sh -c 'echo Changes!'`"/tmp/mytestfile"
+
+```
+______________________________________________________________________________
+
+ T R I G G E R C O M M A N D O N A F I L E C H A N G E
+_______________________________________________________________________| v1.06
+
+
+--- summary
+checking file(s): /tmp/mytestfile
+with command [stat]
+with a sleep time of [5] seconds
+on change execute command [echo Changes!]
+
+...............................................................................
+
+
+
+>>>>> watched files
+ls: cannot access '/tmp/mytestfile': No such file or directory
+INFO: file '/tmp/mytestfile' (or one of them) does not exist yet
+
+>>>>> start
+waiting for file changes ...
+```
+
+If you create the file in another terminal window `touch /tmp/mytestfile`then you get the reaction:
+
+```txt
+>>>>> start
+waiting for file changes ...
+1c1
+< stat: cannot statx '/tmp/mytestfile': No such file or directory
+---
+> regular empty file /tmp/mytestfile | perms: -rw-r--r--; user 1000 (axel) group 1000 (axel) | size: 0 byte | last modification 2025-01-17 13:39:02.543806368 +0100
+>>>>> Fri Jan 17 13:39:06 CET 2025 Executing echo Changes! ...
+```
+
+The given command will be executed and its output is visible. Then it waits again.
+
+```txt
+Changes!
+Command was successful.
+
+>>>>> waiting for the next change ...
+```
+
+## Tipps and tricks
+
+### Multiple files
+
+You cannot watch just a single file but multiple files too. Just add all of them at the and of the command line as parameters.
+
+`onfilechange.sh -c <command> <FILE_1> <FILE_2> <FILE:N>`
+
+The files are seperated by spaces. If they contain spaces or other special chars you need to quote them or mask the special characters. Both of these examples are equal:
+
+```txt
+onfilechange.sh -c <command> "directory 1" "directory 2"
+onfilechange.sh -c <command> directory\ 1 directory\ 2
+```
+
+### Run permanently
-Each time you touch the testfile in another terminal window it should show "hello".
+If the file watcher should run always ans always start after reboot, then create a service. In the chapter Service is an example for systemd.
diff --git a/docs/30_Service.md b/docs/30_Service.md
index f7be69354dcfc2b0e123e11d05d2cb37486fad16..79181f7f4436f37e8e913cde17f1807c3cfef20c 100644
--- a/docs/30_Service.md
+++ b/docs/30_Service.md
@@ -1,10 +1,11 @@
-
-# Use as systemd service
+## Use as systemd service
With running the script as a service can be helpful if you administrate servers and habe developer teams with limited access. Instead of giving sudo permissions you can watch a touchfile to execute something specific as root, i.e. restart Apache httpd. In the real world this file would be touched during an automated deploy process.
Below is just an example service watching a dummy file in /tmp directory.
+### Create the service file
+
In `/etc/systemd/system/` create a service config file **onfilechange-demo.service**
```txt
@@ -25,6 +26,13 @@ Type=simple
WantedBy=multi-user.target
```
+**Remark**:
+The example runs with root to restart a system service. Always limit the permission "User" an "Group" to that user that is needed for watching files and the command.
+
+### Test
+
Check if the service exists `systemctl status onfilechange-demo`. If so you can start and stop it with `systemctl [start|stop] onfilechange-demo`
-To start the service on reboot you additionally need to enable it: `systemctl enable onfilechange-demo`.
\ No newline at end of file
+### Startup on boot
+
+To start the service on reboot you additionally need to enable it: `systemctl enable onfilechange-demo`.
diff --git a/docs/_index.md b/docs/_index.md
index c735b0c2206a63fe12437ebffdcc28f0c8f016cd..e2589db7ace85e78e29955243fc3ac09756cc626 100644
--- a/docs/_index.md
+++ b/docs/_index.md
@@ -1,7 +1,7 @@
# onfilechange
-A Shell script that watches a given fileobject or multiple fileobjects (=files or directories).
-If one of the watched fileobject changes then a given command will be exxecuted.
+Watche a given fileobject or multiple fileobjects (=files or directories) and execute a command if it changes.
+
It loops permanently; you need to stop it by Ctrl + C and/ or can
use it as systemd watcher daemon.
@@ -26,3 +26,5 @@ application ... and on an update you want to allow him to restart the web servic
Start the onfilechange to watch a defined file as root:
`onfilechange.sh -f /var/www/touch2restart_httpd -c "systemctl restart httpd"`
+
+Or you can start a tool to process changed files in a watched directory: eg convert docs to PDF or videos.
diff --git a/onfilechange.sh b/onfilechange.sh
index 0d6f8f66263f241aaf7b82b2166c845618dea3ab..80ec501c1a4564c6b09b0228b657d03c888b69a5 100755
--- a/onfilechange.sh
+++ b/onfilechange.sh
@@ -23,20 +23,22 @@
# 2019-10-21 v1.03 <axel.hahn@iml.unibe.ch> use stat as default
# 2022-03-11 v1.04 <axel.hahn@iml.unibe.ch> shell fixes
# 2022-03-11 v1.05 <axel.hahn@iml.unibe.ch> fix: behaviur when trigger command fails; shell fixes; update docs
+# 2025-01-17 v1.06 <axel.hahn@unibe.ch> handle multiple files with spaces; long param options; update help
# ======================================================================
# ----------------------------------------------------------------------
# CONFIG
# ----------------------------------------------------------------------
-bDebug=0
-iSleep=5
+FLAG_DEBUG=0
+typeset -i iSleep=5
sCommand=
-sWatchFile=
sMode=
+aWatchFiles=()
+
# ---- below are some internal variables
-_version=1.05
+_version=1.06
# ----------------------------------------------------------------------
@@ -47,38 +49,55 @@ _version=1.05
function showHelp(){
local _self=$( basename $0 )
cat <<ENDOFHELP
+
HELP:
- This script checks the change of a given fileobjects and triggers
- a command if it changes
+
+${_self} checks the change of a given fileobjects and triggers
+a command on file changes.
+It can use stat or inotifywait to watch a file change. preferred is stat
+because it can be used for not yet existing files.
+
+SYNTAX:
+
+ ${_self} OPTIONS -c COMAND [FILE] [[... FILE N]]
PRAMETERS:
- -c [command]
- command to execute on a file change
- -f [fileobject(s)]
- filenames or directories to watch; separate multiple files with
- space and put all in quotes
- -h
- show this help
- -i
- force inotifywait command
- -s
- force stat command (default mode)
- -v
- verbose mode; enable showing debug output
- -w [integer]
- for stat mode: wait time in seconds betweeen each test or on
- missing file; default: 5 sec
-EXAMPLES:
- $_self -f /home/me/touchfile.txt -c "ls -l"
- watch touchfile.txt and make a file listing on change
+ -c|--command COMMAND
+ A command to execute on a file change
+
+ -f|--file FILENAME
+ Filenames or directories to watch; separate multiple files with
+ space and put all in quotes
+ DEPRECATED: add all files to watch as parameters
- $_self -f "/home/me/touchfile.txt home/me/touchfile2.txt" -c "ls -l"
- watch touchfile.txt and touchfile2.txt
+ -h|--help
+ show this help
- $_self -f /home/me/touchfile.txt -s -w 10 -c "echo hello"
- watch touchfile.txt every 10 sec with stat and show "hello" on a
- change
+ -i|--inotifywait
+ force inotifywait command
+
+ -s|--stat
+ force stat command (default mode)
+
+ -v
+ verbose mode; enable showing debug output; it should be the first option
+ to see handling of other options
+
+ -w|--wait SLEEPTIME
+ for stat mode: wait time in seconds betweeen each test or on
+ missing file; default: 5 sec
+
+EXAMPLES:
+
+ $_self -c "ls -l" /home/me/touchfile.txt
+ watch touchfile.txt and make a file listing on change
+
+ $_self -c "ls -l" "/home/me/touchfile.txt" "home/me/touchfile2.txt"
+ watch touchfile.txt and touchfile2.txt
+
+ $_self -s -w 10 -c "echo hello" /home/me/touchfile.txt
+ watch touchfile.txt every 10 sec with stat and show "hello" on a change
ENDOFHELP
@@ -86,28 +105,28 @@ ENDOFHELP
# write debug output ... if debug is enabled only
#
-# global (bool) $bDebug
+# global (bool) $FLAG_DEBUG
# param string text message to show
function wd(){
- if [ $bDebug -ne 0 ]; then
- echo "[$(date)] DEBUG |" $*
+ if [ $FLAG_DEBUG -ne 0 ]; then
+ echo "$*" | while read -r l; do echo "[$(date)] DEBUG | ${l}"; done
fi
}
# list watched files
#
-# global (string) filename(s) to watch
+# global (string) filesAsString list of all files to watch
function listFiles(){
echo
echo ">>>>> watched files"
- ls -ld ${sWatchFile} 2>&1
+ eval "ls -ld $filesAsString"
}
# for stat: helper to get current file status
#
-# global (string) $sWatchFile
+# global (array) $aWatchFiles array of watched files
function getFilestatus(){
- for myfile in ${sWatchFile}
+ for myfile in "${aWatchFiles[@]}"
do
stat -c "%F %n | perms: %A; user %u (%U) group %g (%G) | size: %s byte | last modification %y" "${myfile}" 2>&1
done
@@ -129,9 +148,9 @@ function initFilestatus(){
# global (string) $sTmpFile2 current file status
# global (string) $sCommand command to execute
function compareFilestatus(){
- getFilestatus >${sTmpFile2}
- wd "$(cat ${sTmpFile2})"
- if diff ${sTmpFile} ${sTmpFile2}; then
+ getFilestatus >"${sTmpFile2}"
+ wd "$(cat "${sTmpFile2}")"
+ if diff "${sTmpFile}" "${sTmpFile2}"; then
wd "No Change"
else
wd "Change detected."
@@ -141,7 +160,7 @@ function compareFilestatus(){
echo rc=$? FAILED.
fi
wd "Re-Init File status"
- mv ${sTmpFile2} ${sTmpFile}
+ mv "${sTmpFile2}" "${sTmpFile}"
echo
echo ">>>>> waiting for the next change ..."
fi
@@ -168,15 +187,12 @@ _______________________________________________________________________| v${_ver
ENDOFHEAD
if which stat >/dev/null 2>&1; then
- echo "INFO: stat command detected"
sMode=stat
else
- echo ERROR: the command stat was not found on your system.
if ! which inotifywait >/dev/null 2>&1; then
echo ERROR: the command inotifywait was not found on your system.
exit 2
fi
- echo "INFO: enabling inotifywait command"
sMode=inotifywait
fi
@@ -184,52 +200,29 @@ if [ $# -eq 0 ]; then
showHelp
exit 0
fi
-
-while getopts ":c: :v :f: :h :i :s :w:" opt
-do
- case $opt in
- h)
- showHelp
- exit 0
- ;;
- v)
- bDebug=1
- wd "debug is now ${bDebug}"
- ;;
- c)
- sCommand=$OPTARG
- wd "command is now ${sCommand}"
- ;;
- f)
- sWatchFile=$OPTARG
- wd "watch file is now ${sWatchFile}"
- ;;
- i)
- sMode=inotifywait
- wd "forcing mode with inotifywait command"
- ;;
- s)
- sMode=stat
- wd "forcing mode with stat command"
- ;;
- w)
- typeset -i iSleep=$OPTARG
- wd "sleep $iSleep sec"
- ;;
- :)
- echo "ERROR: Option -$opt requires an argument." >&2
- showHelp
- exit 1
- esac
-done
+while [[ "$#" -gt 0 ]]; do case $1 in
+ -h|--help) showHelp; exit 0;;
+ -c|--command) sCommand="$2"; wd "command is now ${sCommand}"; shift; shift;;
+ -f|--file) aWatchFiles+=("$2"); echo "DEPPRECATED: Add all files as parameter instead of using -f option."; wd "watch file $2 was added" ;shift;shift;;
+ -i|--inotifywait) sMode=inotifywait; wd "forcing mode with inotifywait command"; shift;;
+ -s|--stat) sMode=stat; wd "forcing mode with inotifywait command"; shift;;
+ -w|--wait) iSleep=$OPTARG; wd "sleep $iSleep sec"; shift;shift;;
+ -v|--verbose) FLAG_DEBUG=1; shift;;
+ *) if grep "^-" <<< "$1" >/dev/null ; then
+ echo; echo "ERROR: Unknown parameter: $1"; echo; _showHelp; exit 2
+ fi
+ # break;
+ aWatchFiles+=("$1"); wd "watch file $1 was added" ;shift;;
+
+esac; done
cat <<ENDOFINFO
--- summary
-checking file [${sWatchFile}]
+checking file(s): ${aWatchFiles[@]}
with command [${sMode}]
with a sleep time of [${iSleep}] seconds
-and on change I start the command [${sCommand}]
+on change execute command [${sCommand}]
...............................................................................
@@ -240,19 +233,23 @@ ENDOFINFO
# CHECKS
# ----------------------------------------------------------------------
+filesAsString=
+for myfile in "${aWatchFiles[@]}"
+do
+ filesAsString+="'${myfile}' "
+done
+
wd "--- checks"
-if [ -z "${sWatchFile}" ]; then
- echo ERROR: set a check file with param -f
+if [ -z "${filesAsString}" ]; then
+ echo "ERROR: Add one or more files / directories to watch as parameter"
exit 1
fi
if ! listFiles; then
- echo "INFO: file ${sWatchFile} (or one of them) does not exist yet"
- # echo "ERROR: file ${sWatchFile} (or one of them) does not exist yet"
- # exit 1
+ echo "INFO: file ${filesAsString} (or one of them) does not exist yet"
fi
if [ -z "${sCommand}" ]; then
- echo ERROR: set a ${sCommand} with param -s
+ echo ERROR: set a command with option -c first.
exit 1
fi
echo
@@ -262,7 +259,7 @@ echo
# ----------------------------------------------------------------------
echo ">>>>> start"
-myset=$(echo "${sWatchFile}" | sha1sum | cut -f 1 -d " ")
+myset=$(echo "${aWatchFiles[*]}" | sha1sum | cut -f 1 -d " ")
sTmpFile="/tmp/$(basename $0)-${myset}-last.tmp"
sTmpFile2="/tmp/$(basename $0)-${myset}-current.tmp"
@@ -270,7 +267,7 @@ case $sMode in
"inotifywait")
while true; do
if listFiles >/dev/null 2>&1; then
- inotifywait -e attrib -e modify "${sWatchFile}" && execCommand
+ eval inotifywait -e attrib -e modify "${filesAsString}" && execCommand || exit 1
else
echo "ERROR: inotifywait only can notify if all watched files exist."
echo "Use parameter -s to use stat for file detection, This mode also allows that a file is deleted."