add a comment about CWD

While git ls-files can actually be used on a repo that is not in the
cwd, it works inconsistently. For example, this fails:

git --git-dir=../foo/.git --work-tree=../foo ls-files ../foo

But change some of the paths to absolute and it will succeed. That seems
like a bug in git.

OTOH, this succeeds:

git --git-dir=../foo/.git --work-tree=../foo ls-files

But, that lists paths relative to the top of the --work-tree,
rather than the usual listing them relative to the cwd. Because the cwd
is not in the repo. And so anything parsing the ls-files output of that
is likely to operate on files in the wrong location. Indeed, there is
code in Upgrade/ that has this problem!

CHANGELOG

@@ -18,6 +18,8 @@ git-annex (8.20200227) UNRELEASED; urgency=medium
   * git-annex config: Only allow configs be set that are ones git-annex actually
     supports reading from repo-global config, to avoid confusion.
   * Linux standalone: Use md5sum to shorten paths in .cache/git-annex/locales
+  * Fix a problem in auto-upgrade of a clone to v8 that caused a
+    message "fatal: <path> is outside repository".
 
  -- Joey Hess <id@joeyh.name>  Thu, 27 Feb 2020 00:44:11 -0400
 

Git/LsFiles.hs

@@ -40,7 +40,13 @@ import System.Posix.Types
 import qualified Data.Map as M
 import qualified Data.ByteString.Lazy as L
 
-{- Scans for files that are checked into git's index at the specified locations. -}
+{- Lists files that are checked into git's index at the specified paths.
+ - With no paths, all files are listed.
+ -
+ - Paths are relative to the CWD. So this should only be used on the
+ - current Repo, not on clones. (Same goes for all the rest of this
+ - module!)
+ -}
 inRepo :: [RawFilePath] -> Repo -> IO ([RawFilePath], IO Bool)
 inRepo = inRepo' []