Document how $HOME is set on Windows

[hickford]

CC: Alejandro Barreto [email protected], Johannes Schindelin [email protected]

Fixes git-for-windows#5282

cc: Johannes Sixt [email protected]

[gitgitgadget]

There are issues in commit e98423c:
Document how $HOME is set on Windows
Lines in the body of the commit messages should be wrapped between 60 and 76 characters.
Indented lines, and lines without whitespace, are exempt

[dscho]

@hickford maybe you want to add your Signed-off-by line before contributing it to the Git mailing list?

[hickford]

/submit

[gitgitgadget]

Submitted as [email protected]

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-1834/hickford/home-docs-v1

To fetch this version to local tag pr-1834/hickford/home-docs-v1:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-1834/hickford/home-docs-v1

[gitgitgadget]

On the Git mailing list, Junio C Hamano wrote (reply to this):

"M Hickford via GitGitGadget" <[email protected]> writes:

> 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.

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.

> +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.

[gitgitgadget]

On the Git mailing list, Johannes Sixt wrote (reply to this):

Am 10.12.24 um 00:47 schrieb Junio C Hamano:
> "M Hickford via GitGitGadget" <[email protected]> writes:
> 
>> From: Alejandro Barreto <[email protected]>
>> +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.

> 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.

> 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

[gitgitgadget]

User Johannes Sixt <[email protected]> has been added to the cc: list.

[gitgitgadget]

On the Git mailing list, Junio C Hamano wrote (reply to this):

Johannes Sixt <[email protected]> writes:

>> 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.

[gitgitgadget]

This patch series was integrated into seen via git@f4873e4.

[gitgitgadget]

This patch series was integrated into seen via git@1b78b48.

[gitgitgadget]

This patch series was integrated into seen via git@b472f51.

[gitgitgadget]

This patch series was integrated into seen via git@f0b5923.

[gitgitgadget]

This patch series was integrated into next via git@9f49e6f.

[gitgitgadget]

This patch series was integrated into seen via git@87a1b60.

[gitgitgadget]

This patch series was integrated into seen via git@6a09a9b.

[gitgitgadget]

This branch is now known as mh/doc-windows-home-env.

[gitgitgadget]

This patch series was integrated into seen via git@cead366.

[gitgitgadget]

This patch series was integrated into seen via git@aab3dbf.