diff --git a/README.md b/README.md index bf334c1..69e9e69 100644 --- a/README.md +++ b/README.md @@ -64,6 +64,24 @@ docker run -d \ nginx ``` +### Volumes + +The `--root` flag must indicate either a directory that either a) does not +exist (it will be created); or b) exists and is empty; or c) can be emptied by +removing all of the contents. + +Why? Git demands to clone into an empty directory. If the directory exists +and is not empty, git-sync will try to empty it by removing everything in it +(we can't just `rm -rf` the dir because it might be a mounted volume). If that +fails, git-sync will abort. + +With the above example or with a Kubernetes `emptyDir`, there is usually no +problem. The problematic case is when the volume is the root of a filesystem, +which sometimes contains metadata (e.g. ext{2,3,4} have a `lost+found` dir). +Git will not clone into such a directory (`fatal: destination path +'/tmp/git-data' already exists and is not an empty directory`). The only real +solution is to use a sub-directory of the volume as the `--root`. + ## Manual ``` diff --git a/cmd/git-sync/main.go b/cmd/git-sync/main.go index f70867c..0ee35bc 100644 --- a/cmd/git-sync/main.go +++ b/cmd/git-sync/main.go @@ -1841,7 +1841,10 @@ OPTIONS --root , $GIT_SYNC_ROOT The root directory for git-sync operations, under which --link will - be created. This flag is required. + be created. This must be a path that either a) does not exist (it + will be created); b) is an empty directory; or c) is a directory + which can be emptied by removing all of the contents. This flag is + required. --sparse-checkout-file, $GIT_SYNC_SPARSE_CHECKOUT_FILE The path to a git sparse-checkout file (see git documentation for