Document HOME environment variable
PATCH 1/1 Document HOME environment variable
From: Alejandro Barreto <[email protected]>
Git documentation refers to $HOME and $XDG_CONFIG_HOME often, but does not specify how or where these values come from on Windows where neither is set by default. The new documentation reflects the behavior of setup_windows_environment() in compat/mingw.c.
---
Document how $HOME is set on Windows
CC: Alejandro Barreto [email protected], Johannes Schindelin [email protected]
Fixes https://github.com/git-for-windows/git/issues/5282
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1834%2Fhickford%2Fhome-docs-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1834/hickford/home-docs-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1834
Documentation/git.txt | 8 ++++++++ 1 file changed, 8 insertions(+)
Documentation/git.txt +8 -0
@@ -477,6 +477,14 @@ their values the same way as Boolean valued configuration variables, e.g. Here are the variables: +System +~~~~~~~~~~~~~~~~~~ +`HOME`:: + Specifies the path to the user's home directory. On Windows, if + unset, Git will set a process environment variable equal to: + `$HOMEDRIVE$HOMEPATH` if both `$HOMEDRIVE` and `$HOMEPATH` exist; + otherwise `$USERPROFILE` if `$USERPROFILE` exists. + The Git Repository ~~~~~~~~~~~~~~~~~~ These environment variables apply to 'all' core Git commands. Nb: it
base-commit: cc01bad4a9f566cf4453c7edd6b433851b0835e2
Signature · 1 line
gitgitgadget
Quoted 6 lines · M Hickford via GitGitGadget
From: Alejandro Barreto <[email protected]>
Git documentation refers to $HOME and $XDG_CONFIG_HOME often, but does not specify how or where these values come from on Windows where neither is set by default. The new documentation reflects the behavior of
setup_windows_environment()incompat/mingw.c.
Makes sense. As long as the logic to make this fallback is in my tree (as opposed to being implemented by a set of GfW/minGit add-on patches), its documentation should also be in my tree.
Will queue.
Documentation/git.txt their values the same way as Boolean valued configuration variables, e.g. · line 486
Quoted 7 lines
Documentation/git.txt +7
-0+System +~~~~~~~~~~~~~~~~~~ +`HOME`:: + Specifies the path to the user's home directory. On Windows, if + unset, Git will set a process environment variable equal to: + `$HOMEDRIVE$HOMEPATH` if both `$HOMEDRIVE` and `$HOMEPATH` exist; + otherwise `$USERPROFILE` if `$USERPROFILE` exists.
I wondered what the reaction by the readers on non-Windows would be, but hopefully they would read this to mean that HOME will not be mucked with, even if they leave it unset (or they take it granted that HOME is set somewhere while they log in and they do not have to worry about it), so it may be OK.
Just out of curiousity, is Git the only thing that uses $HOME on Windows? Or among may other programs on Windows that use $HOME, is the way Git gives a fall-back value out of these three variables unusual and deserves documentation?
Thanks.
Am 10.12.24 um 00:47 schrieb Junio C Hamano:
Quoted 10 lines
Documentation/git.txt their values the same way as Boolean valued configuration variables, e.g. · line 486
Quoted 8 lines · M Hickford via GitGitGadget
From: Alejandro Barreto <[email protected]>
Documentation/git.txt +7
-0+System +~~~~~~~~~~~~~~~~~~ +`HOME`:: + Specifies the path to the user's home directory. On Windows, if + unset, Git will set a process environment variable equal to: + `$HOMEDRIVE$HOMEPATH` if both `$HOMEDRIVE` and `$HOMEPATH` exist; + otherwise `$USERPROFILE` if `$USERPROFILE` exists.
Makes sense and matches the implementation in compat/mingw.c. GfW uses the same method with with additional checks for existence of the $HOMEDRIVE$HOMEPATH combination.
Quoted 5 lines
I wondered what the reaction by the readers on non-Windows would be, but hopefully they would read this to mean that HOME will not be mucked with, even if they leave it unset (or they take it granted that HOME is set somewhere while they log in and they do not have to worry about it), so it may be OK.
Since all Windows specific text is in a single sentence, I think it is difficult to misread. I would leave away the colon, though.
Quoted 4 lines
Just out of curiousity, is Git the only thing that uses $HOME on Windows? Or among may other programs on Windows that use $HOME, is the way Git gives a fall-back value out of these three variables unusual and deserves documentation?
No Windows native program uses $HOME. Only POSIX-derived tools would consider doing so. So, I would answer your question: yes, Git is the "only" one insisting in HOME being set. We are free to choose how we set it, and the way we do it makes the most sense for Git's purpose. It is certainly useful to document how we do it.
-- Hannes
Quoted 10 lines · Johannes Sixt
Quoted 4 lines
Just out of curiousity, is Git the only thing that uses $HOME on Windows? Or among may other programs on Windows that use $HOME, is the way Git gives a fall-back value out of these three variables unusual and deserves documentation?
No Windows native program uses $HOME. Only POSIX-derived tools would consider doing so. So, I would answer your question: yes, Git is the "only" one insisting in HOME being set. We are free to choose how we set it, and the way we do it makes the most sense for Git's purpose. It is certainly useful to document how we do it.
That's perfect. I've marked the topic for 'next' already.
Thanks, all.