Linux Get-Help does not find CurrentUser Update-Help topics, only AllUsers · Issue #21187 · PowerShell/PowerShell · GitHub

Prerequisites

Write a descriptive title.
Make sure you are able to repro it on the latest released version
Search the existing issues.
Refer to the FAQ.
Refer to Differences between Windows PowerShell 5.1 and PowerShell.

Steps to reproduce

Using Docker:

docker run -it mcr.microsoft.com/powershell
$env:LANG #Confirm culture, en_US.UTF-8
get-help find-command #Does not find help


#Currentuser Test
command find-command |% module | update-help -verbose #Verbose messages confirm it is installed to right folder
gc -raw ~/.local/share/powershell/Help/PowerShellGet/en-US/PSModule-help.xml #Confirm help file is present
get-help find-command #Still cannot find help files, will succeed but Remarks will show that it cannot find the offline help file.

#Allusers test
sudo pwsh -c 'command find-command |% module | update-help -scope allusers -verbose -uiculture en-US' #Installl for all uesers and confirm it shows up in /opt/microsoft/powershell
get-help find-command #Works and now shows a synopsis and description

Workaround

Install using -scope allusers (requires access to /opt psinstall folder which usually means root/sudo)

Expected behavior

Offline Help Displays with a synopsis and a description
Remarks does not have the line "Get-Help cannot find the Help files for the cmdlet on this computer."

Actual behavior

Display only basic name and syntax
Remarks has the line "Remarks does not have the line "Get-Help cannot find the Help files for the cmdlet on this computer."

Error details

No response

Environment data

Name                           Value
----                           -----
PSVersion                      7.4.1
PSEdition                      Core
GitCommitId                    7.4.1
OS                             Ubuntu 22.04.3 LTS
Platform                       Unix
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0…}
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1
WSManStackVersion              3.0

Visuals

No response

Verified on multiple users and OS systems.

An strace shows that it does find the help en-US folder, but it never reads or parses the XML beyond that, something is causing it to die at this step.

root@c6497a55fd5e:~# strace -f -t -e trace=file -p 1 2>&1 | grep '.local/share/powershell'
[pid    27] 23:11:32 lstat("/root/.local/share/powershell/PSReadLine/ConsoleHost_history.txt", {st_mode=S_IFREG|0644, st_size=353, ...}) = 0
[pid    27] 23:11:32 openat(AT_FDCWD, "/root/.local/share/powershell/PSReadLine/ConsoleHost_history.txt", O_WRONLY|O_CREAT|O_CLOEXEC, 0666) = 214
[pid    27] 23:11:32 lstat("/root/.local/share/powershell/PSReadLine/ConsoleHost_history.txt", {st_mode=S_IFREG|0644, st_size=374, ...}) = 0
[pid    27] 23:11:32 stat("/root/.local/share/powershell/Help", {st_mode=S_IFDIR|0755, st_size=4096, ...}) = 0
[pid    27] 23:11:32 stat("/root/.local/share/powershell/Help/PowerShellGet", {st_mode=S_IFDIR|0755, st_size=4096, ...}) = 0
[pid    27] 23:11:32 stat("/root/.local/share/powershell/Help/en-US", 0x7ed47effbd08) = -1 ENOENT (No such file or directory)
[pid    27] 23:11:32 stat("/root/.local/share/powershell/Help/en", 0x7ed47effbd08) = -1 ENOENT (No such file or directory)
[pid    27] 23:11:32 stat("/root/.local/share/powershell/Help", {st_mode=S_IFDIR|0755, st_size=4096, ...}) = 0
[pid    27] 23:11:32 openat(AT_FDCWD, "/root/.local/share/powershell/Help", O_RDONLY|O_NONBLOCK|O_CLOEXEC|O_DIRECTORY) = 169

#Finds Correct Folder Here after some false starts
[pid    27] 23:11:32 stat("/root/.local/share/powershell/Help/PowerShellGet/en-US", {st_mode=S_IFDIR|0755, st_size=4096, ...}) = 0

[pid    27] 23:11:32 openat(AT_FDCWD, "/root/.local/share/powershell/Help/PowerShellGet/en-US", O_RDONLY|O_NONBLOCK|O_CLOEXEC|O_DIRECTORY) = 169
[pid    27] 23:11:32 stat("/root/.local/share/powershell/Help/PowerShellGet/en", 0x7ed47effbd08) = -1 ENOENT (No such file or directory)
[pid    27] 23:11:32 stat("/root/.local/share/powershell/Help/PowerShellGet", {st_mode=S_IFDIR|0755, st_size=4096, ...}) = 0
[pid    27] 23:11:32 openat(AT_FDCWD, "/root/.local/share/powershell/Help/PowerShellGet", O_RDONLY|O_NONBLOCK|O_CLOEXEC|O_DIRECTORY) = 169

It doesn't appear to be a potential caching issue, I tried multiple Update-Help -Force -scope currentuser and started multiple separate pwsh processes after updating.

Without docker Update-Help -Scope CurrentUser works as expected.

rhubarb-geek-nz did you scroll all the way to the bottom? Because your help is missing synopsis and description, and had you scrolled to the bottom it would have said it was unable to find the help files.

And even as root, root still has a home directly and .local/share and the discovery behavior would be the same regardless of if it's "root" or a "normal" user.

Without docker Update-Help -Scope CurrentUser works as expected.

