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
|