Skip to content

Commit

Permalink
Merge pull request #4 from acaloiaro/add-v2-documentation
Browse files Browse the repository at this point in the history 
Add v2 documentation to README
  • Loading branch information
@acaloiaro
acaloiaro authored May 29, 2023
2 parents c8543f9 + bf6eca7 commit 35faf64
Showing 1 changed file with 108 additions and 33 deletions.
141 changes: 108 additions & 33 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,70 +1,148 @@
# env-sample-sync

A [pre-commit plugin](https://pre-commit.com/#install) that safely keeps `.env` files in sync with `env.sample`.
Automatically keep `.env` files in sync with `env.sample`

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.
---

For details on configuring and installing `pre-commit`, refer to https://pre-commit.com/#install
`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).

# Background
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.

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.
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.

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:
# Installation & Usage

`env-sample-sync` can be run in three ways:

1. Manually
2. As a native git-hook
3. As a [pre-commit plugin](https://pre-commit.com/#install) (a utility for organizing pre-commit hooks)

## Installation

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.


**Install from the releases page**

Download [the latest release](https://github.com/acaloiaro/env-sample-sync/releases/latest) and add it to your `$PATH`.

**Install with `go install`**

```bash
APPLICATION_SECRET=supersekrit
go install github.com/acaloiaro/env-sample-sync@latest
```

# I got this FOO from the detailed process documented at: http:://wiki.example.com/how_to_get_a_foo
FOO="My super secret value for foo"
## Running manually

`env-sample-sync` can be run with no arguments to use defaults.

**Sync `.env` with `env.sample`**

```bash
env-sample-sync
```

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.

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`:
**With a non-default `.env` and `env.sample` location**

```bash
APPLICATION_SECRET=<APPLICATION_SECRET>
env-sample-sync --env-file=.env-file-name --sample-file=env-sample-file-name
```

# I got this FOO from the detailed process documented at: http:://wiki.example.com/how_to_get_a_foo
FOO=<FOO>
**Provide example values for variables**

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.

Add custom examples for variables `FOO` and `BAR`.

```bash
env-sample-sync --example=FOO="must be a valid UUID" --example=BAR="bars must be a positive integer"
```

The above invocation yields the following `env.sample`


```bash
FOO=must be a valid UUID

BAR=bars must be a positive integer
```

## Running as a native git-hook

To add `env-sample-sync` as a pre-commit git hook in a git repository, run:

```bash
env-sample-sync install
```

It's even possible to provide default/example values for for every environment variables with the `--example` [argument](#arguments).
This installs `env-sample-sync` as a pre-commit git hook with default arguments.

The `install` command supports all [command flags](#command-flags).

If you need to change `env-sample-sync` flags, simply run `env-sample-sync install` again with the desired flags.

# Usage
## Running as a pre-commit plugin

Add this hook to your repository as follows:
This utility can be used as a [pre-commit plugin](https://pre-commit.com/#install)

## Add configuration
```bash
cat <<EOF > .pre-commit-config.yaml
repos:
- repo: https://github.com/acaloiaro/pre-commit-env-sample-sync.git
- repo: https://github.com/acaloiaro/env-sample-sync.git
rev: v2.1.0
hooks:
- id: env-sample-sync
EOF
pre-commit install
git add .pre-commit-config.yaml
```

See [pre-commit configuration examples](#pre-commit-configuration-examples) for additional pre-commit documentation.

# Background

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.

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:

```bash
APPLICATION_SECRET=supersekrit

# I got this FOO from the detailed process documented at: http:://wiki.example.com/how_to_get_a_foo
FOO="My super secret value for foo"
```

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.

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`:

```bash
APPLICATION_SECRET=<APPLICATION_SECRET>

# I got this FOO from the detailed process documented at: http:://wiki.example.com/how_to_get_a_foo
FOO=<FOO>
```

## Hook arguments
It's even possible to provide default/example values for every environment variables with the `--example` [flag](#command-flags).

This plugin accepts the following arguments
## Command Flags

| Name | Description | Example | Default |
| -------------------- | --------------------------------------------------------- | --------------------------------------------------------- | ----------------------------- |
| `-e`/`--env-file` | The name of the environment file in the repository | `--env-file=.secrets` | `--env-file=.env` |
| `-s`/`--sample-file` | The name of the sample environment file in the repository | `--sample-file=secrets.example` | `--sample-file=env.sample` |
| `-x`/`--example` | Provide examples for specific environment variables | `--example=FOO="Example FOO" --example=BAR="Example BAR"` | `--example=<ENV_VAR_NAME>` |
| Name | Description | Example | Default |
| -------------------- | --------------------------------------------------- | --------------------------------------------------------- | ----------------------------- |
| `-e`/`--env-file` | The name of the environment file | `--env-file=.secrets` | `--env-file=.env` |
| `-s`/`--sample-file` | The name of the sample environment file | `--sample-file=secrets.example` | `--sample-file=env.sample` |
| `-x`/`--example` | Provide examples for specific environment variables | `--example=FOO="Example FOO" --example=BAR="Example BAR"` | `--example=VAR=<VAR>` |

## Configuration Examples
## Pre-commit Configuration Examples

### Default configuration

```yml
repos:
- repo: https://github.com/acaloiaro/pre-commit-env-sample-sync.git
- repo: https://github.com/acaloiaro/env-sample-sync.git
rev: v2.1.0
hooks:
- id: env-sample-sync
Expand All @@ -74,7 +152,7 @@ repos:

```yml
repos:
- repo: https://github.com/acaloiaro/pre-commit-env-sample-sync.git
- repo: https://github.com/acaloiaro/env-sample-sync.git
rev: v2.1.0
hooks:
- id: env-sample-sync
Expand All @@ -85,10 +163,9 @@ repos:

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.

`.pre-commit-config.yml`
```yml
repos:
- repo: https://github.com/acaloiaro/pre-commit-env-sample-sync.git
- repo: https://github.com/acaloiaro/env-sample-sync.git
rev: v2.1.0
hooks:
- id: env-sample-sync
Expand All @@ -111,7 +188,5 @@ BAR=You can fetch bars from https://example.com/bars

# Limitations

Currently, this hook only supports `.env` files with environment variables of the form `VAR_NAME=VAR_VALUE`.

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).
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 comments on commit 35faf64

Please sign in to comment.