docs(docker): add FAQ for using git worktrees (#5076)
Added a new FAQ & Troubleshooting section to the flutter_agy_docker README.
This section explains how to configure Git to use relative paths for worktrees
when working within the container to prevent broken worktree references.
Also make sure the next image has this turned on so when you type "gwta fu" you get a ".git" that is relative.
diff --git a/cloud_build/flutter_agy_docker/Dockerfile b/cloud_build/flutter_agy_docker/Dockerfile
index b6eb6cb..dfb579b 100644
--- a/cloud_build/flutter_agy_docker/Dockerfile
+++ b/cloud_build/flutter_agy_docker/Dockerfile
@@ -185,7 +185,8 @@
RUN git config --global --add safe.directory /app && \
git config --global core.editor vim && \
- git config --global pull.rebase true
+ git config --global pull.rebase true && \
+ git config --global worktree.useRelativePaths true
WORKDIR /app
ENTRYPOINT [ "/usr/bin/byobu" ]
diff --git a/cloud_build/flutter_agy_docker/README.md b/cloud_build/flutter_agy_docker/README.md
index a7bf140..35ceaa1 100644
--- a/cloud_build/flutter_agy_docker/README.md
+++ b/cloud_build/flutter_agy_docker/README.md
@@ -112,3 +112,17 @@
3. Once the SSH connection is established, open the Command Palette again.
4. Select **Dev Containers: Attach to Running Container...**
5. Choose the running container on the remote machine.
+
+## 7. FAQ & Troubleshooting
+
+### Using Git Worktrees
+
+When using Git worktrees with this container, you must configure Git to use relative paths. Failure to do so will result in broken worktree references because absolute paths differ between your host machine and the container.
+
+To configure Git to use relative paths, run the following command on your **host machine** (not inside the container) from within your Git repository:
+
+```shell
+git config --global worktree.useRelativePaths true && git worktree repair
+```
+
+After repairing, ensure you run `podman run` (or `coder-up`) from the **root of the worktree** so that the container mounts the correct paths.
