{"id":13609819,"url":"https://github.com/acaloiaro/ess","last_synced_at":"2025-08-29T23:17:59.733Z","repository":{"id":63825491,"uuid":"571022485","full_name":"acaloiaro/ess","owner":"acaloiaro","description":"ess (env-sample-sync): automatically and safely synchronize env.sample files with .env","archived":false,"fork":false,"pushed_at":"2025-04-11T01:37:35.000Z","size":130,"stargazers_count":87,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-11T02:41:38.764Z","etag":null,"topics":["environment-variables","git","githooks","githooks-plugin"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/acaloiaro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-11-26T22:35:30.000Z","updated_at":"2025-04-11T01:37:38.000Z","dependencies_parsed_at":"2024-01-29T20:17:10.554Z","dependency_job_id":"219bae77-824d-4a41-b4ef-e27b71e5aa2e","html_url":"https://github.com/acaloiaro/ess","commit_stats":null,"previous_names":["acaloiaro/ess","acaloiaro/env-sample-sync"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/acaloiaro/ess","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acaloiaro%2Fess","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acaloiaro%2Fess/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acaloiaro%2Fess/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acaloiaro%2Fess/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/acaloiaro","download_url":"https://codeload.github.com/acaloiaro/ess/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acaloiaro%2Fess/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272779027,"owners_count":24991509,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-29T02:00:10.610Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["environment-variables","git","githooks","githooks-plugin"],"created_at":"2024-08-01T19:01:38.403Z","updated_at":"2025-08-29T23:17:59.726Z","avatar_url":"https://github.com/acaloiaro.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# ess (env sample sync)\n\n[![Gitter chat](https://badges.gitter.im/gitterHQ/gitter.png)](https://app.gitter.im/#/room/#env-sample-sync-dev:gitter.im)\n\nAutomatically keep `env.sample` files in sync with `.env`\n\n---\n\n`ess` transforms environment files containing secrets (e.g. `.env`, `.envrc`) into sample environment files (e.g.\n`env.sample`) that may be safely checked into git.\n\n`ess` may be run manually by running the cli executable, or automatically by installing the pre-commit hook with `ess install`\nin any git repository. Installing `ess` as a git hook ensures that project environment files are automatically and safely\nrevision controlled when they change.\n\nDoing so allows environment configurations to be shared across teams without leaking secrets.\n\n## How it works\n\nBy default, `ess` checks the local directory for environment files named `.env`. The env file name is controlled by\nthe `--env-file` switch. Next, the environment file is parsed for environment variables. Environment variables\nmay be of the following forms:\n\n```\n# Standard environment variables\nFOO=bar baz\nFOO=\"bar baz\"\nFOO='bar baz'\n\n# Envrc environment variable\nexport FOO=bar baz\nexport FOO=\"bar baz\"\nexport FOO='bar baz'\n```\n\nBy default, variable values are replaced with innert values named after the variable, e.g. `FOO=bar` is replaced by `FOO=\u003cFOO\u003e`.\n\nExample values may be provided with the `--example` switch, e.g. `--exmaple=FOO=\"enter your foo here\"` will set `FOO`'s\nvalue as follows `FOO=\"enter your foo here\"` in the sample file.\n\nFinally, when all variables are replaced, the sample file is written with the sanitized variable values, along with all\nnon-variable strings from the file. By default the sample file is named `env.sample`, which is controlled by the `--env-sample`\nswitch.\n\nBecause `ess` permits non-variable strings in environment files, it means that both comments and script code (in the case\nof `.envrc` files) is included in environment sample files. This allows environment files to not only be checked into git, but\ndocumented with comments.\n\n# Installation \u0026 Usage\n\n`ess` can be run in three ways:\n\n1. Manually\n2. As a native git-hook\n3. As a [pre-commit plugin](https://pre-commit.com/#install) (a utility for organizing pre-commit hooks)\n\n## Installation\n\nInstallation is required to run `ess` manually, or as a native git hook. See [pre-commit configuration]\n(#running-as-a-pre-commit-plugin) for pre-commit usage.\n\n\n**Install from the releases page**\n\nDownload [the latest release](https://github.com/acaloiaro/ess/releases/latest) and add it to your `$PATH`.\n\n**Install with `go install`**\n\n```bash\ngo install github.com/acaloiaro/ess@latest\n```\n\n**Nix Flake**\n\nThis application may be added as a flake input\n\n**flake.nix**\n```nix\ninputs.ess = {\n  url = \"github:acaloiaro/ess\";\n  inputs.nixpkgs.follows = \"nixpkgs\";\n};\n```\n\n**configuration.nix**\n```nix\nusers.users.\u003cUSERNAME\u003e.packages = [\n  ...\n  inputs.ess.packages.${system}.default\n];\n```\n\nOr simply run directly\n```bash\nnix run github:acaloiaro/ess\n```\n\n## Running manually\n\n`ess` can be run with no arguments to use defaults.\n\n**Sync `.env` with `env.sample`**\n\n```bash\ness\n```\n\n\n**With a non-default `.env` and `env.sample` location**\n\n```bash\ness --env-file=.env-file-name --sample-file=env-sample-file-name\n```\n\n**Provide example values for variables**\n\nBy default, `ess` uses the name of environment variables in `\u003cbrackets\u003e` as example values in `env.sample`,\ne.g. `FOO=secret value` is replaced with `FOO=\u003cFOO\u003e`. This behavior is customizable wit the `--example` flag.\n\nAdd custom examples for variables `FOO` and `BAR`.\n\n```bash\ness --example=FOO=\"must be a valid UUID\" --example=BAR=\"bars must be a positive integer\"\n```\n\nThe above invocation yields the following `env.sample`\n\n\n```bash\nFOO=must be a valid UUID\n\nBAR=bars must be a positive integer\n```\n\n## Running as a native git-hook\n\nTo add `ess` as a pre-commit git hook in a git repository, run:\n\n```bash\ness install\n```\n\nThis installs `ess` as a pre-commit git hook with default arguments.\n\nThe `install` command supports all [command flags](#command-flags).\n\nIf you need to change `ess` flags, simply run `ess install` again with the desired flags and\nchoose the overwrite [o] option when prompted what to do with the existing pre-commit hook.\n\n## Running as a pre-commit plugin\n\nThis utility can be used as a [pre-commit plugin](https://pre-commit.com/#install)\n\n## Add configuration\n```bash\ncat \u003c\u003cEOF \u003e.pre-commit-config.yaml\nrepos:\n-   repo: https://github.com/acaloiaro/ess.git\n    rev: v2.18.2\n    hooks:\n      - id: ess\nEOF\npre-commit install\ngit add .pre-commit-config.yaml\n```\n\nSee [pre-commit configuration examples](#pre-commit-configuration-examples) for additional pre-commit documentation.\n\n# Background\n\nIt's important to document the environment variables required to run applications, both in production and development. A\ngreat way to do so is with `env.sample` files, but sample files tend to get out of date very quickly.\n\nFor example, let's say you're adding a new feature to your application, and it requires the variable `FOO` to be set.\nWhile you're developing locally, you likely have a `.env` file that looks something like:\n\n```bash\nAPPLICATION_SECRET=supersekrit\n\n# I got this FOO from the detailed process documented at: http:://wiki.example.com/how_to_get_a_foo\nFOO=\"My super secret value for foo\"\n```\n\nWorking on large teams, it's common to share these `.env` files somewhere secure where all developers have access to\nthem. Retrieval is often integrated into application startup and/or bootstrap processes.\n\nBut working on open source projects or teams with less trust and less shared infrastructure, it's more common to share\nan `env.sample`. `ess` automatically keeps the sample file in sync with `.env`, so you don't have to. Your\n`.env` file stays the same, and is automatically converted to the following `env.sample`:\n\n```bash\nAPPLICATION_SECRET=\u003cAPPLICATION_SECRET\u003e\n\n# I got this FOO from the detailed process documented at: http:://wiki.example.com/how_to_get_a_foo\nFOO=\u003cFOO\u003e\n```\n\nIt's even possible to provide default/example values for every environment variables with the `--example` [flag](#command-flags).\n\n## Command Flags\n\n| Name             | Description                                         | Example                                                   | Default                       |\n| ---------------  | --------------------------------------------------- | --------------------------------------------------------- | ----------------------------- |\n| `--env-file`     | The name of the environment file                    | `--env-file=.secrets`                                     | `--env-file=.env`             |\n| `--debug`        | Enable debugging                                    | `--debug`                                                 | `false`                       |\n| `--skip-git-add` | Skip performing `git add` after syncing             | `--skip-git-add`                                          | `false`                       |\n| `--sample-file`  | The name of the sample environment file             | `--sample-file=secrets.example`                           | `--sample-file=env.sample`    |\n| `--example`      | Provide examples for specific environment variables | `--example=FOO=\"Example FOO\" --example=BAR=\"Example BAR\"` | `--example=VAR=\u003cVAR\u003e`         |\n\n## Pre-commit Configuration Examples\n\n### Default configuration\n\n```yml\nrepos:\n-   repo: https://github.com/acaloiaro/ess.git\n    rev: v2.18.2\n    hooks:\n      - id: ess\n```\n\n### Customize `.env` and `env.sample` paths\n\n```yml\nrepos:\n-   repo: https://github.com/acaloiaro/ess.git\n    rev: v2.18.2\n    hooks:\n      - id: ess\n        args: ['--env-file=.env_file', '--sample-file=env_file.sample']\n```\n\n### Customize variable example values\n\nSometimes environment variables need to conform to specific formats, and it's necessary to provide better documentation.\nFor this reason, environment variable examples may be provided in lieu of the default behavior, which is to use the\nenvironment variable name surrounded by `\u003cbrackets like this\u003e` in sample files.\n\n```yml\nrepos:\n-   repo: https://github.com/acaloiaro/ess.git\n    rev: v2.18.2\n    hooks:\n      - id: ess\n        args: [--example=FOO=\"Provide your foo here\", --example=BAR=\"You can fetch bars from https://example.com/bars\"]\n```\n\nExample environment file\n`.env`\n```\nFOO=the_value_of_my_secret_foo\nBAR=the_value_of_my_secret_bar\n```\n\nExample sample file output\n`env.sample`\n```bash\nFOO=Provide your foo here\nBAR=You can fetch bars from https://example.com/bars\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facaloiaro%2Fess","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Facaloiaro%2Fess","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facaloiaro%2Fess/lists"}