mirror of https://github.com/git/git.git
fsmonitor: document builtin fsmonitor
Document how `core.fsmonitor` can be set to a boolean to enable or disable the builtin FSMonitor. Update references to `core.fsmonitor` and `core.fsmonitorHookVersion` and pointers to `Watchman` to refer to it. Create `git-fsmonitor--daemon` manual page and describe its features. Signed-off-by: Jeff Hostetler <jeffhost@microsoft.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Jeff Hostetler
Junio C Hamano
parent
9c307e8afd
commit
3248486920
|
|
@ -62,22 +62,54 @@ core.protectNTFS::
|
|||
Defaults to `true` on Windows, and `false` elsewhere.
|
||||
|
||||
core.fsmonitor::
|
||||
If set, the value of this variable is used as a command which
|
||||
will identify all files that may have changed since the
|
||||
requested date/time. This information is used to speed up git by
|
||||
avoiding unnecessary processing of files that have not changed.
|
||||
See the "fsmonitor-watchman" section of linkgit:githooks[5].
|
||||
If set to true, enable the built-in file system monitor
|
||||
daemon for this working directory (linkgit:git-fsmonitor--daemon[1]).
|
||||
+
|
||||
Like hook-based file system monitors, the built-in file system monitor
|
||||
can speed up Git commands that need to refresh the Git index
|
||||
(e.g. `git status`) in a working directory with many files. The
|
||||
built-in monitor eliminates the need to install and maintain an
|
||||
external third-party tool.
|
||||
+
|
||||
The built-in file system monitor is currently available only on a
|
||||
limited set of supported platforms. Currently, this includes Windows
|
||||
and MacOS.
|
||||
+
|
||||
Otherwise, this variable contains the pathname of the "fsmonitor"
|
||||
hook command.
|
||||
+
|
||||
This hook command is used to identify all files that may have changed
|
||||
since the requested date/time. This information is used to speed up
|
||||
git by avoiding unnecessary scanning of files that have not changed.
|
||||
+
|
||||
See the "fsmonitor-watchman" section of linkgit:githooks[5].
|
||||
+
|
||||
Note that if you concurrently use multiple versions of Git, such
|
||||
as one version on the command line and another version in an IDE
|
||||
tool, that the definition of `core.fsmonitor` was extended to
|
||||
allow boolean values in addition to hook pathnames. Git versions
|
||||
2.35.1 and prior will not understand the boolean values and will
|
||||
consider the "true" or "false" values as hook pathnames to be
|
||||
invoked. Git versions 2.26 thru 2.35.1 default to hook protocol
|
||||
V2 and will fall back to no fsmonitor (full scan). Git versions
|
||||
prior to 2.26 default to hook protocol V1 and will silently
|
||||
assume there were no changes to report (no scan), so status
|
||||
commands may report incomplete results. For this reason, it is
|
||||
best to upgrade all of your Git versions before using the built-in
|
||||
file system monitor.
|
||||
|
||||
core.fsmonitorHookVersion::
|
||||
Sets the version of hook that is to be used when calling fsmonitor.
|
||||
There are currently versions 1 and 2. When this is not set,
|
||||
version 2 will be tried first and if it fails then version 1
|
||||
will be tried. Version 1 uses a timestamp as input to determine
|
||||
which files have changes since that time but some monitors
|
||||
like watchman have race conditions when used with a timestamp.
|
||||
Version 2 uses an opaque string so that the monitor can return
|
||||
something that can be used to determine what files have changed
|
||||
without race conditions.
|
||||
Sets the protocol version to be used when invoking the
|
||||
"fsmonitor" hook.
|
||||
+
|
||||
There are currently versions 1 and 2. When this is not set,
|
||||
version 2 will be tried first and if it fails then version 1
|
||||
will be tried. Version 1 uses a timestamp as input to determine
|
||||
which files have changes since that time but some monitors
|
||||
like Watchman have race conditions when used with a timestamp.
|
||||
Version 2 uses an opaque string so that the monitor can return
|
||||
something that can be used to determine what files have changed
|
||||
without race conditions.
|
||||
|
||||
core.trustctime::
|
||||
If false, the ctime differences between the index and the
|
||||
|
|
|
|||
|
|
@ -0,0 +1,75 @@
|
|||
git-fsmonitor--daemon(1)
|
||||
========================
|
||||
|
||||
NAME
|
||||
----
|
||||
git-fsmonitor--daemon - A Built-in File System Monitor
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
[verse]
|
||||
'git fsmonitor--daemon' start
|
||||
'git fsmonitor--daemon' run
|
||||
'git fsmonitor--daemon' stop
|
||||
'git fsmonitor--daemon' status
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
|
||||
A daemon to watch the working directory for file and directory
|
||||
changes using platform-specific file system notification facilities.
|
||||
|
||||
This daemon communicates directly with commands like `git status`
|
||||
using the link:technical/api-simple-ipc.html[simple IPC] interface
|
||||
instead of the slower linkgit:githooks[5] interface.
|
||||
|
||||
This daemon is built into Git so that no third-party tools are
|
||||
required.
|
||||
|
||||
OPTIONS
|
||||
-------
|
||||
|
||||
start::
|
||||
Starts a daemon in the background.
|
||||
|
||||
run::
|
||||
Runs a daemon in the foreground.
|
||||
|
||||
stop::
|
||||
Stops the daemon running in the current working
|
||||
directory, if present.
|
||||
|
||||
status::
|
||||
Exits with zero status if a daemon is watching the
|
||||
current working directory.
|
||||
|
||||
REMARKS
|
||||
-------
|
||||
|
||||
This daemon is a long running process used to watch a single working
|
||||
directory and maintain a list of the recently changed files and
|
||||
directories. Performance of commands such as `git status` can be
|
||||
increased if they just ask for a summary of changes to the working
|
||||
directory and can avoid scanning the disk.
|
||||
|
||||
When `core.fsmonitor` is set to `true` (see linkgit:git-config[1])
|
||||
commands, such as `git status`, will ask the daemon for changes and
|
||||
automatically start it (if necessary).
|
||||
|
||||
For more information see the "File System Monitor" section in
|
||||
linkgit:git-update-index[1].
|
||||
|
||||
CAVEATS
|
||||
-------
|
||||
|
||||
The fsmonitor daemon does not currently know about submodules and does
|
||||
not know to filter out file system events that happen within a
|
||||
submodule. If fsmonitor daemon is watching a super repo and a file is
|
||||
modified within the working directory of a submodule, it will report
|
||||
the change (as happening against the super repo). However, the client
|
||||
will properly ignore these extra events, so performance may be affected
|
||||
but it will not cause an incorrect result.
|
||||
|
||||
GIT
|
||||
---
|
||||
Part of the linkgit:git[1] suite
|
||||
|
|
@ -498,7 +498,9 @@ FILE SYSTEM MONITOR
|
|||
This feature is intended to speed up git operations for repos that have
|
||||
large working directories.
|
||||
|
||||
It enables git to work together with a file system monitor (see the
|
||||
It enables git to work together with a file system monitor (see
|
||||
linkgit:git-fsmonitor--daemon[1]
|
||||
and the
|
||||
"fsmonitor-watchman" section of linkgit:githooks[5]) that can
|
||||
inform it as to what files have been modified. This enables git to avoid
|
||||
having to lstat() every file to find modified files.
|
||||
|
|
@ -509,8 +511,8 @@ looking for new files.
|
|||
|
||||
If you want to enable (or disable) this feature, it is easier to use
|
||||
the `core.fsmonitor` configuration variable (see
|
||||
linkgit:git-config[1]) than using the `--fsmonitor` option to
|
||||
`git update-index` in each repository, especially if you want to do so
|
||||
linkgit:git-config[1]) than using the `--fsmonitor` option to `git
|
||||
update-index` in each repository, especially if you want to do so
|
||||
across all repositories you use, because you can set the configuration
|
||||
variable in your `$HOME/.gitconfig` just once and have it affect all
|
||||
repositories you touch.
|
||||
|
|
|
|||
Loading…
Reference in New Issue