os/exec: document subtleties around Cmd.Dir, PWD, os.Getwd and C's getcwd

[adonovan]

The interaction of exec.Cmd and os.Getwd is rather subtle: the working directory of a POSIX process is represented by a file descriptor, not a string, so C's getcwd will always return a real (symlink-free) path. By contrast, Go's os.Getwd will return the value of $PWD if it is an alias for the real path. (It does not do this for ancestors or other directories: it won't return $PWD/foo if that is an alias for getcwd, for example.) exec.Cmd sets the PWD variable implicitly in order to make os.Getwd, and similar functions such as GNU C's get_current_dir_name, work this way--but it only does so in certain circumstances.

We should document the subtleties of this issue so that users of os/exec and os.Getwd don't get confused (as I did in https://github.com/golang/go/issues/67757).

[gabyhelp]

Similar Issues

• os/exec: improved API and default behavior for the PWD env variable #50599
• exec.Cmd.Dir does not set working directory properly for symlinks #17198
• docs for os.Getwd() misleading #7811

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[gopherbot]

Change https://go.dev/cl/609395 mentions this issue: os/exec: document interaction of Dir, PWD, os.Getwd and C