diff --git a/docs/docs/faq.mdx b/docs/docs/faq.mdx index aa086d16..8035c92d 100644 --- a/docs/docs/faq.mdx +++ b/docs/docs/faq.mdx @@ -77,8 +77,7 @@ They need to work on their terminal, somehow it only supports UTF-8 and not UTF- ### The term 'Set-Theme' is not recognized as the name of a cmdlet, function, script file, or operable program. -You need to migrate V2 to V3 using the following [guide][upgrading]. The quick fix is to replace `Set-Theme` with `Set-PoshPrompt`, -but it's advised to read the guide. +You need to migrate using the following [guide][migrating]. ### Strange colouring after exiting VIM or when using the PowerShell progress bootstrap @@ -201,7 +200,7 @@ $OutputEncoding = [console]::InputEncoding = [console]::OutputEncoding = New-Obj [nf]: https://www.nerdfonts.com/ [font]: /docs/configuration/fonts [jb-icons]: https://youtrack.jetbrains.com/issue/IDEA-248010 -[upgrading]: upgrading.md +[migrating]: /docs/migrating [wt-vim]: https://github.com/microsoft/terminal/issues/3794 [vim-wt]: https://github.com/vim/vim/issues/5092 [utf-8]: https://github.com/PowerShell/PowerShell/issues/7233#issuecomment-640243647 diff --git a/docs/docs/installation/prompt.mdx b/docs/docs/installation/prompt.mdx index af2291fa..9c248601 100644 --- a/docs/docs/installation/prompt.mdx +++ b/docs/docs/installation/prompt.mdx @@ -47,15 +47,6 @@ Once added, reload your profile for the changes to take effect. . $PROFILE ``` -:::caution -If you installed Oh My Posh using `Install-Module oh-my-posh`, you need to first import -Oh My Posh in your `$PROFILE` before adding the line above: - -```powershell -Import-Module oh-my-posh -``` -::: - diff --git a/docs/docs/installation/windows.mdx b/docs/docs/installation/windows.mdx index 200165e2..a4fbf61c 100644 --- a/docs/docs/installation/windows.mdx +++ b/docs/docs/installation/windows.mdx @@ -27,8 +27,6 @@ When using oh-my-posh inside the WSL, make sure to follow the [linux][linux] ins values={[ { label: 'winget', value: 'winget', }, { label: 'scoop', value: 'scoop', }, - { label: 'powershell', value: 'powershell', }, - { label: 'chocolatey', value: 'chocolatey'}, ] }> @@ -44,33 +42,6 @@ winget install JanDeDobbeleer.OhMyPosh scoop install https://github.com/JanDeDobbeleer/oh-my-posh/releases/latest/download/oh-my-posh.json ``` - - - -```powershell -Install-Module oh-my-posh -Scope CurrentUser -``` - -:::warning -The PowerShell module only installs the Oh My Posh executable inside PowerShell, to use Oh My posh outside of PowerShell -(bash, cmd, ...), add the following folder to your `$PATH`: - -```powershell -$env:POSH_PATH -``` -::: - - - - -:::info -The chocolatey package is managed by [Curtis Carter][cc]. In case of problems, please create an issue [here][cc-choco]. -::: - -```powershell -choco install oh-my-posh -``` - @@ -97,8 +68,6 @@ Add-MpPreference -ExclusionProcess oh-my-posh.exe values={[ { label: 'winget', value: 'winget', }, { label: 'scoop', value: 'scoop', }, - { label: 'powershell', value: 'powershell', }, - { label: 'chocolatey', value: 'chocolatey'}, ] }> @@ -114,20 +83,6 @@ winget upgrade JanDeDobbeleer.OhMyPosh scoop update oh-my-posh ``` - - - -```powershell -Update-Module oh-my-posh -``` - - - - -```powershell -choco upgrade oh-my-posh -``` - @@ -139,8 +94,6 @@ choco upgrade oh-my-posh values={[ { label: 'winget', value: 'winget', }, { label: 'scoop', value: 'scoop', }, - { label: 'powershell', value: 'powershell', }, - { label: 'chocolatey', value: 'chocolatey'}, ] }> @@ -156,28 +109,11 @@ You can find the themes scoop installs inside the `"$(scoop prefix oh-my-posh)\t To use `jandedobbeleer.omp.json` for example, you can refer to it using `"$(scoop prefix oh-my-posh)\themes\jandedobbeleer.omp.json"` when setting the prompt using the `--config` flag. - - - -You can find the themes PowerShell installs inside the `$env:POSH_THEMES_PATH` folder. -To use `jandedobbeleer.omp.json` for example, you can refer to it using `"$env:POSH_THEMES_PATH\jandedobbeleer.omp.json"` -when setting the prompt using the `--config` flag. - - - - -You can find the themes winget installs inside the `~\AppData\Local\Programs\oh-my-posh\themes\` folder. -To use `jandedobbeleer.omp.json` for example, you can refer to it using `~\AppData\Local\Programs\oh-my-posh\themes\jandedobbeleer.omp.json` -when setting the prompt using the `--config` flag. - [fonts]: /docs/configuration/fonts [scoop]: https://scoop.sh/ [wt]: https://github.com/microsoft/terminal -[powershell]: https://www.powershellgallery.com/packages/oh-my-posh -[cc]: https://github.com/digitalcoyote -[cc-choco]: https://github.com/digitalcoyote/chocolatey-packages/tree/master/oh-my-posh [linux]: /docs/installation/linux [themes]: /docs/themes diff --git a/docs/docs/migrating-module.md b/docs/docs/migrating-module.md new file mode 100644 index 00000000..452d3573 --- /dev/null +++ b/docs/docs/migrating-module.md @@ -0,0 +1,85 @@ +--- +id: migrating +title: PowerShell module +sidebar_label: đŸĒĻ PowerShell Module +--- + +## Problem statement + +Traditionally, the module was the only way to install oh-my-posh using `Install-Module oh-my-posh`. +Today, with the shift to the executable version over a year ago, it only acts as a wrapper around the +executable, offering no additional functionality. Throughout the year, the following changes have been made: + +- don't ship all binaries in the Module but download on `Import-Module` +- move all functionality from the Module to the [init][init] script + +There's a problem with the Module due to the following: + +- downloading the binary is a problem on company managed computers +- the module syncs cross device thanks to OneDrive sync, causing versions to be out of sync and [configs to break][idiots] +- it's impactful having to explain the difference time and time again (for me) + +## Migration steps + +### Remove the module's cached files + +```powershell +Remove-Item $env:POSH_PATH -Force -Recurse +``` + +:::warning +If you added custom elements to this location, they will be deleted with the command above. +Make sure to move these before running the command. +::: + +### Install oh-my-posh + +See your platform's installation guide. The preferred ways are **winget** and **homebrew**. + +- [Windows][windows] +- [macOS][macos] +- [Linux][linux] + +### Uninstall the PowerShell module + +```powershell +Uninstall-Module oh-my-posh --AllVersions +``` + +Delete the import of the PowerShell module in your `$PROFILE` + +```powershell +Import-Module oh-my-posh +``` + +### Adjust setting the prompt + +If you're still using `Set-PoshPrompt`, replace that statement with the following: + +#### I have a custom theme + +```powershell +oh-my-posh init pwsh --config ~/.custom.omp.json | Invoke-Expression +``` + +And replace `~/.custom.omp.json` with the location of your theme. + +#### I have an out of the box theme + +```powershell +oh-my-posh init pwsh --config "$env:POSH_THEMES_PATH\jandedobbeleer.omp.json" | Invoke-Expression +``` + +Replace `jandedobbeleer.omp.json` with the theme you use. + +:::caution +Only winget can add the `$env:POSH_THEMES_PATH` variable. For homebrew, use +`$(brew --prefix oh-my-posh)/themes/jandedobbeleer.omp.json` +::: + +[init]: https://github.com/JanDeDobbeleer/oh-my-posh/blob/main/src/shell/scripts/omp.ps1 +[idiots]: https://ohmyposh.dev/blog/idiots-everywhere +[windows]: /docs/installation/windows +[macos]: /docs/installation/macos +[linux]: /docs/installation/linux +[set-prompt]: /docs/installation/prompt diff --git a/docs/docs/upgrading.md b/docs/docs/upgrading.md deleted file mode 100644 index 670dde53..00000000 --- a/docs/docs/upgrading.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -id: upgrading -title: Upgrading -sidebar_label: 🤘 Upgrading from V2 ---- - -Just like V2, oh-my-posh is available in the [PowerShell gallery][psgallery]. - -## V2's problem statement - -Oh My Posh is the offspring of [Oh My Posh 2][omp], a prompt theme engine for PowerShell. -It started out by being inspired by tools like [Oh my ZSH][omz] when nothing was -available specifically for PowerShell. - -Over the years, I switched operating system/main shell quite a lot, even on -Windows via the [WSL][wsl]. This made it so that my prompt wasn't portable enough, -I wanted the same visual/functional experience regardless -of the shell I was working in. - -Additionally, V2 has Powershell module files as [themes][themesv2]. That way of working was inspired by [oh-my-zsh][omz] -and other prompt rendering tools, but that approach has a few important downsides. - -- hard to extend/adjust when you're not proficient -- the need to expose a lot of functions/settings to allow ease of personalization -- limited to Powershell - -## A brave new world - -This brings us to the first change, to allow a cross-platform experience, [Oh My Posh][v3] is written entirely in [Go][golang]. -That way, cross-platform binaries can be shipped which render the same prompt using the same config anywhere. - -The configuration is changed from `$ThemeSettings` towards a `.json` file that only contains the configuration for the -blocks and segments you want to render. See [concept][introduction] for more context on that part. - -Let's have a look at the V2 commands and how to move towards V3. - -## Import - -Stays the same! Alright. All you need to do is update oh-my-posh. - -```powershell -Update-Module -Name oh-my-posh -Scope CurrentUser -``` - -## Configuration - -Here we have a few options. If you're using an out-of-the-box theme, you can simply change the current command to the -new one, provided your V2 theme has already been added to [oh-my-posh][themesv3]. - -### I use an out-of-the-box theme - -Change the current prompt setting function to the new one. - -```powershell -# Set-Theme Agnoster -Set-PoshPrompt -Theme agnoster -``` - -### I use a custom theme/settings - -The first thing to do is to look for the theme you based your theme on. -If you don't remember which one, preview them all and take the one closest to yours. - -```powershell -Get-PoshThemes -``` - -If you see one you like, set it, then export its config so you can customize/extend the blocks and segments. - -```powershell -Set-PoshPrompt -Theme jandedobbeleer -Export-PoshTheme -FilePath ~/.oh-my-posh.omp.json -``` - -Adjust the config (`~/.oh-my-posh.omp.json`) to your liking by going through the [configuration][configuration] guide. -Set your custom theme and enjoy. - -```powershell -Set-PoshPrompt -Theme ~/.oh-my-posh.omp.json -``` - -### I have no idea just yet - -Great! There's an option for that too. You can easily list all available themes and pick the one you like best. - -```powershell -Get-PoshThemes -``` - -Choose and set the one you like. - -```powershell -Set-PoshPrompt -Theme jandedobbeleer -``` - -## All set, now what - -You can either tweak the theme to your liking, add segments or [submit an issue][issues] for new functionality. -Do not hesitate to [ask for assistance][issues] when you notice an issue or unexpected behavior. - -[psgallery]: https://www.powershellgallery.com/packages/oh-my-posh -[omp]: https://github.com/JanDeDobbeleer/oh-my-posh2 -[wsl]: https://docs.microsoft.com/en-us/windows/wsl/install-win10 -[themesv2]: https://github.com/JanDeDobbeleer/oh-my-posh/tree/master/themes -[omz]: https://github.com/ohmyzsh/ohmyzsh -[golang]: https://golang.org/ -[introduction]: /docs/#concept -[v3]: https://github.com/JanDeDobbeleer/oh-my-posh/ -[themesv3]: https://github.com/JanDeDobbeleer/oh-my-posh/tree/main/themes -[configuration]: /docs/configuration/overview -[issues]: https://github.com/JanDeDobbeleer/oh-my-posh/issues/new diff --git a/docs/sidebars.js b/docs/sidebars.js index 0659e6cd..147440e3 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -6,7 +6,6 @@ module.exports = { collapsed: false, items: [ "introduction", - "upgrading", { type: "category", label: "🚀 Get started", @@ -121,6 +120,7 @@ module.exports = { "themes", "share", "faq", + "migrating", "contributors", ], }; diff --git a/packages/powershell/oh-my-posh.psm1 b/packages/powershell/oh-my-posh.psm1 index 327ff809..5155a0d5 100644 --- a/packages/powershell/oh-my-posh.psm1 +++ b/packages/powershell/oh-my-posh.psm1 @@ -1,3 +1,20 @@ +Write-Host @' +Hey friend + +In an effort to grow oh-my-posh, the decision was made to no +longer support the PowerShell module. Over the past year, the +added benefit of the module disappeared, while the burden of +maintaining it increased. + +However, this doesn't mean oh-my-posh disappears from your +terminal, it just means that you'll have to use a different +tool to install it. + +All you need to do, is follow the migration guide here: + +https://ohmyposh.dev/docs/migrating +'@ + function Get-CachePath { [CmdletBinding()] param ( @@ -41,127 +58,7 @@ function Set-PoshRootPath { $env:POSH_PATH = $env:HOME } -function Get-PoshDownloadUrl { - param( - [Parameter(Mandatory = $true)] - [string] - $Version - ) - - $executable = "" - if ($IsMacOS) { - $executable = "posh-darwin-amd64" - } - elseif ($IsLinux) { - # this is rather hacky but there's no other way for the time being - $arch = uname -m - if ($arch -eq 'aarch64') { - $executable = "posh-linux-arm64" - } - elseif ($arch -eq 'armv7l') { - $executable = "posh-linux-arm" - } - else { - $executable = "posh-linux-amd64" - } - } - else { - $arch = (Get-CimInstance -Class Win32_Processor -Property Architecture).Architecture - switch ($arch) { - 0 { $executable = "posh-windows-386.exe" } # x86 - 5 { $executable = "posh-windows-arm64.exe" } # ARM - 9 { $executable = "posh-windows-amd64.exe" } # x64 - 12 { $executable = "posh-windows-amd64.exe" } # x64 emulated on Surface Pro X - } - } - if ($executable -eq "") { - throw "oh-my-posh: Unsupported architecture: $arch" - } - return "https://github.com/jandedobbeleer/oh-my-posh/releases/download/v$Version/$executable" -} - -function Get-PoshExecutable { - param( - [Parameter(Mandatory = $true)] - [string] - $Url, - [Parameter(Mandatory = $true)] - [string] - $Destination - ) - - Invoke-WebRequest $Url -Out $Destination - if (-Not (Test-Path $executable)) { - # This should only happen with a corrupt installation - throw "Executable at $executable was not found, please try importing oh-my-posh again." - } - # Set the right binary to executable before doing anything else - # Permissions don't need to be set on Windows - if ($PSVersionTable.PSEdition -ne "Core" -or $IsWindows) { - return - } - chmod a+x $executable 2>&1 -} - -function Get-PoshCommand { - if ($PSVersionTable.PSEdition -ne "Core" -or $IsWindows) { - return Join-Path -Path $env:POSH_PATH -ChildPath "oh-my-posh.exe" - } - return Join-Path -Path $env:POSH_PATH -ChildPath "oh-my-posh" -} - -function Sync-PoshThemes { - param( - [Parameter(Mandatory = $true)] - [string] - $Version - ) - - Write-Host "Downloading oh-my-posh themes for $Version" - $tmp = New-TemporaryFile | Rename-Item -NewName { $_ -replace 'tmp$', 'zip' } -PassThru - $themesUrl = "https://github.com/jandedobbeleer/oh-my-posh/releases/download/v$Version/themes.zip" - Invoke-WebRequest -OutFile $tmp $themesUrl - $destination = $env:POSH_THEMES_PATH - $tmp | Microsoft.PowerShell.Archive\Expand-Archive -DestinationPath $destination -Force - $tmp | Remove-Item -} - -function Sync-PoshArtifacts { - param( - [Parameter(Mandatory = $true)] - [string] - $Version - ) - - $executable = Get-PoshCommand - if (-not (Test-Path $executable)) { - Write-Host "Downloading oh-my-posh executable for $Version" - $url = Get-PoshDownloadUrl -Version $Version - Get-PoshExecutable -Url $url -Destination $executable - Sync-PoshThemes -Version $Version - return - } - $poshVersion = & $executable --version - if ($poshVersion -eq "development") { - Write-Warning "omp development version detected" - return - } - if ($poshVersion -eq $Version) { - return - } - Write-Host "Updating oh-my-posh executable to $Version" - $url = Get-PoshDownloadUrl -Version $Version - Get-PoshExecutable -Url $url -Destination $executable - Sync-PoshThemes -Version $Version -} - Set-PoshRootPath -$env:PATH = $env:POSH_PATH + [System.IO.Path]::PathSeparator + $env:PATH -$env:POSH_THEMES_PATH = Join-Path -Path $env:POSH_PATH -ChildPath "themes" -$moduleVersion = Split-Path -Leaf $MyInvocation.MyCommand.ScriptBlock.Module.ModuleBase -Sync-PoshArtifacts -Version $moduleVersion - -# Legacy functions function Set-PoshPrompt { param( @@ -169,24 +66,4 @@ function Set-PoshPrompt { [string] $Theme ) - - $config = "" - if (Test-Path "$($env:POSH_THEMES_PATH)/$Theme.omp.json") { - $path = "$($env:POSH_THEMES_PATH)/$Theme.omp.json" - $config = (Resolve-Path -Path $path).ProviderPath - } - elseif (Test-Path $Theme) { - $config = (Resolve-Path -Path $Theme).ProviderPath - } - else { - $config = "$($env:POSH_THEMES_PATH)/jandedobbeleer.omp.json" - } - - # Workaround for get-location/push-location/pop-location from within a module - # https://github.com/PowerShell/PowerShell/issues/12868 - # https://github.com/JanDeDobbeleer/oh-my-posh2/issues/113 - $global:OMP_GLOBAL_SESSIONSTATE = $PSCmdlet.SessionState - - $poshCommand = Get-PoshCommand - (& $poshCommand init pwsh --config="$config") | Invoke-Expression }