add warnings about Git config to docs

iesahin · Dec 15, 2024 · 9e732bf · 9e732bf
1 parent fbf8905
commit 9e732bf
Show file tree

Hide file tree

Showing 2 changed files with 40 additions and 0 deletions.
diff --git a/book/src/ref/xvc-file-list.md b/book/src/ref/xvc-file-list.md
@@ -174,6 +174,8 @@ Total #: 30 Workspace Size:       51195 Cached Size:           0
 
 ```
 
+## Files tracked by Git
+
 This command doesn't list Git-tracked files by default. If you want to list them, use `--include-git-files` flag.
 ```console
 $ zsh -c 'echo "#!/bin/bash" > my-git-tracked-script.sh'
@@ -196,6 +198,21 @@ Total #: 1 Workspace Size:          12 Cached Size:           0
 
 ```
 
+````admonish warning 
+Xvc detects files tracked by git with the output of `git ls-files`. In default
+configuration Git encodes **UTF-8** file names in octal format. As Xvc uses
+UTF-8 internally to keep track of paths, it cannot identify files are tracked
+by Git if they have non-ASCII characters. 
+
+Please set 
+
+```shell
+git config core.quotepath off
+```
+
+in your Xvc repository to let Git list files in UTF-8.  
+````
+
 By default the command hides dotfiles too. If you also want to show them, you can use `--show-dot-files`/`-a` flag. If you want to show dotfiles also tracked by git, you may use `--show-dot-files` and `--include-git-files` together.
 
 ```console

diff --git a/book/src/ref/xvc-file-track.md b/book/src/ref/xvc-file-track.md
@@ -102,6 +102,29 @@ You can specify more than one target in a single command.
 $ xvc file track dir-0001/file-0002.bin dir-0001/file-0003.bin
 ```
 
+## Files tracked by Git
+
+By default, Xvc doesn't track files tracked by Git. You need to specify
+`--include-git-files` options to track files tracked by git.
+
+````admonish warning 
+Xvc detects files tracked by git with the output of `git ls-files`. In default
+configuration Git encodes **UTF-8** file names in octal format. As Xvc uses
+UTF-8 internally to keep track of paths, it cannot identify files are tracked
+by Git if they have non-ASCII characters. 
+
+Please set 
+
+```shell
+git config core.quotepath off
+```
+
+in your Xvc repository to let Git list files in UTF-8.  
+````
+
+
+## Caching
+
 When you track a file, Xvc moves the file to the cache directory under `.xvc/`
 and _connects_ the workspace file with the cached file. This _connection_ is
 called rechecking and analogous to Git checkout. For example, the above