me/ess
1
0
Fork 0
mirror of https://github.com/acaloiaro/ess synced 2026-07-21 18:29:08 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Rename project to 'ess'

Browse source 
`env-sample-sync` is tedious to type
This commit is contained in:
Adriano Caloiaro 2023-09-26 07:51:15 -06:00
parent 4a0a3c14d4
commit 5bc9d352e9
No known key found for this signature in database
GPG key ID: 920633857147D83D
6 changed files with 56 additions and 49 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
.pre-commit-hooks.yaml
View file

@ -1,8 +1,8 @@
- id: env-sample-sync
name: env-sample-sync env sample file synchronizer
- id: ess
name: ess - env sample sync
description: Automatically and safely synchronize .env files with env.sample
language: golang
entry: env-sample-sync
entry: ess
always_run: true
pass_filenames: false
stages: [commit]

56
README.md
View file

@ -1,4 +1,4 @@
# env-sample-sync
# ess (env sample sync)
[![Gitter chat](https://badges.gitter.im/gitterHQ/gitter.png)](https://app.gitter.im/#/room/#env-sample-sync-dev:gitter.im)
@ -6,18 +6,18 @@ Automatically keep `.env` files in sync with `env.sample`
---
`env-sample-sync` checks whether the local repository contains an `.env` file (configurable), scrubs it of secrets/
`ess` 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).
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.
Crucially, `env-sample-sync` allows comments in `env` files, which are carried over to `env.sample`. This lets
Crucially, `ess` allows comments in `env` files, which are carried over to `env.sample`. This lets
developers add thorough environment variable documentation to source control.
# Installation & Usage
`env-sample-sync` can be run in three ways:
`ess` can be run in three ways:
1. Manually
2. As a native git-hook
@ -25,18 +25,18 @@ developers add thorough environment variable documentation to source control.
## Installation
Installation is required to run `env-sample-sync` manually, or as a native git hook. See [pre-commit configuration]
Installation is required to run `ess` manually, or as a native git hook. See [pre-commit configuration]
(#running-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`.
Download [the latest release](https://github.com/acaloiaro/ess/releases/latest) and add it to your `$PATH`.
**Install with `go install`**
```bash
go install github.com/acaloiaro/env-sample-sync@latest
go install github.com/acaloiaro/ess@latest
```
**Nix Flake**
@ -45,8 +45,8 @@ This application may be added as a flake input
**flake.nix**
```nix
inputs.env-sample-sync = {
url = "github:acaloiaro/env-sample-sync";
inputs.ess = {
url = "github:acaloiaro/ess";
inputs.nixpkgs.follows = "nixpkgs";
};
```
@ -55,7 +55,7 @@ inputs.env-sample-sync = {
```nix
users.users.<USERNAME>.packages = [
...
inputs.env-sample-sync.packages.${system}.default
inputs.ess.packages.${system}.default
];
```
@ -66,30 +66,30 @@ nix run github:acaloiaro/di-tui -- --username <USERNAME> --password <PASSWORD>
## Running manually
`env-sample-sync` can be run with no arguments to use defaults.
`ess` can be run with no arguments to use defaults.
**Sync `.env` with `env.sample`**
```bash
env-sample-sync
ess
```
**With a non-default `.env` and `env.sample` location**
```bash
env-sample-sync --env-file=.env-file-name --sample-file=env-sample-file-name
ess --env-file=.env-file-name --sample-file=env-sample-file-name
```
**Provide example values for variables**
By default, `env-sample-sync` uses the name of environment variables in `<brackets>` as example values in `env.sample`,
By default, `ess` 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"
ess --example=FOO="must be a valid UUID" --example=BAR="bars must be a positive integer"
```
The above invocation yields the following `env.sample`
@ -103,17 +103,17 @@ 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:
To add `ess` as a pre-commit git hook in a git repository, run:
```bash
env-sample-sync install
ess install
```
This installs `env-sample-sync` as a pre-commit git hook with default arguments.
This installs `ess` 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 and
If you need to change `ess` flags, simply run `ess install` again with the desired flags and
choose the overwrite [o] option when prompted what to do with the existing pre-commit hook.
## Running as a pre-commit plugin
@ -124,10 +124,10 @@ This utility can be used as a [pre-commit plugin](https://pre-commit.com/#instal
```bash
cat <<EOF > .pre-commit-config.yaml
repos:
- repo: https://github.com/acaloiaro/env-sample-sync.git
- repo: https://github.com/acaloiaro/ess.git
rev: v2.5.0
hooks:
- id: env-sample-sync
- id: ess
EOF
pre-commit install
git add .pre-commit-config.yaml
@ -154,7 +154,7 @@ Working on large teams, it's common to share these `.env` files somewhere secure
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
an `env.sample`. `ess` 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
@ -180,20 +180,20 @@ It's even possible to provide default/example values for every environment varia
```yml
repos:
- repo: https://github.com/acaloiaro/env-sample-sync.git
- repo: https://github.com/acaloiaro/ess.git
rev: v2.5.0
hooks:
- id: env-sample-sync
- id: ess
```
### Customize `.env` and `env.sample` paths
```yml
repos:
- repo: https://github.com/acaloiaro/env-sample-sync.git
- repo: https://github.com/acaloiaro/ess.git
rev: v2.5.0
hooks:
- id: env-sample-sync
- id: ess
args: ['--env-file=.env_file', '--sample-file=env_file.sample']
```
@ -205,10 +205,10 @@ environment variable name surrounded by `<brackets like this>` in sample files.
```yml
repos:
- repo: https://github.com/acaloiaro/env-sample-sync.git
- repo: https://github.com/acaloiaro/ess.git
rev: v2.5.0
hooks:
- id: env-sample-sync
- id: ess
args: [--example=FOO="Provide your foo here", --example=BAR="You can fetch bars from https://example.com/bars"]
```

4
flake.nix
View file

@ -32,7 +32,7 @@
in
{
default = pkgs.buildGoModule {
pname = "env-sample-sync";
pname = "ess";
inherit version;
# In 'nix develop', we don't need a copy of the source tree
# in the Nix store.
@ -60,7 +60,7 @@
apps = forAllSystems (system: {
default = {
type = "app";
program = "${self.packages.${system}.default}/bin/env-sample-sync";
program = "${self.packages.${system}.default}/bin/ess";
};
});
};

7
go.mod
View file

@ -1,5 +1,8 @@
module github.com/acaloiaro/env-sample-sync
module github.com/acaloiaro/ess
go 1.20
require github.com/hashicorp/go-envparse v0.1.0 // indirect
require (
github.com/hashicorp/go-envparse v0.1.0 // indirect
github.com/kardolus/chatgpt-cli v1.3.1 // indirect
)

2
go.sum
View file

@ -1,2 +1,4 @@
github.com/hashicorp/go-envparse v0.1.0 h1:bE++6bhIsNCPLvgDZkYqo3nA+/PFI51pkrHdmPSDFPY=
github.com/hashicorp/go-envparse v0.1.0/go.mod h1:OHheN1GoygLlAkTlXLXvAdnXdZxy8JUweQ1rAXx1xnc=
github.com/kardolus/chatgpt-cli v1.3.1 h1:6+P/ajo5GoPzNgCIuFbJ4UUdU3Gmg2BQc3E+ogPptXQ=
github.com/kardolus/chatgpt-cli v1.3.1/go.mod h1:PdFwHa368+zVfR7k25EVXvmojBCcwn0zsmLLGHolpb8=

30
main.go
View file

@ -40,9 +40,11 @@ func (e exampleFlag) Set(value string) (err error) {
return nil
}
var envFileFlag string
var sampleFileFlag string
var examplesFlag = make(exampleFlag)
var (
envFileFlag string
sampleFileFlag string
examplesFlag = make(exampleFlag)
)
func init() {
flag.StringVar(&envFileFlag, "env-file", ".env", "-env-file=.env_file")
@ -84,7 +86,7 @@ func main() {
os.Exit(1)
}
default:
fmt.Printf("env-sample-sync: unknown command '%s'\n\n", command)
fmt.Printf("ess: unknown command '%s'\n\n", command)
flag.Usage()
}
}
@ -206,16 +208,16 @@ func gitDirPaths() (projectPath, gitDir string) {
}
var preCommitScriptTemplate = `{{if .Appending}}{{ .OldPreCommitScript }}
# Below code generated by env-sample-sync https://github.com/acaloiaro/env-sample-sync
# Below code generated by ess https://github.com/acaloiaro/ess
{{else}}#!/usr/bin/env bash
# File generated by env-sample-sync https://github.com/acaloiaro/env-sample-sync
# File generated by ess https://github.com/acaloiaro/ess
{{end}}ARGS=({{ .Args }})
exec $(dirname -- "${BASH_SOURCE[0]}")/{{ .PreCommitHooksDir }}/0-env-sample-sync "${ARGS[@]}"
exec $(dirname -- "${BASH_SOURCE[0]}")/{{ .PreCommitHooksDir }}/0-ess "${ARGS[@]}"
`
// installHook installs the env-sample-sync git hook to 'dir'
// installHook installs the ess git hook to 'dir'
func installHook(gitDirPath string) (err error) {
hooksScriptDirName := "pre-commit-hooks.d"
hooksDirName := filepath.Join(gitDirPath, "hooks")
@ -250,15 +252,15 @@ func installHook(gitDirPath string) (err error) {
}
}
preCommitHookPath := filepath.Join(hooksScriptDirPath, "0-env-sample-sync")
preCommitHook, err := os.OpenFile(preCommitHookPath, os.O_RDWR|os.O_CREATE|os.O_TRUNC, 0755)
preCommitHookPath := filepath.Join(hooksScriptDirPath, "0-ess")
preCommitHook, err := os.OpenFile(preCommitHookPath, os.O_RDWR|os.O_CREATE|os.O_TRUNC, 0o755)
if err != nil {
return
}
executablePath, err := exec.LookPath(os.Args[0])
if err != nil {
fmt.Println("unable to find 'env-sample-sync' in $PATH:", err)
fmt.Println("unable to find 'ess' in $PATH:", err)
os.Exit(1)
}
@ -275,7 +277,7 @@ func installHook(gitDirPath string) (err error) {
return err
}
args := fmt.Sprintf("--env-file=%s --sample-file=%s %s", envFileFlag, sampleFileFlag, examplesFlag)
var buff = bytes.NewBufferString("")
buff := bytes.NewBufferString("")
templateValues := struct {
Args string
@ -294,7 +296,7 @@ func installHook(gitDirPath string) (err error) {
return err
}
preCommitHookScript, err := os.OpenFile(preCommitHookScriptPath, os.O_RDWR|os.O_CREATE|os.O_TRUNC, 0755)
preCommitHookScript, err := os.OpenFile(preCommitHookScriptPath, os.O_RDWR|os.O_CREATE|os.O_TRUNC, 0o755)
if err != nil {
return err
}
@ -305,6 +307,6 @@ func installHook(gitDirPath string) (err error) {
return err
}
fmt.Println("env-sample-sync pre-commit hook installed!")
fmt.Println("ess pre-commit hook installed!")
return nil
}