Document path conversion on Windows (#13331)

* Document path conversion on Windows

* Minor formatting and style updates

* desktop/windows: minor fixes in troubleshoot

Co-authored-by: Usha Mandya <47779042+usha-mandya@users.noreply.github.com>

desktop/windows/troubleshoot.md

@@ -54,9 +54,10 @@ from the menu.
 4. When the diagnostics collection process is complete, click **Upload to get a Diagnostic ID**.
 5. When the diagnostics have been uploaded, Docker Desktop prints a Diagnostic ID. Copy this ID.
 6. If you have subscribed to a Pro or a Team plan, click **Contact Support**. This opens the [Docker Desktop support](https://hub.docker.com/support/desktop/){:target="_blank" rel="noopener" class="_"} form. Fill in the information required and add the ID you copied earlier to the Diagnostics ID field. Click **Submit** to request Docker Desktop support.
+
    > **Note**
-    >
-    > You must be signed in to Docker Desktop using your Pro or Team plan credentials to access the support form. For information on what's covered as part of Docker Desktop support, see [Support](#support).
+   >
+   > You must be signed in to Docker Desktop using your Pro or Team plan credentials to access the support form. For information on what's covered as part of           Docker Desktop support, see [Support](#support).
 7. If you are not subscribed to a Pro or a team plan, you can click **Upgrade to benefit from Docker Support** to upgrade your existing account.
     Alternatively, click **Report a Bug** to open a new Docker Desktop issue on GitHub. This opens Docker Desktop [for Windows](https://github.com/docker/for-win/issues/) on GitHub in your web browser in a 'New issue' template. Complete the information required and ensure you add the diagnostic ID you copied earlier. Click **submit new issue** to create a new issue.
 
@@ -179,6 +180,94 @@ For an example of this issue and the resolution, see this issue on GitHub:
 [Docker RUN fails to execute shell
 script](https://github.com/moby/moby/issues/24388).
 
+#### Path conversion on Windows
+
+On Linux, the system takes care of mounting a path to another path. For example, when you run the following command on Linux:
+
+```console
+$ docker run --rm -ti -v /home/user/work:/work alpine
+```
+
+It adds a `/work` directory to the target container to mirror the specified path.
+
+However, on Windows, you must update the source path. For example, if you are using 
+the legacy Windows shell (`cmd.exe`), you can use the following command:
+
+```console
+$ docker run --rm -ti -v C:\Users\user\work:/work alpine
+```
+
+This starts the container and ensures the volume becomes usable. This is possible because Docker Desktop detects
+the Windows-style path and provides the appropriate conversion to mount the directory.
+
+Docker Desktop also allows you to use Unix-style path to the appropriate format. For example:
+
+```console
+$ docker run --rm -ti -v /c/Users/user/work:/work alpine ls /work
+```
+
+#### Working with Git Bash
+
+Git Bash (or MSYS) provides Unix-like environment on Windows. These tools apply their own
+preprocessing on the command line. For example, if you run the following command in Git Bash, it gives an error:
+
+```console
+$ docker run --rm -ti -v C:\Users\user\work:/work alpine
+docker: Error response from daemon: mkdir C:UsersUserwork: Access is denied.
+```
+
+This is because the `\` character has a special meaning in Git Bash. If you are using Git Bash, you must neutralize it using `\\`:
+
+```console
+$ docker run --rm -ti -v C:\\Users\\user\\work:/work alpine
+```
+
+Also, in scripts, the `pwd` command is used to avoid hardcoding file system locations. Its output is a Unix-style path.
+
+```console
+$ pwd
+/c/Users/user/work
+```
+
+Combined with the `$()` syntax, the command below works on Linux, however, it fails on Git Bash.
+
+```console
+$ docker run --rm -ti -v $(pwd):/work alpine
+docker: Error response from daemon: OCI runtime create failed: invalid mount {Destination:\Program Files\Git\work Type:bind Source:/run/desktop/mnt/host/c/Users/user/work;C Options:[rbind rprivate]}: mount destination \Program Files\Git\work not absolute: unknown.
+```
+
+You can work around this issue by using an extra `/`
+
+```console
+$ docker run --rm -ti -v /$(pwd):/work alpine
+```
+
+Portability of the scripts is not affected as Linux treats multiple `/` as a single entry.
+Each occurence of paths on a single line must be neutralized.
+
+```console
+$ docker run --rm -ti -v /$(pwd):/work alpine ls /work
+ls: C:/Program Files/Git/work: No such file or directory
+```
+
+In this example, The `$(pwd)` is not converted because of the preceding '/'. However, the second '/work' is transformed by the
+POSIX layer before passing it to Docker Desktop. You can also work around this issue by using an extra `/`.
+
+```console
+$ docker run --rm -ti -v /$(pwd):/work alpine ls //work
+```
+
+To verify whether the errors are generated from your script, or from another source, you can use an environment variable. For example:
+
+```console
+$ MSYS_NO_PATHCONV=1 docker run --rm -ti -v $(pwd):/work alpine ls /work
+```
+
+It only expects the environment variable here. The value doesn't matter.
+
+In some cases, MSYS also transforms colons to semicolon. Similar conversions can also occur
+when using `~` because the POSIX layer translates it to a DOS path. `MSYS_NO_PATHCONV` also works in this case.
+
 ### Virtualization
 
 Your machine must have the following features for Docker Desktop to function correctly.

storage/bind-mounts.md

@@ -91,6 +91,7 @@ on your development host. Use the following command to bind-mount the `target/`
 directory into your container at `/app/`. Run the command from within the
 `source` directory. The `$(pwd)` sub-command expands to the current working
 directory on Linux or macOS hosts.
+If you're on Windows, see also [Path conversions on Windows](../docker-for-windows/troubleshoot.md#path-conversions-on-windows)
 
 The `--mount` and `-v` examples below produce the same result. You
 can't run them both unless you remove the `devtest` container after running the