{"id":13596611,"url":"https://github.com/RamblingCookieMonster/PSDepend","last_synced_at":"2025-04-09T16:33:19.353Z","repository":{"id":10170526,"uuid":"64519238","full_name":"RamblingCookieMonster/PSDepend","owner":"RamblingCookieMonster","description":"PowerShell Dependency Handler","archived":false,"fork":false,"pushed_at":"2023-09-07T15:52:12.000Z","size":449,"stargazers_count":273,"open_issues_count":55,"forks_count":73,"subscribers_count":21,"default_branch":"master","last_synced_at":"2024-05-23T03:17:57.310Z","etag":null,"topics":["build","build-pipelines","ci-cd","dependency-manager","packages","powershell","powershell-modules"],"latest_commit_sha":null,"homepage":null,"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/RamblingCookieMonster.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":["ramblingcookiemonster"]}},"created_at":"2016-07-30T01:12:40.000Z","updated_at":"2024-05-03T06:43:46.000Z","dependencies_parsed_at":"2024-01-14T04:45:30.106Z","dependency_job_id":"51d9a0df-f208-4d22-8869-9b4821ba224c","html_url":"https://github.com/RamblingCookieMonster/PSDepend","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RamblingCookieMonster%2FPSDepend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RamblingCookieMonster%2FPSDepend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RamblingCookieMonster%2FPSDepend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RamblingCookieMonster%2FPSDepend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RamblingCookieMonster","download_url":"https://codeload.github.com/RamblingCookieMonster/PSDepend/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248068013,"owners_count":21042402,"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":["build","build-pipelines","ci-cd","dependency-manager","packages","powershell","powershell-modules"],"created_at":"2024-08-01T16:02:35.862Z","updated_at":"2025-04-09T16:33:14.345Z","avatar_url":"https://github.com/RamblingCookieMonster.png","language":"PowerShell","funding_links":["https://github.com/sponsors/ramblingcookiemonster"],"categories":["PowerShell"],"sub_categories":[],"readme":"[![Build status](https://ci.appveyor.com/api/projects/status/4mwhsx9pkfpc1j48/branch/master?svg=true)](https://ci.appveyor.com/project/RamblingCookieMonster/psdepend/branch/master)\n\nPSDepend\n========\n\nThis is a simple PowerShell dependency handler.  You might loosely compare it to `bundle install` in the Ruby world or `pip install -r requirements.txt` in the Python world.\n\nPSDepend allows you to write simple requirements.psd1 files that describe what dependencies you need, which you can invoke with `Invoke-PSDepend`\n\n**WARNING**:\n\n* Minimal testing.  This is in my backlog, but PRs would be welcome!\n* This borrows quite heavily from PSDeploy.  There may be leftover components that haven't been adapted, have been improperly adapted, or shouldn't have been adapted\n* Would love ideas, feedback, pull requests, etc., but if you rely on this, consider pinning a specific version to avoid hitting breaking changes.\n\n## Getting Started\n\n### Installing PSDepend\n\n```powershell\n# PowerShell 5\nInstall-Module PSDepend\n\n# PowerShell 3 or 4, curl|bash bootstrap. Read before running something like this : )\niex (new-object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/RamblingCookieMonster/PSDepend/master/Examples/Install-PSDepend.ps1')\n\n# Git\n    # Download the repository\n    # Unblock the zip\n    # Extract the PSDepend folder to a module path (e.g. $env:USERPROFILE\\Documents\\WindowsPowerShell\\Modules\\)\n\n# Import and start exploring\nImport-Module PSDepend\nGet-Command -Module PSDepend\nGet-Help about_PSDepend\n```\n\n### Example Scenarios\n\nIn-depth:\n\n* [Creating a virtual-environment-light](/Examples/VirtualEnvironment.md)\n* [Handling module dependencies](/Examples/ModuleDependencies.md)\n\nRecipes:\n\n* [How Do I...](/Examples/HowDoI.md)\n\n## Defining Dependencies\n\nStore dependencies in a PowerShell data file, and use *.depend.psd1 or requirements.psd1 to allow Invoke-PSDepend to find your files for you.\n\nWhat does a dependency file look like?\n\n### Simple syntax\n\nHere's the simplest syntax.  If this meets your needs, you can stop here:\n\n```powershell\n@{\n    psake        = 'latest'\n    Pester       = 'latest'\n    BuildHelpers = '0.0.20'  # I don't trust this Warren guy...\n    PSDeploy     = '0.1.21'  # Maybe pin the version in case he breaks this...\n\n    'RamblingCookieMonster/PowerShell' = 'master'\n}\n```\n\nAnd what PSDepend sees:\n\n```\nDependencyName                   DependencyType  Version Tags\n--------------                   --------------  ------- ----\npsake                            PSGalleryModule latest\nBuildHelpers                     PSGalleryModule 0.0.20\nPester                           PSGalleryModule latest\nRamblingCookieMonster/PowerShell GitHub          master\nPSDeploy                         PSGalleryModule 0.1.21\n```\n\nThere's a bit more behind the scenes - we assume you want PSGalleryModules or GitHub repos unless you specify otherwise, and we hide a few dependency properties.\n\nWe can also indicate the dependency type more explicitly if desired:\n\n```powershell\n@{\n    'PSGalleryModule::InvokeBuild' = 'latest'\n    'GitHub::RamblingCookieMonster/PSNeo4j' = 'master'\n}\n```\n\n### Flexible syntax\n\nWhat else can we put in a dependency?  Here's an example using a more flexible syntax.  You can mix and match.\n\n```powershell\n@{\n    psdeploy = 'latest'\n\n    buildhelpers_0_0_20 = @{\n        Name = 'buildhelpers'\n        DependencyType = 'PSGalleryModule'\n        Parameters = @{\n            Repository = 'PSGallery'\n            SkipPublisherCheck = $true\n        }\n        Version = '0.0.20'\n        Tags = 'prod', 'test'\n        PreScripts = 'C:\\RunThisFirst.ps1'\n        DependsOn = 'some_task'\n    }\n\n    some_task = @{\n        DependencyType = 'task'\n        Target = 'C:\\RunThisFirst.ps1'\n        DependsOn = 'nuget'\n    }\n\n    nuget = @{\n        DependencyType = 'FileDownload'\n        Source = 'https://dist.nuget.org/win-x86-commandline/latest/nuget.exe'\n        Target = 'C:\\nuget.exe'\n    }\n}\n```\n\nThis example illustrates using a few different dependency types, using DependsOn to sort things (e.g. some_task runs after nuget), tags, and other options.\n\nYou can inspect the full output as needed.  For example:\n\n```powershell\n# List the dependencies, get the third item, show all props\n$Dependency = Get-Dependency \\\\Path\\To\\complex.depend.ps1\n$Dependency[2] | Select *\n```\n\n```\nDependencyFile : \\\\Path\\To\\complex.depend.psd1\nDependencyName : buildhelpers_0_0_20\nDependencyType : PSGalleryModule\nName           : buildhelpers\nVersion        : 0.0.20\nParameters     : {Repository,SkipPublisherCheck}\nSource         :\nTarget         :\nAddToPath      :\nTags           : {prod, test}\nDependsOn      : some_task\nPreScripts     : C:\\RunThisFirst.ps1\nPostScripts    :\nRaw            : {Version, Name, Tags, DependsOn...}\n```\n\nNote that we replace certain strings in Target and Source fields:\n\n* $PWD (or .) refer to the current path\n* $ENV:USERPROFILE, $ENV:TEMP, $ENV:ProgramData, $ENV:APPDATA\n* Variables need to be in single quotes or the $ needs to be escaped.  We replace the raw strings with the values for you. This will not work: Target = \"$PWD\\dependencies\".  This will: Target = '$PWD\\dependencies'\n* If you call Invoke-PSDepend -Target $Something, we override any value for target\n* Thanks to Mike Walker for the idea!\n\n### Repository Credentials\n\nIf you are using a PowerShell module repository that requires authentication then add those to your dependency. When working with credentials there are two parts we need to consider:\n\n* Credential property of our dependency.\n* Credentials parameter for Invoke-PSDepend.\n\n```powershell\n@{\n    psdeploy = 'latest'\n\n    buildhelpers_0_0_20 = @{\n        Name = 'buildhelpers'\n        DependencyType = 'PSGalleryModule'\n        Parameters = @{\n            Repository = 'PSGallery'\n            SkipPublisherCheck = $true\n        }\n        Version = '0.0.20'\n        Credential = 'must_match'\n    }\n}\n```\n\nNow create a `PSCredential` object with the credentials to access the repository and run it:\n\n```powershell\nInvoke-PSDepend -Path C:\\requirements.psd1 -Credentials @{ 'must_match' = $creds }\n```\n\nMake sure whatever you use as `must_match` is the same in the dependency as it is in the hashtable you pass to the Credentials parameter.\n\n## Exploring and Getting Help\n\nEach DependencyType - PSGalleryModule, FileDownload, Task, etc. - might treat these standard properties differently, and may include their own Parameters.  For example, in the BuildHelpers node above, we specified a Repository and SkipPublisherCheck parameters.\n\nHow do we find out what these mean?  First things first, let's look at what DependencyTypes we have available:\n\n```powershell\nGet-PSDependType\n```\n\n```\nDependencyType  Description                                                 DependencyScript\n--------------  -----------                                                 ----------------\nPSGalleryModule Install a PowerShell module from the PowerShell Gallery.    C:\\...\\PSDepend\\PSDepen...\nTask            Support dependencies by handling simple tasks.              C:\\...\\PSDepend\\PSDepen...\nNoop            Display parameters that a depends script would receive...   C:\\...\\PSDepend\\PSDepen...\nFileDownload    Download a file                                             C:\\...\\PSDepend\\PSDepen...\n```\n\nNow that we know what types are available, we can read the comment-based help.  Hopefully the author took their time to write this:\n\n```PowerShell\nGet-PSDependType -DependencyType PSGalleryModule -ShowHelp\n```\n\n```\n...\nDESCRIPTION\n    Installs a module from a PowerShell repository like the PowerShell Gallery.\n\n    Relevant Dependency metadata:\n        Name: The name for this module\n        Version: Used to identify existing installs meeting this criteria, and as RequiredVersion for installation.  Defaults to 'latest'\n        Target: Used as 'Scope' for Install-Module.  If this is a path, we use Save-Module with this path.  Defaults to 'AllUsers'\n\nPARAMETERS\n...\n    -Repository \u003cString\u003e\n        PSRepository to download from.  Defaults to PSGallery\n    -SkipPublisherCheck \u003cSwitch\u003e\n        Bypass the catalog signing check.  Defaults to $false\n```\n\nIn this example, we see how PSGalleryModule treats the Name, Version, and Target in a depend.psd1, and we see Parameter's specific to this DependencyType, 'Repository' and 'SkipPublisherCheck'\n\nFinally, we have a few about topics, and individual commands have built in help:\n\n```\nGet-Help about_PSDepend\nGet-Help about_PSDepend_Definitions\nGet-Help Get-Dependency -Full\n```\n\n## Extending PSDepend\n\nPSDepend is extensible.  To create a new dependency type:\n\n* Pick a name.  We'll use `Nothing` as an example\n* Create `DependencyType.ps1` (substituting in your name, e.g. `Nothing.ps1`) in the [PSDependScripts folder](https://github.com/RamblingCookieMonster/PSDepend/tree/master/PSDepend/PSDependScripts)\n* Your `DependencyType.ps1` (`Nothing.ps1` in this example) should...\n  * Have comment based help\n  * Include details on how you use Dependency metadata.  For example, in [Git.ps1](https://github.com/RamblingCookieMonster/PSDepend/blob/master/PSDepend/PSDependScripts/Git.ps1), `Version` is used in git checkout\n  * Include a PSDependAction parameter that takes `Install`, `Test`, `Import`, or a subset of these.  [Example parameter declaration](https://github.com/RamblingCookieMonster/PSDepend/blob/master/PSDepend/PSDependScripts/PSGalleryModule.ps1#L40)\n  * Depending on which PSDependAction is specified by the user, your script should `install`, `test` (return true or false depending on whether the dependency exists - sometimes this is impossible to check), and `import` (import the dependency - if appropriate, this might import a module or dot source code, for example)\n* Add your new dependency type to [PSDependMap.psd1](https://github.com/RamblingCookieMonster/PSDepend/blob/master/PSDepend/PSDependMap.psd1)\n\nSo!  In our example, we would create `PSDepend\\PSDependScripts\\Nothing.ps1`, with the following code:\n\n```powershell\n\u003c#\n    .SYNOPSIS\n        Example Dependency\n\n    .DESCRIPTION\n        Example Dependency\n\n        Relevant Dependency metadata:\n            Version: Used for nonsense output\n\n    .PARAMETER Dependency\n        Dependency to process\n\n    .PARAMETER StringParameter\n        An example parameter that does nothing\n\n    .PARAMETER PSDependAction\n        Test, Install, or Import the dependency.  Defaults to Install\n\n        Test: Return true or false on whether the dependency is in place\n        Install: Install the dependency\n        Import: Import the dependency\n#\u003e\n[cmdletbinding()]\nparam (\n    [PSTypeName('PSDepend.Dependency')]\n    [psobject[]]$Dependency,\n\n    [ValidateSet('Test', 'Install', 'Import')]\n    [string[]]$PSDependAction = @('Install'),\n\n    [string]$StringParameter\n)\n\n$Output = [PSCustomobject]@{\n    DependencyName = $Dependency.DependencyName\n    Status = \"Invoking $PSDependAction action\"\n    BoundParameters = $PSBoundParameters.Keys\n    Message = \"Version [$Version]\"\n}\n\n# Notice that we end the script if we're testing.\nif( $PSDependAction -Contains 'Test' )\n{\n    Write-Verbose $Output\n    return $true\n}\n\n$Output\n```\n\nFinally, we'll add an entry to `PSDependMap.psd1`:\n\n```powershell\n    Nothing = @{\n        Script= 'Nothing.ps1'\n        Description = 'Example dependency'\n    }\n```\n\nLastly, we'll define a requirements.psd1 using this dependency:\n\n```powershell\n@{\n    ExampleDependency = @{\n        DependencyType = 'Nothing'\n        Version = 1\n        Parameters = @{\n            StringParameter = 'A thing'\n        }\n    }\n}\n```\n\nFinally, run it!\n\n```powershell\nInvoke-PSDepend -Path C:\\requirements.psd1 -Test -Quiet\n```\n\n`True`\n\n```powershell\nInvoke-PSDepend -Path C:\\requirements.psd1\n```\n\n```\nDependencyName    Status                  BoundParameters                               Message\n--------------    ------                  ---------------                               -------\nExampleDependency Invoking Install action {StringParameter, PSDependAction, Dependency} Version [1]\n```\n\n```powershell\nInvoke-PSDepend -Path C:\\requirements.psd1 -Import\n```\n\n```\nDependencyName    Status                 BoundParameters                               Message\n--------------    ------                 ---------------                               -------\nExampleDependency Invoking Import action {StringParameter, PSDependAction, Dependency} Version [1]\n```\n\n## Notes\n\nMajor props to Michael Willis for the idea - check out his [PSRequire](https://github.com/Xainey/PSRequire), a similar but more feature-full solution.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRamblingCookieMonster%2FPSDepend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FRamblingCookieMonster%2FPSDepend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRamblingCookieMonster%2FPSDepend/lists"}