From 9e732bf1a67025e66c6d0978fc98f5965d8b22c4 Mon Sep 17 00:00:00 2001
From: Emre Sahin <github@emresult.com>
Date: Sun, 15 Dec 2024 15:01:09 +0300
Subject: [PATCH] add warnings about Git config to docs

---
 book/src/ref/xvc-file-list.md  | 17 +++++++++++++++++
 book/src/ref/xvc-file-track.md | 23 +++++++++++++++++++++++
 2 files changed, 40 insertions(+)

diff --git a/book/src/ref/xvc-file-list.md b/book/src/ref/xvc-file-list.md
index 5c00fd48..f2afed79 100644
--- 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
index 49c844b7..af9689df 100644
--- 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