@matheusbsbs / matheus-bagliano / commits / 780494b1f5

fsmonitor: add documentation for the fsmonitor extension.

This includes the core.fsmonitor setting, the fsmonitor integration hook, and the fsmonitor index extension. Also add documentation for the new fsmonitor options to ls-files and update-index. Signed-off-by: Ben Peart <benpeart@microsoft.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Ben Peart committed Sep 22, 2017 at 12:35 UTC 780494b1f5c3744860c485d1e9f1b23879f8936f

5 files changed +105 -1

Documentation/config.txt

@@ -413,6 +413,13 @@ core.protectNTFS::

413 8.3 "short" names.

414 Defaults to `true` on Windows, and `false` elsewhere.

415

416 +core.fsmonitor::

417 + If set, the value of this variable is used as a command which

418 + will identify all files that may have changed since the

419 + requested date/time. This information is used to speed up git by

420 + avoiding unnecessary processing of files that have not changed.

421 + See the "fsmonitor-watchman" section of linkgit:githooks[5].

422 +

423 core.trustctime::

424 If false, the ctime differences between the index and the

425 working tree are ignored; useful when the inode change time

Documentation/git-ls-files.txt

+6 -1

@@ -9,7 +9,7 @@ git-ls-files - Show information about files in the index and the working tree

9 SYNOPSIS

10 --------

11 [verse]

12 -'git ls-files' [-z] [-t] [-v]

12 +'git ls-files' [-z] [-t] [-v] [-f]

14 (-[c|d|o|i|s|u|k|m])*

15 [--eol]

@@ -133,6 +133,11 @@ a space) at the start of each line:

133 that are marked as 'assume unchanged' (see

134 linkgit:git-update-index[1]).

135

136 +-f::

137 + Similar to `-t`, but use lowercase letters for files

138 + that are marked as 'fsmonitor valid' (see

139 + linkgit:git-update-index[1]).

140 +

141 --full-name::

142 When run from a subdirectory, the command usually

143 outputs paths relative to the current directory. This

Documentation/git-update-index.txt

+45

@@ -16,9 +16,11 @@ SYNOPSIS

16 [--chmod=(+|-)x]

17 [--[no-]assume-unchanged]

18 [--[no-]skip-worktree]

19 + [--[no-]fsmonitor-valid]

20 [--ignore-submodules]

21 [--[no-]split-index]

22 [--[no-|test-|force-]untracked-cache]

23 + [--[no-]fsmonitor]

24 [--really-refresh] [--unresolve] [--again | -g]

25 [--info-only] [--index-info]

26 [-z] [--stdin] [--index-version <n>]

@@ -111,6 +113,12 @@ you will need to handle the situation manually.

113 set and unset the "skip-worktree" bit for the paths. See

114 section "Skip-worktree bit" below for more information.

115

116 +--[no-]fsmonitor-valid::

117 + When one of these flags is specified, the object name recorded

118 + for the paths are not updated. Instead, these options

119 + set and unset the "fsmonitor valid" bit for the paths. See

120 + section "File System Monitor" below for more information.

121 +

122 -g::

123 --again::

124 Runs 'git update-index' itself on the paths whose index

@@ -201,6 +209,15 @@ will remove the intended effect of the option.

209 `--untracked-cache` used to imply `--test-untracked-cache` but

210 this option would enable the extension unconditionally.

211

212 +--fsmonitor::

213 +--no-fsmonitor::

214 + Enable or disable files system monitor feature. These options

215 + take effect whatever the value of the `core.fsmonitor`

216 + configuration variable (see linkgit:git-config[1]). But a warning

217 + is emitted when the change goes against the configured value, as

218 + the configured value will take effect next time the index is

219 + read and this will remove the intended effect of the option.

220 +

221 \--::

222 Do not interpret any more arguments as options.

223

@@ -447,6 +464,34 @@ command reads the index; while when `--[no-|force-]untracked-cache`

464 are used, the untracked cache is immediately added to or removed from

465 the index.

466

467 +File System Monitor

468 +-------------------

469 +

470 +This feature is intended to speed up git operations for repos that have

471 +large working directories.

472 +

473 +It enables git to work together with a file system monitor (see the

474 +"fsmonitor-watchman" section of linkgit:githooks[5]) that can

475 +inform it as to what files have been modified. This enables git to avoid

476 +having to lstat() every file to find modified files.

477 +

478 +When used in conjunction with the untracked cache, it can further improve

479 +performance by avoiding the cost of scanning the entire working directory

480 +looking for new files.

481 +

482 +If you want to enable (or disable) this feature, it is easier to use

483 +the `core.fsmonitor` configuration variable (see

484 +linkgit:git-config[1]) than using the `--fsmonitor` option to

485 +`git update-index` in each repository, especially if you want to do so

486 +across all repositories you use, because you can set the configuration

487 +variable to `true` (or `false`) in your `$HOME/.gitconfig` just once

488 +and have it affect all repositories you touch.

489 +

490 +When the `core.fsmonitor` configuration variable is changed, the

491 +file system monitor is added to or removed from the index the next time

492 +a command reads the index. When `--[no-]fsmonitor` are used, the file

493 +system monitor is immediately added to or removed from the index.

494 +

495 Configuration

496 -------------

497

Documentation/githooks.txt

+28

@@ -455,6 +455,34 @@ the name of the file that holds the e-mail to be sent. Exiting with a

455 non-zero status causes 'git send-email' to abort before sending any

456 e-mails.

457

458 +fsmonitor-watchman

459 +~~~~~~~~~~~~~~~~~~

460 +

461 +This hook is invoked when the configuration option core.fsmonitor is

462 +set to .git/hooks/fsmonitor-watchman. It takes two arguments, a version

463 +(currently 1) and the time in elapsed nanoseconds since midnight,

464 +January 1, 1970.

465 +

466 +The hook should output to stdout the list of all files in the working

467 +directory that may have changed since the requested time. The logic

468 +should be inclusive so that it does not miss any potential changes.

469 +The paths should be relative to the root of the working directory

470 +and be separated by a single NUL.

471 +

472 +It is OK to include files which have not actually changed. All changes

473 +including newly-created and deleted files should be included. When

474 +files are renamed, both the old and the new name should be included.

475 +

476 +Git will limit what files it checks for changes as well as which

477 +directories are checked for untracked files based on the path names

478 +given.

479 +

480 +An optimized way to tell git "all files have changed" is to return

481 +the filename '/'.

482 +

483 +The exit status determines whether git will use the data from the

484 +hook to limit its search. On error, it will fall back to verifying

485 +all files and folders.

486

487 GIT

488 ---

Documentation/technical/index-format.txt

+19

@@ -295,3 +295,22 @@ The remaining data of each directory block is grouped by type:

295 in the previous ewah bitmap.

296

297 - One NUL.

298 +

299 +== File System Monitor cache

300 +

301 + The file system monitor cache tracks files for which the core.fsmonitor

302 + hook has told us about changes. The signature for this extension is

303 + { 'F', 'S', 'M', 'N' }.

304 +

305 + The extension starts with

306 +

307 + - 32-bit version number: the current supported version is 1.

308 +

309 + - 64-bit time: the extension data reflects all changes through the given

310 + time which is stored as the nanoseconds elapsed since midnight,

311 + January 1, 1970.

312 +

313 + - 32-bit bitmap size: the size of the CE_FSMONITOR_VALID bitmap.

314 +

315 + - An ewah bitmap, the n-th bit indicates whether the n-th index entry

316 + is not CE_FSMONITOR_VALID.