{"id":25411293,"url":"https://github.com/sharpjs/psprefix","last_synced_at":"2025-04-14T08:27:52.002Z","repository":{"id":277410700,"uuid":"932337567","full_name":"sharpjs/PSPrefix","owner":"sharpjs","description":"A PowerShell module that prefixes output with the elapsed time or a custom header","archived":false,"fork":false,"pushed_at":"2025-02-23T02:57:31.000Z","size":178,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-23T03:17:39.342Z","etag":null,"topics":["powershell","powershell-module"],"latest_commit_sha":null,"homepage":"","language":"C#","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/sharpjs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE.txt","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":"2025-02-13T18:48:00.000Z","updated_at":"2025-02-23T02:53:36.000Z","dependencies_parsed_at":"2025-02-13T20:20:22.290Z","dependency_job_id":"7c55e7ea-5d20-4bd3-b6f7-67b816e25397","html_url":"https://github.com/sharpjs/PSPrefix","commit_stats":null,"previous_names":["sharpjs/psprefix"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sharpjs%2FPSPrefix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sharpjs%2FPSPrefix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sharpjs%2FPSPrefix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sharpjs%2FPSPrefix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sharpjs","download_url":"https://codeload.github.com/sharpjs/PSPrefix/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248845127,"owners_count":21170705,"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":["powershell","powershell-module"],"created_at":"2025-02-16T10:17:05.519Z","updated_at":"2025-04-14T08:27:51.990Z","avatar_url":"https://github.com/sharpjs.png","language":"C#","readme":"## About\n\nThe **PSPrefix** PowerShell module improves the output of long-running, potentially parallel tasks.\n\nPSPrefix provides three cmdlets:\n\n- **Show-Prefixed** – prefixes output with a custom header.\n- **Show-Elapsed** – prefixes output with an elapsed-time header.\n- **Get-SynchronizedHost** – makes the current `$Host` shareable across threads.\n\n![An example showing use and output of Show-Prefixed nested within Show-Elapsed and invoking various Write cmdlets](https://raw.githubusercontent.com/sharpjs/PSPrefix/main/img/example.png)\n\n## Status\n\n[![Build](https://github.com/sharpjs/PSPrefix/workflows/Build/badge.svg)](https://github.com/sharpjs/PSPrefix/actions)\n[![Build](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/sharpjs/PSPrefix/actions)\n[![PSGallery](https://img.shields.io/powershellgallery/v/PSPrefix.svg)](https://www.powershellgallery.com/packages/PSPrefix)\n[![PSGallery](https://img.shields.io/powershellgallery/dt/PSPrefix.svg)](https://www.powershellgallery.com/packages/PSPrefix)\n\n## Installation\n\nTo install in PowerShell 7.2 or later:\n\n```pwsh\nInstall-Module PSPrefix\n```\n\nTo update:\n\n```pwsh\nUpdate-Module PSPrefix\n```\n\n## Usage\n\n### The Basics\n\nTo prefix command output with an abitrary string, use the `Show-Prefixed` cmdlet.\n\n```pwsh\nShow-Prefixed \"Foo\" {\n    # your commands here\n}\n```\n\n![Output of the Show-Prefixed example above](https://raw.githubusercontent.com/sharpjs/PSPrefix/main/img/output-prefixed.png)\n\nTo prefix command output with the elapsed time, use the `Show-Elapsed` cmdlet.\n\n```pwsh\nShow-Elapsed {\n    # your commands here\n}\n```\n\n![Output of the Show-Elapsed example above](https://raw.githubusercontent.com/sharpjs/PSPrefix/main/img/output-elapsed.png)\n\nThe cmdlets can be combined.\n\n```pwsh\nShow-Elapsed {\n    Show-Prefixed Foo {\n        Show-Prefixed Bar {\n            # your commands here\n        }\n    }\n}\n```\n\n![Output of the combined example above](https://raw.githubusercontent.com/sharpjs/PSPrefix/main/img/output-combined.png) \n\n### What Gets Prefixed\n\nBy default, this module's cmdlets affect the following output streams:\n\n\\#| Name        | Write Cmdlet\n--|-------------|----------------\n1 | Success     | `Write-Output`\n2 | Error       | `Write-Error`\n3 | Warning     | `Write-Warning`\n4 | Verbose     | `Write-Verbose`\n5 | Debug       | `Write-Debug`\n6 | Information | `Write-Host`\n\nThe cmdlets do not affect the Progress stream.\n\nTo output objects (the Success stream) unaltered, use the `-PassThru` switch to\nexempt that stream from prefix behavior.\n\n```pwsh\nShow-Prefixed Foo -PassThru {\n    Write-Host   \"This is prefixed\"\n    Write-Object \"This is not prefixed\"\n}\n```\n\n![Output of the -PassThru parameter example above](https://raw.githubusercontent.com/sharpjs/PSPrefix/main/img/output-passthru.png) \n\n### The Clean Slate\n\nThe code between the `{` and `}` (the script block) runs in a new, clean\nPowerShell environment (runspace).  No state from the invoking script is\nvisible in the script block.  Specifically:\n\n- The current directory (location) is at its default value.\n- Built-in PowerShell variables have their default values.\n- No other variables are defined, except as shown below.\n- No modules are imported, except as shown below.\n- No profile scripts are run.\n\nTo pre-import modules for the script block to use, specify one or more modules\nvia the `-Module` parameter.\n\n```pwsh\nShow-Prefixed Foo -Module A, B {\n    # modules A and B are available here\n}\n```\n\nTo copy variable values from the invoking script into the script block, specify\none or more variables via the `-Variable` parameter.\n\n```pwsh\n$x = 1337\n$y =   42\n\nShow-Prefixed Foo -Variable x, y {\n    # $x and $y are visible here\n}\n```\n\nThe script block is free to import modules, define variables, and perform other\nsetup as needed.  Becuase the script block runs isolated in its own runspace,\nthe script block's state changes do not affect the state of the invoking\nscript.\n\n### Parallel Operations\n\nPSPrefix is designed to add clarity to the output of long-running, parallel\noperations.  The `Show-Elapsed` cmdlet provides relative time information.\nThe `Show-Prefixed` cmdlet can differentiate output from separate tasks.\nTogether, the cmdlets can help to detangle webs of intermingled output from\nmultiple threads.\n\nImagine this scenario that runs a command four times in parallel:\n\n```pwsh\n1..4 | ForEach-Object -Parallel {\n    Write-Host \"example command output\"\n}\n```\n\n![Output of the parallel example above: four identical lines of text.](https://raw.githubusercontent.com/sharpjs/PSPrefix/main/img/output-parallel-unprefixed.png) \n\nWhich command invocation produced which line of output?  It is impossible to\nknow.  PSPrefix removes the ambiguity:\n\n```pwsh\nShow-Elapsed {\n    $MyHost = Get-SynchronizedHost\n    1..4 | ForEach-Object -Parallel {\n        Show-Prefixed \"Task $_\" -CustomHost $using:MyHost {\n            Write-Host \"example command output\"\n        }\n    }\n}\n```\n\n![Output of the parallel example above: each line is prefixed by a task name.](https://raw.githubusercontent.com/sharpjs/PSPrefix/main/img/output-parallel.png) \n\nA trick is required when using the `Show-Elapsed` and `Show-Prefixed` cmdlets\nin parallel multithreaded scenarios.  The cmdlets work by routing output\nthrough custom `PSHost` objects, but that technique does not work within\n`ForEach-Object -Parallel` script blocks.  PSPrefix provides a pair of features\nto work around this limitation,\n\nFirst, PSPrefix provides a `Get-SynchronizedHost` cmdlet that returns a wrapper\nover the current `$Host` object.  The wrapper makes the host object safe to\nshare across threads.\n\nSecond, the `Show-Elapsed` and `Show-Prefixed` cmdlets have a `-CustomHost`\nparameter that accepts a host object to use instead of the current `$Host`\nobject.\n\nTo use a PSPrefix cmdlet within a `ForEach-Object -Parallel` script block, use\n`Get-SynchronizedHost` to obtain a thread-safe host object outside the parallel\nscript block.  Then pass the thread-safe host object inside the parallel script\nblock using the `-CustomHost` parameter and the `$using:` syntax, as shown in\nthe example above.\n\n\u003c!--\n  Copyright Subatomix Research Inc.\n  SPDX-License-Identifier: MIT\n--\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsharpjs%2Fpsprefix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsharpjs%2Fpsprefix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsharpjs%2Fpsprefix/lists"}