fsmonitor: add documentation for allowRemote and socketDir options
Add documentation for 'fsmonitor.allowRemote' and 'fsmonitor.socketDir'. Call-out experimental nature of 'fsmonitor.allowRemote' and limited filesystem support for 'fsmonitor.socketDir'. Signed-off-by: Eric DeCosta <edecosta@mathworks.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Eric DeCosta committed
Oct 4, 2022 at 17:32 UTC
5aa9e3262e6ac99c1c06d7f0e0619b1ea94a9881
3 files changed
+47
-3
Documentation/config.txt
+2
@@ -423,6 +423,8 @@ include::config/filter.txt[]
423
424
include::config/fsck.txt[]
425
426
+include::config/fsmonitor--daemon.txt[]
427
+
428
include::config/gc.txt[]
429
430
include::config/gitcvs.txt[]
Documentation/config/fsmonitor--daemon.txt
new
+11
@@ -0,0 +1,11 @@
1
+fsmonitor.allowRemote::
2
+ By default, the fsmonitor daemon refuses to work against network-mounted
3
+ repositories. Setting `fsmonitor.allowRemote` to `true` overrides this
4
+ behavior. Only respected when `core.fsmonitor` is set to `true`.
5
+
6
+fsmonitor.socketDir::
7
+ This Mac OS-specific option, if set, specifies the directory in
8
+ which to create the Unix domain socket used for communication
9
+ between the fsmonitor daemon and various Git commands. The directory must
10
+ reside on a native Mac OS filesystem. Only respected when `core.fsmonitor`
11
+ is set to `true`.
Documentation/git-fsmonitor--daemon.txt
+34
-3
@@ -3,7 +3,7 @@ git-fsmonitor{litdd}daemon(1)
3
4
NAME
5
----
6
-git-fsmonitor--daemon - A Built-in File System Monitor
6
+git-fsmonitor--daemon - A Built-in Filesystem Monitor
7
8
SYNOPSIS
9
--------
@@ -17,7 +17,7 @@ DESCRIPTION
17
-----------
18
19
A daemon to watch the working directory for file and directory
20
-changes using platform-specific file system notification facilities.
20
+changes using platform-specific filesystem notification facilities.
21
22
This daemon communicates directly with commands like `git status`
23
using the link:technical/api-simple-ipc.html[simple IPC] interface
@@ -63,13 +63,44 @@ CAVEATS
63
-------
64
65
The fsmonitor daemon does not currently know about submodules and does
66
-not know to filter out file system events that happen within a
66
+not know to filter out filesystem events that happen within a
67
submodule. If fsmonitor daemon is watching a super repo and a file is
68
modified within the working directory of a submodule, it will report
69
the change (as happening against the super repo). However, the client
70
will properly ignore these extra events, so performance may be affected
71
but it will not cause an incorrect result.
72
73
+By default, the fsmonitor daemon refuses to work against network-mounted
74
+repositories; this may be overridden by setting `fsmonitor.allowRemote` to
75
+`true`. Note, however, that the fsmonitor daemon is not guaranteed to work
76
+correctly with all network-mounted repositories and such use is considered
77
+experimental.
78
+
79
+On Mac OS, the inter-process communication (IPC) between various Git
80
+commands and the fsmonitor daemon is done via a Unix domain socket (UDS) -- a
81
+special type of file -- which is supported by native Mac OS filesystems,
82
+but not on network-mounted filesystems, NTFS, or FAT32. Other filesystems
83
+may or may not have the needed support; the fsmonitor daemon is not guaranteed
84
+to work with these filesystems and such use is considered experimental.
85
+
86
+By default, the socket is created in the `.git` directory, however, if the
87
+`.git` directory is on a network-mounted filesystem, it will be instead be
88
+created at `$HOME/.git-fsmonitor-*` unless `$HOME` itself is on a
89
+network-mounted filesystem in which case you must set the configuration
90
+variable `fsmonitor.socketDir` to the path of a directory on a Mac OS native
91
+filesystem in which to create the socket file.
92
+
93
+If none of the above directories (`.git`, `$HOME`, or `fsmonitor.socketDir`)
94
+is on a native Mac OS file filesystem the fsmonitor daemon will report an
95
+error that will cause the daemon and the currently running command to exit.
96
+
97
+CONFIGURATION
98
+-------------
99
+
100
+include::includes/cmd-config-section-all.txt[]
101
+
102
+include::config/fsmonitor--daemon.txt[]
103
+
104
GIT
105
---
106
Part of the linkgit:git[1] suite