Define "works as expected", because it does not on standalone linux VMs for me of various flavors.

Note Get-Help will "work" e.g. not error and display output but it will only show partial help, just what it generates from the module info. It only actually reads the help if you see synopsis and description, and the remarks do not have this line:

To help clarify the success criteria:

if you are not seeing a synopsis and a description then you are not reading from the offline help files.
You also need to make sure the help doesn't already exist in /opt/powershell from doing an update-help -scope allusers, hence why I provided Docker as an easy way to produce a "fresh" environment.

I updated the original post with more clear success criteria.

Define "works as expected", because it does not on standalone linux VMs for me of various flavors.

What I have to define?

I just type the command and press Enter. The laptop has Linux installed as the only OS. PowerShell is unpacked from the tar.gz downloaded from the release page.

I just type the command and press Enter. The laptop has Linux installed as the only OS. PowerShell is unpacked from the tar.gz downloaded from the release page.

I clarified the success criteria above for testing, thanks.

I've dug into this a bit to figure out what the problem is. The logic for getting the help data for cmdlets/script functions is in CommandHelpProvider.GetHelpInfo.

This function is a bit complicated but I found there are multiple ways it can find the help content for cmdlets/script functions:

.ExternalHelp Foo.xml inside a script functions comment based help
- This only checks in $ScriptThatDefinesFunctionDirectory/$externalHelpFileName
Module help paths
- ~/.local/share/powershell/Help
- $ModuleBasePath
- ~/.local/share/powershell/Help/$ModuleName
- It searches the above 3 directories for $ModuleName-Help.xml

One thing to note is that the help file searcher also searches inside culture folders, e.g. en-US.

Using Find-Command as an example we can see it is a script based function and defines an external help file PSModule-help.xml

(Get-Item function:Find-Command).Definition -split "\r?\n" | Select-Object -First 10

    <#
    .ExternalHelp PSModule-help.xml
    #>
    [CmdletBinding(HelpUri = 'https://go.microsoft.com/fwlink/?LinkId=733636')]
    [outputtype('PSCustomObject[]')]
    Param
    (
        [Parameter(Position = 0)]
        [ValidateNotNullOrEmpty()]

With the first help find option we can see that it will search for the following path

$culture = 'en-US'  # hardcoded for this test
$functionDir = Split-Path ${Function:Find-Command}.File -Parent
Join-Path $functionDir $culture "PSModule-help.xml"

# /opt/microsoft/powershell/7/Modules/PowerShellGet/en-US/PSModule-help.xml

If you combine that with the fallback help file lookup we can see it is going to search for the help file under

/opt/microsoft/powershell/7/Modules/PowerShellGet/$culture/PSModule-help.xml
~/.local/share/powershell/Help/$culture/PowerShellGet-help.xml
/opt/microsoft/powershell/7/Modules/PowerShellGet/$culture/PowerShellGet-help.xml
~/.local/share/powershell/Help/PowerShellGet/$culture/PowerShellGet-help.xml

Notice how only the script comment based help ExternalHelp option is searching for PSModule-help.xml, the fallback options which do search in the user specific dirs is searching for only the module name. This is important because Update-Help is going to download PSModule-help.xml and place it under ~/.local/share/powershell/Help/PowerShellGet/$culture/PSModule-help.xml. Installing it with -Scope AllUsers works today as PowerShell does check for PSModule-help.xml but only in the module base where AllUsers is installing to.

If you were to rename the downloaded help file in the user dir to PowerShellGet-help.xml then it will be able to find the help file.

Get-Help Find-Command

# NAME
#     Find-Command
#
# ...
#
# REMARKS
#     Get-Help cannot find the Help files for this cmdlet on this computer. It is displaying only partial help.
# ...

Copy-Item ~/.local/share/powershell/Help/PowerShellGet/en-US/PSModule-help.xml ~/.local/share/powershell/Help/PowerShellGet/en-US/PowerShellGet-help.xml
Get-Help Find-Command

# NAME
#     Find-Command
#
# ...
#
# REMARKS
#     To see the examples, type: "Get-Help Find-Command -Examples"
...

Not sure if it's related but here is one I opened a while back where About topics weren't returned unless it was in the module folder. #18397

Linux Get-Help does not find CurrentUser Update-Help topics, only AllUsers · Issue #21187 · PowerShell/PowerShell · GitHub

Repository navigation

Linux Get-Help does not find CurrentUser Update-Help topics, only AllUsers #21187

Prerequisites

Steps to reproduce

Workaround

Expected behavior

Actual behavior

Error details

Environment data

Visuals

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Linux Get-Help does not find CurrentUser Update-Help topics, only AllUsers · Issue #21187 · PowerShell/PowerShell · GitHub

Repository navigation

Linux Get-Help does not find CurrentUser Update-Help topics, only AllUsers #21187

Description

Prerequisites

Steps to reproduce

Workaround

Expected behavior

Actual behavior

Error details

Environment data

Visuals

Activity

JustinGrote commented on Feb 5, 2024

237dmitry commented on Feb 6, 2024

JustinGrote commented on Feb 6, 2024

JustinGrote commented on Feb 6, 2024

JustinGrote commented on Feb 6, 2024

JustinGrote commented on Feb 6, 2024

237dmitry commented on Feb 6, 2024

JustinGrote commented on Feb 6, 2024

jborean93 commented on Feb 6, 2024

ThomasNieto commented on Feb 7, 2024

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions