72 lines
3.3 KiB
Markdown
72 lines
3.3 KiB
Markdown
# AGENTS.md
|
|
|
|
## Overview
|
|
This repository contains NixOS configurations for multiple machines using flakes, home-manager, and sops-nix for secrets.
|
|
|
|
## Working with this Repository
|
|
|
|
### DO
|
|
- Use `nix fmt` or `nix fmt .` to format files before committing (uses nixfmt-tree)
|
|
- Test builds with `nix build .#nixosConfigurations.<hostname>.config.system.build.toplevel`
|
|
- Use the included devShell run `nix develop` to get formatting and linting tools
|
|
- When adding packages, check both overlays in `flake.nix` and `home/programs/`
|
|
- Follow the directory structure: `hosts/` for system configs, `home/` for home-manager configs
|
|
- **CRITICAL: When adding NEW files, run `git add <newfile>` BEFORE building. Nix flakes ignore untracked files in the build context, so newly added files won't be copied and builds will fail until they're git-tracked**
|
|
|
|
### DON'T
|
|
- Don't work directly on master branch, always create a new branch if editing something
|
|
- Don't run `nix flake update` to update inputs, this should only be done by the user manually
|
|
- Don't directly edit files in `secrets/` - they should be manually managed by the user
|
|
- Don't add secrets to Git
|
|
- Don't format with tools other than `nix fmt` (the formatter is defined in flake.nix)
|
|
- Don't modify `.sops.yaml` or any secrets, ask the user to do it manually
|
|
- Don't use `nix-shell` directly - use `nix develop` for the devShell environment
|
|
- Don't skip builds after configuration changes - test before pushing
|
|
- Don't mix stable and unstable packages arbitrarily in the same expression
|
|
- Don't commit without running `nix fmt` - formatted Nix is required
|
|
- **Don't try to build with newly created but untracked files - `nix build` will fail to find them**
|
|
|
|
## Specific Patterns
|
|
|
|
### Adding a New Program
|
|
- DO add to `home/packages` if no nixos or home-manager options are used.
|
|
- DO create a subdirectory in `home/programs/` if nixos or home-manager options are used.
|
|
- DO `git add` the new configuration files before attempting to build
|
|
- DON'T add programs directly to user configs unless absolutely necessary
|
|
|
|
### Modifying System Configuration
|
|
- DO check `system/` for shared configs across hosts
|
|
- DO check individual `hosts/<hostname>/` for host-specific overrides
|
|
- DON'T duplicate configuration - use `system/` modules for shared settings
|
|
|
|
### Working with Secrets
|
|
- DON'T add unencrypted secrets to the repository
|
|
- DON'T commit decrypted secrets
|
|
- DON'T add secrets, ask the user do it themselves
|
|
|
|
### Testing
|
|
- DO run `nix build .#nixosConfigurations.<hostname>.config.system.build.toplevel` to test
|
|
- DON'T push untested configuration changes
|
|
- DON'T attempt to build configurations with newly added but untracked files
|
|
|
|
### Git
|
|
If change is small, and can be described sufficiently in the summary, dont add a long
|
|
body to the commit, prefer just the summary if sufficient.
|
|
|
|
Commits should match the format:
|
|
`topic: description of change`
|
|
|
|
Some examples:
|
|
- hyprland: convert deprecated windowrules
|
|
- packages: nixfmt-rfc-style renamed
|
|
- gunter: use beta nvidia driver
|
|
|
|
|
|
## Repository Structure Guide
|
|
- `flake.nix` - Entrypoint, inputs, overlays, and configurations
|
|
- `hosts/` - System-level NixOS configs per host
|
|
- `home/` - Home-manager configs (programs, editor, window managers)
|
|
- `system/` - Shared system modules (fonts, security, services)
|
|
- `secrets/` - Encrypted secrets (managed by sops-nix)
|
|
- `scripts/` - Utility scripts
|