hypha

A declarative user-environment and dotfiles configuration system

Hypha, is a declarative configuration system for managing a user's environment and dotfiles. It represents configuration as Resources defined by declarative manifests, forming a dependency graph that is reconciled through pluggable controllers.

Example

First let's define some manifests

Hypha allows you to define manifests using Jsonnet, JSON, & YAML

~/.config/hypha/example.jsonnet:

local hypha = import 'lib/hypha.libsonnet';
[
  // Create a symlink .gitconfig => ~/.gitconfig
  hypha.SymlinkManifest('gitconfig', spec={
    source: ".gitconfig",
    target: "~/.gitconfig",
  }),
]

Create another manifest, this time using YAML.

~/.config/hypha/git.yaml:

---
kind: Package
metadata:
  name: git
  labels:
    - test
spec:
  target: git

By default, Hypha can discover manifests automatically.

Any file found in the config directory ~/.config/hypha with one of the following extensions is considered a valid manifest source:

• .jsonnet
• .yaml
• .json

However, you can also provide an init.lua in the config directory to customize how and what manifests get loaded:

~/.config/hypha/init.lua:

local sources = require('hypha.sources')
return {
  -- load the new manifests from ~/.config/hypha/example.jsonnet
  sources.file("%h/example.jsonnet"),
  -- manifests can also be provided directly from lua
  -- create the directory:  ~/.config/hypha/test-dir
  sources.raw([[
  {
    kind: "Directory",
    metadata: {
      "name": "TestDirectory",
      "labels": [
        "test",
      ],
    },
    spec: {
      "target": "%h/test-dir",
    },
  }
  ]])
}

Once your config is defined, you can preview the changes Hypha would make with plan:

Optional, but highly recommended

hypha plan

Finally, if your changes look correct, let's apply those changes:

hypha apply

Building From Source

Check out the build docs for how to build.

Wiki

Check out the wiki for more information.

CLI

A preview of the sub-commands for Hypha, you can find out more in the wiki

hypha --help

A dotfile manager

Usage:
  hypha [command]

Configuration Commands
  adopt       Adopt specific resources into the resource graph
  apply       Apply your configuration
  gc          Cleanup orphaned resources
  generate    generate a manifest for a given resource
  init        Initialize hypha on a system
  plan        Preview the pending changes
  status      Show resource drift
  tidy        Cleanup the configuration dir

Inspection Commands
  browse      Open a read-only interactive browser session
  describe    Describe a resource
  explain     Explain why a resource exists
  graph       Graph the resources
  history     Show the history of the resource graph
  lint        Lint the specified manifests
  list        List resources in the graph
  query       Query the resource graph using an expression
  validate    Validate the specified manifests

Development Commands
  docs        Open the documentation for a specific resource kind in the system browser
  eval        Evaluate a lua expression or file
  lsp         Run the LSP service for a manifest

Resource Commands

Additional Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  info        Show runtime info
  rocks       Manipulate luarocks packages

Flags:
      --cache-dir string    The cache dir for hypha (default "/home/tazz/.cache/hypha")
      --config-dir string   The configuration dir for hypha (default "/home/tazz/.config/hypha")
  -h, --help                help for hypha
      --state-dir string    The state dir for hypha (default "/home/tazz/.local/state/hypha")
  -v, --verbose             add more detailed output

Use "hypha [command] --help" for more information about a command.

Contributing

See the Contributing guide in the wiki for contribution guidelines and development information.

AI Contributions

AI-assisted and AI-generated contributions are welcome. However, AI contributions are subject to additional disclosure and review requirements described in the AI Contributions section of the Contributing guide.

AI Usage Disclaimer

This project contains some contributions made using AI. These contributions undergo additional review before merging.

For transparency, known AI usage in this project is documented below:

• Claude --- Free tier, Sonnet 5 Medium
  • Refactoring the Resource ID field from char* to uuid_t
  • Adding telemetry tracking and reporting data to resources
  • Additional contributions can be found in Claude's commits

AI usage does not imply that the resulting changes were accepted without review. AI-generated changes remain subject to the project's normal architectural, design, correctness, testing, and maintainability standards, in addition to the requirements described in the AI Contributions section.

Credits

Hypha is inspired by the helm, dotbot, and home-manager

With contributions by the following:

• ChatGPT --- Logo
• Claude --- Some contributions

License

See LICENSE.