{"id":17867030,"url":"https://github.com/jaykul/powerline","last_synced_at":"2025-04-04T06:10:04.162Z","repository":{"id":40431994,"uuid":"66994113","full_name":"Jaykul/PowerLine","owner":"Jaykul","description":"A more PowerShell prompt","archived":false,"fork":false,"pushed_at":"2024-09-04T05:49:32.000Z","size":465,"stargazers_count":573,"open_issues_count":15,"forks_count":32,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-03-28T05:12:11.298Z","etag":null,"topics":["powerline","powershell","powershell-classes","powershell-modules","prompt"],"latest_commit_sha":null,"homepage":"","language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Jaykul.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-08-31T02:10:22.000Z","updated_at":"2025-02-28T00:22:06.000Z","dependencies_parsed_at":"2022-08-09T20:20:12.607Z","dependency_job_id":"0a9a1f7e-06ba-4025-9d87-ea1abd7eb16a","html_url":"https://github.com/Jaykul/PowerLine","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jaykul%2FPowerLine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jaykul%2FPowerLine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jaykul%2FPowerLine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jaykul%2FPowerLine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Jaykul","download_url":"https://codeload.github.com/Jaykul/PowerLine/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247128753,"owners_count":20888235,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["powerline","powershell","powershell-classes","powershell-modules","prompt"],"created_at":"2024-10-28T09:42:58.343Z","updated_at":"2025-04-04T06:10:04.147Z","avatar_url":"https://github.com/Jaykul.png","language":"PowerShell","readme":"[![Build on push](https://github.com/PoshCode/Metadata/actions/workflows/build.yml/badge.svg)](https://github.com/PoshCode/Metadata/actions/workflows/build.yml)\n\n# PowerLine - Beautiful, Powerful, PowerShell prompts\n\n- [Install](#install)\n- [First Use](#first-use-configuration)\n- [Why Powerline](#why-powerline)\n- [Using PowerLine](#using-powerline)\n    - [Configuration](#configuration)\n- [Helpers for Module Authors](#helpers-for-module-authors)\n\n## Install\n\nYou can install PowerLine from the PowerShell gallery, using the following commands:\n\n```\nInstall-Module PANSIES -AllowClobber\nInstall-Module PowerLine\nImport-Module PowerLine\n```\n\n\u003e **NOTE:**\n\u003e My [`PANSIES` module for ANSI Escape Sequences](//github.com/PoshCode/Pansies) is required, and because of how PowerShellGet works, you need to install it separately, as it includes an improved `Write-Host` (which is faster, and fully backwards compatible), and therefore requires the `-AllowClobber` switch when installing.\n\n## First use configuration\n\nThere are quite a few options for PowerLine, and you're going to want to set some of them immediately to take full advantage. Check out the [./Source/Examples](./Source/Examples) for some ideas.\n\n```posh\nSet-PowerLinePrompt -SetCurrentDirectory -RestoreVirtualTerminal -Newline -Timestamp -Colors \"#FFDD00\", \"#FF6600\"\n```\n![Prompt ScreenShot](assets/prompt.png)\n\nYou can change the colors by running just that part of the command:\n\n```Posh\nSet-PowerLinePrompt -Colors \"#00DDFF\", \"#0066FF\"\n```\n![Prompt ScreenShot](assets/left-prompt.png)\n\nYou can review (or modify) your current blocks by using `$prompt`, and check which colors it's using with `$prompt.colors`, but there are also commands like the one above to help out.\n\nNow you can add additional blocks to your prompt, even inserting them into the list. Blocks without output are automatically hidden in PowerLine, so you can write a conditional block like this:\n\n```posh\nAdd-PowerLineBlock { if($pushed = (Get-Location -Stack).count) { \"\u0026raquo;$pushed\" } }  -Index 1\n```\n\n![Prompt ScreenShot](assets/pushd.png)\n\nNote that in your PowerLine blocks, there is full support for [PANSIES](/PoshCode/PANSIES) `Text`, which means colors from it's drives, like `$fg:red` and named HTML Entities like `\u0026hearts;` and `\u0026euro;` and now, even emoji and nerdfont named entities -- if you enable them.\n\nThere are some helper functions in PowerLine for common things you'd want in your prompt, like `Get-ShortenedPath` and `Get-SegmentedPath` as well as `Get-Elapsed` and `Test-Elevation` and `Test-Success`.\n\nOnce you start playing with the [other options](#configuration), and get it the way you want, you can save it, and Powerline will re-load it on import in the future:\n\n```posh\nExport-PowerlinePrompt\n```\n\nFor more information about the [configuration](#configuration) --particularly how to get the cool angled separators you see in my screenshots using [powerline fonts](#powerline-fonts-and-separators)-- you can skip past this explanation of why I wrote the module, but you should also explore the commands, as this external documentation is always lagging behind the implementation.\n\n## Why Powerline?\n\n```gherkin\nAs a PowerShell user\nIn order to have the right information available\nI need to be able to customize my prompt\n\nAs a PowerShell module author\nIn order to give my users the right information\nI need to add information to the user's prompt\n\nAs an alpha geek\nIn order to stand out\nI want to have a cool prompt!\n```\n\n\u003e Currently in PowerShell, the prompt is a function that _must_ return a string. Modules that want to add information to your prompt typically _don't even try_ if you have customized your prompt (see Posh-Git, for example). The goal of PowerLine is to have beautiful custom prompts **and** let modules add (and remove) information easily.\n\n### Your Prompt as a Collection\n\nThe core principle of PowerLine 3 is to make your prompt easier to change, and changes easier to undo.\n\nThe idea is to assume a `$Prompt` variable that's a `List` of `ScriptBlock` and just join the output of those scriptblocks:\n\n```posh\nfunction prompt {\n    -join $prompt.Invoke()\n}\n```\n\n### Why Lists of ScriptBlocks?\n\n1. The user can easily add or remove information on the fly.\n2. Modules can add (and remove) information as they're imported/removed.\n3. We can customize the look separate from the content.\n\nTake this for example, it's the same as the current default prompt, except split in three parts:\n\n```\n[System.Collections.Generic.List[ScriptBlock]]$Prompt = @(\n    { \"PS \" }\n    { $executionContext.SessionState.Path.CurrentLocation }\n    { '\u003e' * ($nestedPromptLevel + 1) }\n)\n```\n\nThis would produce _the same output_ as before, and would have _no impact_ on users who already overwrite the default prompt. In fact, **you** can switch to this right now, by just putting those two blocks in your profile.\n\n\n### For users:\n\nIt's suddenly easy to tweak the prompt. I can remove the unecessary \"PS \" from the front of my prompt by just running\n\n```posh\n$Prompt = $Prompt | Select -Skip 1\n```\n\nOr if I wanted to print the current command's `HistoryId` instead of the \"PS\", I could just replace that first part:\n\n```posh\n$Prompt[0] = { \"$($MyInvocation.HistoryId) \" }\n```\n\n### For module authors:\n\nModules can modify the prompt just as easily. Adding to a list is simpler and easier to undo, plus it's possible for the user to re-order their prompt. Since modules don't have to modify or wrap the actual prompt function, users end up in control.\n\nFor example, posh-git can add it's information to the prompt in just one line:\n\n```posh\n$Prompt.Add({Write-VcsStatus})\n```\n\nAnd can hook it's own removal to clean up the status:\n\n```posh\n$MyInvocation.MyCommand.Module.OnRemove = {\n    $Prompt.RemoveAll( {param($_) $_.ToString().Trim() -eq \"Write-VcsStatus\" } )\n}\n```\n\n## Using PowerLine\n\nOf course, with PowerLine, it's even easier. A module can just run:\n\n```posh\nAdd-PowerLineBlock { Write-VcsStatus } -AutoRemove\n```\n\n### Configuration\n\nPowerLine has a lot of flexibility and functionality around output and looks. Because your whole prompt is just a list of script blocks, we can transform your prompt's appearance. You can go from simple to elegant instantly, and then take control of colors and more.\n\nOne important aspect of configuring PowerLine is that it supports both the Configuration module and the EzTheme module. It saves it's current configuration when you run `Export-PowerLinePrompt` and automatically re-imports it when you import the module.\n\n#### The Configuration Module\n\nAs with any module which supports Configuration, you can get the configuration as a hashtable using the Configuration commands:\n\n```PowerShell\n$Configuration = Get-Module PowerLine | Import-Configuration\n```\n\nYou can examine and modify the configuration and then save it back to disk with:\n\n```PowerShell\nGet-Module PowerLine | Export-Configuration $Configuration\n```\n\n#### The EzTheme Module\n\nOf course, the EzTheme module supports some of the same functionality as the Configuration module -- it's goal is to support theming lots of modules at once (i.e. with each theme), so you can get your settings with `Get-PowerLineTheme` which by default will show a preview. You can review the settings by using `Format-List`, capture them with a variable and modify them (and even preview the modifications). As with any module that supports EzTheme, you can modify the returned object and put it back by piping it to `Set-PowerLineTheme`.\n\n#### PowerLine Coloring blocks\n\nThe `-Colors` parameter supports setting the background colors. You can pass a list of colors and PowerLine will loop through them.\nYou can also specify two colors, and PowerLine will generate a gradient between those colors with the same number of steps as you have output blocks.\n\nBasically, each scriptblock which has output (PowerLine cleans up and ignores empty blocks), uses one of those colors, looping back to the first if it runs out.\nPowerLine automatically selects contrasting colors for the text (foreground) color.\n\nYou can set the color with something like this: `Set-PowerLinePrompt -Color \"#00DDFF\",\"#0066FF\"`\n\n#### PowerLine Fonts and Separators\n\nThe `-PowerLineFont` switch requires using a [PowerLine font](https://github.com/PowerLine/fonts), which is a font that\nhas the extra extended characters with the nice angled separators you see in the screenshots here between colors.\nThere are a lot of monospaced fonts to choose from, and you can even install them all by just cloning the repository\nand running the `install.ps1` script, or you can just pick just one TTF and download and install that.\n\nThere are [screenshots of all of them here](https://github.com/powerline/fonts/blob/master/samples/All.md).\n\nIf you're not using a PowerLine font, don't use the `-PowerLineFont` switch, and the module will output common ASCII\nbox characters like ▌ as the separators...\n\nThese characters are set into a dictionary (`[PoshCode.Pansies.Entities]::ExtendedCharacters`) when you call `Set-PowerLinePrompt`.\n\n#### Prompts as arrays\n\nBy default, each ScriptBlock outputs one string, and is colored in one color, with the \"ColorSeparator\" character between each block.\n\nHowever, PowerLine also supports blocks which output arrays. When a ScriptBlock outputs an array of strings,\nthey will be separated with the alternate \"Separator\" instead of the \"ColorSeparator\".\n\nAll you need to to is start adding things to your `$Prompt` -- you can do that directly on the list, using `$Prompt.Add` or `$Prompt.Insert`, or you can use the `Add-PowerLine` command.\n\n#### Right-aligned blocks\n\nIf you add a scriptblock that outputs _just_ a tab ``{ \"`t\" }``,\nblocks after that will be right-aligned until the next block which is _just_ a newline ``{ \"`n\" }``.\n\nFor Right-aligned blocks, the \"ReverseColorSeparator\" or \"ReverseSeparator\" characters are used instead of the \"ColorSeparator\" and \"Separator\".\n\n#### Characters and Custom Entities\n\nPowerLine uses the [Pansies](https://github.com/PoshCode/Pansies) module for coloring and output, so it inherits Pansies' support for [HTML named entities](https://www.w3schools.com/charsets/ref_html_entities_4.asp) like `\u0026hearts;` and `\u0026copy;` or `\u0026cent;` and numerical unicode character entities in decimal (`\u0026#926;`) and hexadeximal (`\u0026#x39E;`), so you can easily embed characters.\n\nAdditionally, Pansies treats the `ExtendedCharacters` dictionary of characters mentioned earlier as entities, and has an additional `EscapeSequences` dictionary which maps entity names to a string. Both of these are modifyable and support adding your own characters, which can then be used as named entities with a `\u0026` and a `;` ...\n\n### Helper Functions for Prompts\n\nWe recommend that modules which want to add information to the prompt create a function which returns a string, and then add a scriptblock wrapping that single function to the `$Prompt` using `Add-PowerLineBlock` (or by hand, as shown above).\n\nThere are a few extra functions included as part of the PowerLine module:\n\nCmdlet                | Description\n----                  | -----------\nNew-PromptText        | A wrapper for New-Text that supports changing foreground or background colors based on whether there's an error or whether the session is elevated.\nGet-Elapsed           | Calls Get-History to get a single command (the most recent, or by ID) and returns the difference between the Start and End execution time.\nGet-SegmentedPath     | Converts a path to an array of Pansies Text objects (one for each folder), with a limit on how many folders to return. Truncates and appends an ellipsis.\nGet-ShortenedPath     | Shortens a path to a specified length, with some options for the output\nTest-Elevation        | Returns True if the current session is elevated, false otherwise\nTest-Success          | Returns True if the last command was successful, false otherwise\n\n\n## Helpers for module authors\n\nPowerLine also provides some additional functions for adding and removing from the prompt list so that modules can add without worrying about doubling up. If Posh-git was to actually adopt the code I mentioned earlier, every time you imported it, they would append to your prompt -- and since they're not cleaning up when you remove the module, they would get re-imported automatically whenever you removed the module.\n\nPowerLine gives you an `Add-PowerLineBlock` which lets you pass in a `ScriptBlock` and have it added to the prompt only if it's not already there -- which means the user can move it around, and re-import the module without having it show up twice. It even has an `-AutoRemove` switch which can be used when adding to the PowerLine from a module to automatically remove that block if the module is removed by the user. And of course, there's a `Remove-PowerLineBlock` which lets you clean up manually.\n\nThere is a `New-PromptText` function which allows you to change the colors based on elevation, or the success of the last command.\n\nFinally, there are separate `Test-Success` and `Test-Elevation` functions (which are used by New-PromptText), if you just want to output something conditionally, or deal with it on your own.\n\n## Future Plans\n\nIf you have any questions, [please ask](https://github.com/jaykul/PowerLine/issues),\nand feel free to send me pull requests with additional escape sequences, or whatever.\n\nPowerLine now depends on [Pansies](https://github.com/PoshCode/Pansies) for color, special characters, etc.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaykul%2Fpowerline","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjaykul%2Fpowerline","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaykul%2Fpowerline/lists"}