-
Notifications
You must be signed in to change notification settings - Fork 3
/
readme.md-tpl
111 lines (79 loc) · 4.41 KB
/
readme.md-tpl
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
[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
Probing for and loading of `.env` files is I/O bound. The parsing itself takes very little time (less than a millisecond on my znver3 cpu).
# Installation
You have 3 options:
## (Windows) 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`
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 .NET SDK 8.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 necessary
./build.ps1 -release
# Now import the module.
Import-Module ./bin/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