Skip to content

File Structure

Jump to bottom
NullString1 edited this page Jan 13, 2026 · 1 revision

File Structure

Understanding the NullOS directory structure.

Overview

NullOS uses a well-organized structure separating system configuration, home manager settings, and documentation.

NullOS/
├── flake.nix              # Main flake configuration
├── flake.lock            # Locked dependencies
├── variables.nix         # Per-machine variables (gitignored)
├── variables.nix.example # Variable template
├── README.md            # Project documentation
├── WIKI.md              # Wiki index
├── .gitignore           # Git ignore rules
├── .gitattributes       # Git attributes
├── .envrc               # Direnv configuration
├── _screenshots/        # Screenshots
├── wallpapers/          # Wallpaper images
├── home/               # Home Manager configs
├── modules/            # NixOS system modules
└── wiki/               # Local wiki (optional)

Root Directory Files

flake.nix

Main flake configuration that:

  • Defines inputs (nixpkgs, home-manager, etc.)
  • Configures system outputs
  • Sets up overlays
  • Defines machine configurations

Key sections:

  • inputs - External dependencies
  • outputs - System and home configurations
  • nixosConfigurations - Per-machine system configs
  • homeConfigurations - User configurations

variables.nix

Per-machine configuration variables:

  • Username and hostname
  • Git credentials
  • Terminal and browser preferences
  • Display configuration
  • Hardware settings (NVIDIA, etc.)
  • Theming options

Important: This file is gitignored for privacy.

flake.lock

Locked versions of all inputs. Ensures reproducibility.

Update with:

nix flake update

Home Directory (home/)

User-level configurations managed by Home Manager.

home/
├── default.nix          # Main entry point
├── bat.nix             # Bat (cat alternative)
├── bottles.nix         # Bottles (Wine)
├── bottom.nix          # Bottom (btop)
├── eza.nix            # Eza (ls alternative)
├── gh.nix             # GitHub CLI
├── ghostty.nix        # Ghostty terminal
├── git.nix            # Git configuration
├── gtk.nix            # GTK theming
├── httpie-desktop.nix # HTTPie GUI
├── kde.nix            # KDE integration
├── nvf.nix            # Neovim config
├── nwg-displays.nix   # Display tool
├── office.nix         # Office apps
├── qt.nix             # Qt theming
├── starship.nix       # Shell prompt
├── stylix.nix         # Stylix theming
├── swappy.nix         # Screenshot annotation
├── swaync.nix         # Notifications
├── swayosd.nix        # On-screen display
├── tealdeer.nix       # tldr client
├── vscode.nix         # VSCode config
├── xdg.nix            # XDG directories
├── zoxide.nix         # Directory jumper
├── fastfetch/         # System info
├── hyprland/          # Hyprland config
├── rofi/              # App launcher
├── scripts/           # Custom scripts
├── waybar/            # Status bar
├── wlogout/           # Logout menu
├── yazi/              # File manager
└── zsh/               # Shell config

home/default.nix

Main home-manager configuration that:

  • Imports all other home configs
  • Defines user packages
  • Sets up programs
  • Configures services

home/hyprland/

Hyprland window manager configuration:

hyprland/
├── default.nix          # Entry point
├── animations-end4.nix  # Animations
├── binds.nix           # Keybindings
├── env.nix             # Environment vars
├── hypridle.nix        # Idle management
├── hyprland.nix        # Core settings
├── hyprlock.nix        # Screen lock
├── pyprland.nix        # Scratchpads
└── windowrules.nix     # Window rules

home/scripts/

Custom shell scripts:

scripts/
├── keybinds.nix        # Keybind lister
├── rofi-launcher.nix   # Rofi launcher
├── screenshotin.nix    # Screenshot tool
└── wallsetter.nix      # Wallpaper setter

Modules Directory (modules/)

System-level NixOS modules organized by category.

modules/
├── default.nix         # Imports all modules
├── misc/              # Miscellaneous configs
├── services/          # System services
├── software/          # Applications
└── system/            # System settings

modules/misc/

misc/
├── default.nix        # Entry point
├── fonts.nix          # Font configuration
└── user.nix           # User account setup

Purpose: User management, fonts, locale settings.

modules/services/

services/
├── default.nix        # Entry point
├── backup.nix         # Restic backups
├── ollama.nix         # Ollama AI server
├── services.nix       # Core services
├── sunshine.nix       # Game streaming
├── virtualisation.nix # Docker/VMs
├── vpn.nix           # VPN configs
└── xserver.nix       # X11 settings

Purpose: System services configuration.

modules/software/

software/
├── default.nix        # Entry point
├── android-studio.nix # Android dev
├── dolphin.nix        # File manager
├── flatpak.nix        # Flatpak support
├── nh.nix            # Nix helper
├── packages.nix      # System packages
├── sddm.nix          # Display manager
├── starship.nix      # Shell prompt
└── steam.nix         # Gaming

Purpose: Application installation and configuration.

modules/system/

system/
├── default.nix        # Entry point
├── audio.nix          # PipeWire audio
├── boot.nix           # Boot config
├── hardware_add.nix   # Additional hardware
├── hardware_nslapt.nix # Laptop config
├── hardware_nspc.nix  # Desktop config
├── network.nix        # Networking
├── nvidia.nix         # NVIDIA drivers
├── power.nix          # Power management
├── printing.nix       # Printer support
├── rtl8852cu.nix      # WiFi driver
├── security.nix       # Security settings
└── system.nix         # Core system

Purpose: Low-level system configuration, hardware support.

Configuration Flow

How Configuration is Applied

  1. flake.nix loads variables.nix
  2. Variables are passed to system and home configs
  3. modules/default.nix imports all system modules
  4. home/default.nix imports all home configs
  5. Build process generates system configuration
  6. Activation applies configuration to system

Variable Propagation

variables.nix
    ↓
flake.nix (vars)
    ↓
├─→ nixosConfigurations (system)
│       ↓
│   modules/ (receives vars)
│
└─→ homeConfigurations (user)
        ↓
    home/ (receives vars)

Adding New Configurations

New Home Module

  1. Create file in home/:
# home/my-app.nix
{ config, pkgs, ... }:
{
  programs.myapp = {
    enable = true;
    settings = { };
  };
}
  1. Import in home/default.nix:
imports = [
  ./my-app.nix
];

New System Module

  1. Create in appropriate modules/ subdirectory:
# modules/software/my-software.nix
{ config, pkgs, ... }:
{
  environment.systemPackages = [ pkgs.my-package ];
}
  1. Import in modules/software/default.nix:
imports = [
  ./my-software.nix
];

Directory Structure Best Practices

Organization Principles

  1. Separation of Concerns

    • System configs in modules/
    • User configs in home/
    • Variables in root

  2. Categorization

    • Group related configs together
    • Use subdirectories for complex configs

  3. Naming Conventions

    • Descriptive filenames
    • Use .nix extension
    • Match program name when possible

  4. Modularity

    • One program per file
    • Import from central default.nix
    • Reusable components

Git Management

What to Commit

✅ Do commit:

  • All .nix files (except variables.nix)
  • Documentation
  • Scripts
  • Wallpapers (if not too large)
  • Example files

❌ Don't commit:

  • variables.nix (personal data)
  • result symlinks
  • Build outputs
  • Secrets/passwords
  • Cache files

.gitignore

# Personal configuration
variables.nix

# Nix build outputs
result
result-*

# Direnv
.direnv/

# Editor files
.vscode/
.idea/

Quick Reference

Find Configuration for...

Application X:

  1. Check home/default.nix packages
  2. Look for home/X.nix
  3. Check modules/software/packages.nix

Service Y:

  1. Check modules/services/Y.nix
  2. Look in modules/services/services.nix

System Setting Z:

  1. Check modules/system/Z.nix
  2. Look in modules/system/system.nix

Keybinding:

  • home/hyprland/binds.nix

Theme/Colors:

  • home/stylix.nix
  • variables.nix (stylixImage)

Next Steps

Clone this wiki locally