File Reference

This page documents the current Hush v3 file model.

File overview

File	Committed	Purpose
`.hush/manifest.encrypted`	Yes	Encrypted repository metadata
`.hush/files/**.encrypted`	Yes	Encrypted secret documents and readers
`.sops.yaml`	Yes	SOPS creation rules for the repo
`~/.hush/state/projects/<slug>/active-identity.json`	No	Machine-local active identity state
`~/.hush/state/projects/<slug>/user/local-overrides.encrypted`	No	Machine-local encrypted overrides

Canonical repository files

`.hush/manifest.encrypted`

This is the repository authority document for v3.

It defines:

identities
bundles
targets
imports
file index metadata

Location: Repository root under .hush/
Commit: Yes
Created by: hush bootstrap, hush migrate --from v2

`.hush/files/**.encrypted`

These encrypted YAML documents hold the actual secret entries and their file readers.

Typical examples:

.hush/files/env/project/shared.encrypted
.hush/files/env/project/development.encrypted
.hush/files/env/project/production.encrypted

Commit: Yes for shared repo files
Created by: hush bootstrap, hush set, hush edit, hush migrate --from v2

`.sops.yaml`

SOPS configuration for the repo public key set.

creation_rules:
  - encrypted_regex: '.*'
    age: age1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Location: Repository root
Commit: Yes

Machine-local state

Active identity state

~/.hush/state/projects/<project-slug>/active-identity.json

Tracks the currently selected local identity for the project.

Local overrides

~/.hush/state/projects/<project-slug>/user/local-overrides.encrypted

Stores machine-local encrypted overrides that should not be committed.

Typical project structure

Directory.hush/
- manifest.encrypted
- Directoryfiles/
  - Directoryenv/
    Directoryproject/
    shared.encrypted
.sops.yaml
package.json

Current commands that manage these files

hush bootstrap
hush config show
hush config active-identity
hush set DATABASE_URL
hush run -- npm start

Legacy bridge

If you still have a legacy hush.yaml repository, do not treat it as the current model. Use:

hush migrate --from v2
hush migrate --from v2 --cleanup

Recommended `.gitignore`

# Machine-local Hush state
.hush/state/

# Local editor/runtime leftovers
.hush-materialized/

# Keep canonical encrypted repository files
!.hush/
!.hush/manifest.encrypted
!.hush/files/