runtime(doc): add some docs for file-watcher programs

fixes: #15733

Signed-off-by: Christian Brabandt <cb@256bit.org>

diff --git a/runtime/doc/editing.txt b/runtime/doc/editing.txt
index 6f004bb2549e8f073236c450334676a884e84c1b..a70515d6ff2f90e4c98dc72b32a303fe51e63194 100644 (file)
--- a/runtime/doc/editing.txt
+++ b/runtime/doc/editing.txt
@@ -1,4 +1,4 @@
-*editing.txt*   For Vim version 9.1.  Last change: 2024 Oct 13
+*editing.txt*   For Vim version 9.1.  Last change: 2024 Oct 14
 
 
                  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -1058,6 +1058,15 @@ explanation of when the copy is made and when the file is renamed.
 If the creation of a backup file fails, the write is not done.  If you want
 to write anyway add a '!' to the command.
 
+                                                       *file-watcher*
+When you notice issues with programs, that act upon when a buffer is written
+(like inotify, entr or fswatch) or when external applications execute Vim to
+edit the file (like git) and those programs do not seem to notice that the
+original file has been changed, you may want to consider switching the
+'backupcopy' option value to "yes".  This makes sure, Vim writes to the same
+file, that those watcher programs expect, without creating a new file (which
+prevents them from detecting that the file has changed).  See also |crontab|
+
                                                        *write-permissions*
 When writing a new file the permissions are read-write.  For unix the mask is
 0o666 with additionally umask applied.  When writing a file that was read Vim

diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 48ca25adf746cb77a77cbe0c956824d8d1e9b65f..40dc139b0876d760f046f839451bc95196d96bc3 100644 (file)
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -1151,12 +1151,13 @@ A jump table for the options with a short description can be found at |Q_op|.
        useful for example in source trees where all the files are symbolic or
        hard links and any changes should stay in the local source tree, not
        be propagated back to the original source.
-                                                       *crontab*
+                                                               *crontab*
        One situation where "no" and "auto" will cause problems: A program
        that opens a file, invokes Vim to edit that file, and then tests if
        the open file was changed (through the file descriptor) will check the
        backup file instead of the newly created file.  "crontab -e" is an
-       example.
+       example, as are several |file-watcher| daemons like inotify.  In that
+       case you probably want to switch this option.
 
        When a copy is made, the original file is truncated and then filled
        with the new text.  This means that protection bits, owner and

diff --git a/runtime/doc/tags b/runtime/doc/tags
index c3089bb6e6da7d60f0f17de234bd245f57168cdb..78e9f2473c69c9ee966ea9bfb3518e9603d8ce24 100644 (file)
--- a/runtime/doc/tags
+++ b/runtime/doc/tags
@@ -7114,6 +7114,7 @@ file-read insert.txt      /*file-read*
 file-searching editing.txt     /*file-searching*
 file-type      filetype.txt    /*file-type*
 file-types     filetype.txt    /*file-types*
+file-watcher   editing.txt     /*file-watcher*
 file_readable()        builtin.txt     /*file_readable()*
 filecopy()     builtin.txt     /*filecopy()*
 fileencoding-changed   version6.txt    /*fileencoding-changed*