Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/insomnimus/ps-dotenv

A feature complete and unintrusive direnv for Powershell Core
https://github.com/insomnimus/ps-dotenv

csharp direnv dotenv dotnet module powershell

Last synced: about 2 months ago
JSON representation

A feature complete and unintrusive direnv for Powershell Core

Awesome Lists containing this project

README 

        
[direnv]: https://direnv.net/



# PS-Dotenv

`Dotenv` is a feature complete and straightforward [direnv][] alternative for Powershell Core.



It also exposes the parser as a separate project you can use in other code.



## Stability

Dotenv is stable and feature complete. the project is currently in maintain-only state. That means unless there's significant demand for a feature, only bug-fixes and other improvements will be added.



## Features

- Complete syntax support including multiline strings and string interpolation.

-	Works on any platform where Powershell Core runs.

-	Logging with configurable log levels.

-	Option to turn the module on and off on the fly.

-	Option to add/remove custom filenames for auto sourcing of env files.

-	A subset of bash-like parameter expansion: `$val`, `${val}`, `${val?error}`, `${val+replacement}` and `${val-default}`.

- Opt-in safe mode where files have to be explicitly allowd.

-	Smart loading and unloading env variables: you won't lose the previously set values upon unloading, the "replaced" values are remembered and kindly reset to their original values.

-	It just works the way you'd expect it to.



## Use Case

This module aims to provide the same functionality as [direnv][].



Add `Update-Dotenv` in your `Prompt` function and as you navigate directories, Dotenv will source the appropriate env files in the current directory and its parents.



## Performance

The parsing of the env files is done in `C#` with a hand-written parser.



Dotenv, when there are env files under $PWD or its parents, adds about 1-10 milliseconds to the prompt, which itself takes about 5-20 milliseconds (on my machine).

If no env files are detected, there's pretty much no overhead.



# Installation

You have 3 options:



## Via Scoop (recommended)

First add [my bucket](https://github.com/insomnimus/scoop-bucket) to scoop:



`scoop bucket add insomnia https://github.com/insomnimus/scoop-bucket`



Update scoop:



`scoop update`



Install the module:



`scoop install ps-dotenv`



## Download a Release Archive

Simply download the latest release from [the releases page](https://github.com/insomnimus/ps-dotenv/releases).



Download `Dotenv.zip`, extract and put the `Dotenv` directory under your `$PSModulePath` as with any other module.



## Build From Source

Make sure you have all the requirements installed:



-	`git`: To clone the repository.

-	`dotnet cli` with `dotnet 6.0` or above: To build the project.

-	`Powershell` version 6.0 or above: To run the build script.



To build the project, run the commands below.



```powershell

git clone https://github.com/insomnimus/ps-dotenv

cd ps-dotenv

git checkout main # This is sometimes required.

./build.ps1 -release

# Now import the module.

Import-Module ./build/Dotenv

```



# Usage

For the env files to be automatically sourced, you'll need to configure your prompt to let `Dotenv` know you possibly changed directories.



You don't need to check if the current directory changed or if there are files that must be loaded since `Dotenv` takes care of that for you by keeping its own state.

If you don't have a powershell profile setup yet, please read [this article from Microsoft](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_profiles?view=powershell-7.2) first.



> Important: Dotenv is disabled by default. You need to enable it with `Enable-Dotenv` in your powershell profile.



First, add this in your profile (don't forget to replace `C:\example\dotenv` with the actual path to the folder you built in above steps, or if Dotenv is in your module directory, replace the path with `Dotenv`):



```powershell

Import-Module C:\example\dotenv

Enable-Dotenv # this is important, by default the module is disabled

```



Depending on if you have a custom prompt follow one of the following steps:



### If you already have a customized prompt

You just have to add the following snippet inside your prompt function:



```powershell

# We check if the command exists to not cause errors.

if(Test-Path function:/Update-Dotenv) { Dotenv\Update-Dotenv }

```



### If you haven't customized your prompt

In your powershell profile, define a new prompt (the snippet below is the built-in prompt with dotenv enabled):



```powershell

function prompt {

	# Print the built-in prompt:

	$(if (Test-Path variable:/PSDebugContext) { '[DBG]: ' }

		else { '' }) + 'PS ' + $(Get-Location) +

	$(if ($NestedPromptLevel -ge 1) { '>>' }) + '> '



	# We check if the command exists to not cause any errors.

	if(Test-Path function:/Update-Dotenv) { Dotenv\Update-Dotenv }

}

```



## Documentation



-	[All in one page](documentation.md)

-	[Individual command docs](docs/)

-	[Syntax](syntax.md)



## Commands Overview

- `Read-Dotenv`: Parses an env file. 

- `Disable-Dotenv`: Disables the module without removing it from the session. 

- `Enable-Dotenv`: Enables the module back. 

- `Update-Dotenv`: Triggers the module to check for env files in the current and parent directories. 

- `Approve-DotenvDir`: Whitelists a directory for dotenv. 

- `Approve-DotenvFile`: Whitelists a particular env file for dotenv. 

- `Deny-DotenvFile`: Unauthorizes an env file. 

- `Register-DotenvName`: Adds a new name to the list of env file names this module will check for. 

- `Unregister-DotenvName`: Removes a name from the list of names this module will consider as an env file. 

- `Add-DotenvPattern`: Adds a glob pattern to the whitelist. 

- `Remove-DotenvPattern`: Removes a pattern from the dotenv whitelist.