Add clang.pathMappings

Initialization-options.md

@@ -6,13 +6,33 @@ Each language client has its own way to specify initialization options. ccls sup
 
 ## `cacheDirectory`
 
-It points to a directory (relative or absolute) storing indexing files so that next time ccls can load these indexing results without full indexing.
+Default: `".ccls-cache"`
 
-If empty, cache will be stored in memory.
+If your project is `/a/b`, cache directories will be created at `/a/b/.ccls-cache/@a@b/` (files under the project root) `/a/b/.ccls-cache/@@a@b/` (files outside the project root, e.g. `/usr/include/stdio.h`).
+
+This can also be an absolute path. Because the project path is encoded with `@`, cache directories of different projects will not conflict. When ccls is started, it will try loading cache files if they are not stale (compile command line matches and timestamps of main source and its `#include` (direct and transitive) dependencies do not change).
+
+If empty, cache will be stored in memory. Every time a file is re-indexed, the cache will be written to the disk. Use this if you don't want to write cache files.
 
 ## `clang.extraArgs` `clang.excludeArgs`
 
 Additional arguments or excluded arguments for `compile_commands.json` entries.
+You may use `clang.excludeArgs` to exclude GCC specific options that are unknown to clang.
+
+## `clang.pathMappings`
+
+If cache files were built with project root `/tmp/container`, and you want to reuse them with a different project root `/host`:
+```javascript
+{ "clang": { "pathMappings": ["/container:/host"] }
+```
+
+Copy cache files:
+```zsh
+rsync -a /tmp/ccls/@tmp@container@/ /tmp/ccls/@tmp@host@/ # files under project root
+rsync -a /tmp/ccls/@@tmp@container/ /tmp/ccls/@@tmp@host/ # files outside of project root
+```
+
+Open `/tmp/host/a.cc`, the cache file `/tmp/ccls/@tmp@host/a.cc.blob` will be reused. When a.cc is saved (re-indexed), the newly generated a.cc.blob will not contain /tmp/container paths any more.
 
 ## `diagnostics.onOpen: true` `diagnostics.onChange: true` `diagnostics.onSave: false`
 
@@ -40,7 +60,7 @@ If `index.threads` is 0, use `std::thread::hardware_concurrency()`. If you want
 
 With the value larger than 0, ccls will index comments associated with functions/types/variables (macros are not handled).
 
-This feature requires UI support as multi-line hover results poses a problem to editors:
+This feature requires UI support as multi-line `textDocument/hover` results pose a problem to editors:
 
 * Emacs
   + lsp-ui-doc https://github.com/emacs-lsp/lsp-ui
@@ -69,7 +89,8 @@ You usually want to use `index.multiVersionBlacklist` to exclude system headers.
 
 ## `index.onChange`: re-index for every change
 
-It is `false` by default which means to re-index when a document is saved.
+Default: `false`, re-index when a document is saved.
+
 Set it to `true` to re-index for every change to a document.
 
 The performance may suffer a lot.
@@ -84,16 +105,13 @@ This is best used in conjunction with empty empty `cacheDirectory` to avoid writ
 
 ## `cacheFormat`: serialization format of cache files
 
-Two cache serialization formats are supported.
+Default: `"binary"`, a compact binary serialization format.
 
-```json
+Use
-"cacheFormat": "binary"
+```javascript
-"cacheFormat": "json"
+{ "cacheFormat": "json" }
 ```
-
+if you want to inspect the cache file (`IndexFile`), e.g. `jq . < /tmp/ccls/@tmp@c/a.cc.json`
-`"binary"` uses a compact binary serialization format which typically takes only 60% of the corresponding JSON size, but is difficult to inspect. It does not store map keys and you need to re-index whenever a struct member has changed.
-
-`"json"` generates `cacheDirectory/.../xxx.json` files which can be pretty printed with jq.
 
 ## `completion.filterAndSort`: completion filtering and sorting