You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A [pre-commit plugin](https://pre-commit.com/#install) that safely keeps `.env` files in sync with `env.sample`.
3
+
Automatically keep `.env` files in sync with `env.sample`
4
4
5
-
It checks whether the local repository has an `.env` file and if one exists, it is scrubbed of secrets/values and made available as `env.sample`. This ensures that all application environment variables are safely and automatically documented without leaking secrets.
5
+
---
6
6
7
-
For details on configuring and installing `pre-commit`, refer to https://pre-commit.com/#install
7
+
`env-sample-sync` checks whether the local repository contains an `.env` file (configurable), scrubs it of secrets/values, and makes the scrubbed version available as `env.sample` (configurable).
8
8
9
-
# Background
9
+
This process can be run manually, or automatically as a git-hook, ensuring that all application environment variables are safely and automatically documented without leaking secrets.
10
10
11
-
It's important to document the environment variables required to run applications, both in production and development. A great way to do so is with `env.sample` files.
11
+
Crucially, `env-sample-sync` allows comments in `env` files, which are carried over to `env.sample`. This lets developers add thorough environment variable documentation to source control.
12
12
13
-
For example, let's say you're adding a new feature to your application and it requires the variable `FOO` to be set. While you're developing locally, you likely have a `.env` file that looks something like:
13
+
# Installation & Usage
14
+
15
+
`env-sample-sync` can be run in three ways:
16
+
17
+
1. Manually
18
+
2. As a native git-hook
19
+
3. As a [pre-commit plugin](https://pre-commit.com/#install) (a utility for organizing pre-commit hooks)
20
+
21
+
## Installation
22
+
23
+
Installation is required to run `env-sample-sync` manually, or as a native git hook. See [pre-commit configuration](#runing-as-a-pre-commit-plugin) for pre-commit usage.
24
+
25
+
26
+
**Install from the releases page**
27
+
28
+
Download [the latest release](https://github.com/acaloiaro/env-sample-sync/releases/latest) and add it to your `$PATH`.
29
+
30
+
**Install with `go install`**
14
31
15
32
```bash
16
-
APPLICATION_SECRET=supersekrit
33
+
go install github.com/acaloiaro/env-sample-sync@latest
34
+
```
17
35
18
-
# I got this FOO from the detailed process documented at: http:://wiki.example.com/how_to_get_a_foo
19
-
FOO="My super secret value for foo"
36
+
## Running manually
37
+
38
+
`env-sample-sync` can be run with no arguments to use defaults.
39
+
40
+
**Sync `.env` with `env.sample`**
41
+
42
+
```bash
43
+
env-sample-sync
20
44
```
21
45
22
-
Working on large teams, it's common to share these `.env` files somewhere secure where all developers have access to them. Retrieval is often integrated into application startup and/or bootstrap processes.
23
46
24
-
But working on open source projects or teams with less trust and less shared infrastructure, it's more common to share an `env.sample`. This pre-commit plugin automatically keeps the sample file in sync with `.env`, so you don't have to. Your `.env` file stays the same, and is automatically converted to the following `env.sample`:
47
+
**With a non-default `.env`and `env.sample` location**
# I got this FOO from the detailed process documented at: http:://wiki.example.com/how_to_get_a_foo
30
-
FOO=<FOO>
53
+
**Provide example values for variables**
54
+
55
+
By default, `env-sample-sync` uses the name of environment variables in `<brackets>` as example values in `env.sample`, e.g. `FOO=secret value` is replaced with `FOO=<FOO>`. This behavior is customizable wit the `--example` flag.
56
+
57
+
Add custom examples for variables `FOO` and `BAR`.
58
+
59
+
```bash
60
+
env-sample-sync --example=FOO="must be a valid UUID" --example=BAR="bars must be a positive integer"
61
+
```
62
+
63
+
The above invocation yields the following `env.sample`
64
+
65
+
66
+
```bash
67
+
FOO=must be a valid UUID
68
+
69
+
BAR=bars must be a positive integer
70
+
```
71
+
72
+
## Running as a native git-hook
73
+
74
+
To add `env-sample-sync` as a pre-commit git hook in a git repository, run:
75
+
76
+
```bash
77
+
env-sample-sync install
31
78
```
32
79
33
-
It's even possible to provide default/example values for for every environment variables with the `--example`[argument](#arguments).
80
+
This installs `env-sample-sync` as a pre-commit git hook with default arguments.
81
+
82
+
The `install` command supports all [command flags](#command-flags).
83
+
84
+
If you need to change `env-sample-sync` flags, simply run `env-sample-sync install` again with the desired flags.
34
85
35
-
#Usage
86
+
## Running as a pre-commit plugin
36
87
37
-
Add this hook to your repository as follows:
88
+
This utility can be used as a [pre-commit plugin](https://pre-commit.com/#install)
See [pre-commit configuration examples](#pre-commit-configuration-examples) for additional pre-commit documentation.
104
+
105
+
# Background
106
+
107
+
It's important to document the environment variables required to run applications, both in production and development. A great way to do so is with `env.sample` files, but sample files tend to get out of date very quickly.
108
+
109
+
For example, let's say you're adding a new feature to your application and it requires the variable `FOO` to be set. While you're developing locally, you likely have a `.env` file that looks something like:
110
+
111
+
```bash
112
+
APPLICATION_SECRET=supersekrit
113
+
114
+
# I got this FOO from the detailed process documented at: http:://wiki.example.com/how_to_get_a_foo
115
+
FOO="My super secret value for foo"
116
+
```
117
+
118
+
Working on large teams, it's common to share these `.env` files somewhere secure where all developers have access to them. Retrieval is often integrated into application startup and/or bootstrap processes.
119
+
120
+
But working on open source projects or teams with less trust and less shared infrastructure, it's more common to share an `env.sample`. `env-sample-sync` automatically keeps the sample file in sync with `.env`, so you don't have to. Your `.env` file stays the same, and is automatically converted to the following `env.sample`:
121
+
122
+
```bash
123
+
APPLICATION_SECRET=<APPLICATION_SECRET>
124
+
125
+
# I got this FOO from the detailed process documented at: http:://wiki.example.com/how_to_get_a_foo
126
+
FOO=<FOO>
49
127
```
50
128
51
-
## Hook arguments
129
+
It's even possible to provide default/example values for every environment variables with the `--example`[flag](#command-flags).
|`-e`/`--env-file`| The name of the environment file in the repository|`--env-file=.secrets`|`--env-file=.env`|
58
-
|`-s`/`--sample-file`| The name of the sample environment file in the repository|`--sample-file=secrets.example`|`--sample-file=env.sample`|
59
-
|`-x`/`--example`| Provide examples for specific environment variables |`--example=FOO="Example FOO" --example=BAR="Example BAR"`|`--example=<ENV_VAR_NAME>`|
|`-e`/`--env-file`| The name of the environment file |`--env-file=.secrets`|`--env-file=.env`|
136
+
|`-s`/`--sample-file`| The name of the sample environment file |`--sample-file=secrets.example`|`--sample-file=env.sample`|
137
+
|`-x`/`--example`| Provide examples for specific environment variables |`--example=FOO="Example FOO" --example=BAR="Example BAR"`|`--example=VAR=<VAR>`|
Sometimes environment variables need to conform to specific formats and it's necessary to provide better documentation. For this reason, environment variable examples may be provided in lieu of the default behavior, which is to use the environment variable name surrounded by `<brackets like this>` in sample files.
@@ -111,7 +188,5 @@ BAR=You can fetch bars from https://example.com/bars
111
188
112
189
# Limitations
113
190
114
-
Currently, this hook only supports `.env` files with environment variables of the form `VAR_NAME=VAR_VALUE`.
115
-
116
-
While this project does not directly support [Direnv](https://direnv.net/)-style `.envrc` files, direnv users are free to use its [`dotenv` std lib function](https://direnv.net/man/direnv-stdlib.1.html#codedotenv-ltdotenvpathgtcode).
191
+
While this project does not directly support [Direnv](https://direnv.net/)-style `.envrc` files, direnv users are free to use its [`dotenv` std lib function](https://direnv.net/man/direnv-stdlib.1.html#codedotenv-ltdotenvpathgtcode) with this utility.
0 commit comments