https://github.com/xx4h/nixconf
❄️ 🗂️ A tool to manage a multi-repo NixOS configuration
https://github.com/xx4h/nixconf
cli comman configuration-management dotfiles home-manager multi-repo nix nix-flakes nixos nixos-configuration
Last synced: 19 days ago
JSON representation
❄️ 🗂️ A tool to manage a multi-repo NixOS configuration
- Host: GitHub
- URL: https://github.com/xx4h/nixconf
- Owner: xx4h
- License: apache-2.0
- Created: 2026-05-12T17:59:08.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-24T10:22:47.000Z (24 days ago)
- Last Synced: 2026-05-24T12:18:05.117Z (24 days ago)
- Topics: cli, comman, configuration-management, dotfiles, home-manager, multi-repo, nix, nix-flakes, nixos, nixos-configuration
- Language: Go
- Homepage:
- Size: 79.1 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Notice: NOTICE
Awesome Lists containing this project
README
# nixconf
[](https://github.com/xx4h/nixconf/actions/workflows/linter-full.yml)
[](https://github.com/xx4h/nixconf/actions/workflows/test-full.yml)
[](https://goreportcard.com/report/github.com/xx4h/nixconf)
[](LICENSE)
[](https://github.com/xx4h/nixconf/tags)
Repository manager for a multi-repo NixOS configuration: one shared
`nixos-common`, one `nixos-` per machine, and one `nixos-` per user.
`nixconf` keeps the sub-repos in sync — cloning them, running `nix flake update`
across all of them, verifying that consumers track the latest `nixos-common`,
and forwarding arbitrary `git` commands into each working tree.
## Install
### Pre-built binaries
Grab a tarball for your platform from the
[releases page](https://github.com/xx4h/nixconf/releases) and place the
`nixconf` binary on your `$PATH`.
### Nix flake
```bash
nix run github:xx4h/nixconf
# or, in a flake:
inputs.nixconf.url = "github:xx4h/nixconf";
```
The package installs Bash/Zsh/Fish completion files into the standard
`share/` paths, so shells that auto-load vendor completions pick them up
without further configuration.
### Home Manager
A Home Manager module is exposed at `homeManagerModules.default`:
```nix
{
inputs.nixconf.url = "github:xx4h/nixconf";
}
```
```nix
# in your Home Manager config
{ inputs, ... }: {
imports = [ inputs.nixconf.homeManagerModules.default ];
programs.nixconf = {
enable = true;
# All three default to true; toggle off to skip the shell init hook.
# enableBashIntegration = true;
# enableZshIntegration = true;
# enableFishIntegration = true;
};
}
```
### Homebrew
```bash
brew install xx4h/tap/nixconf
```
### From source
```bash
git clone https://github.com/xx4h/nixconf.git
cd nixconf
task build # → ./bin/nixconf
task local-install # → ~/.local/bin/nixconf
```
## Configuration
`nixconf` reads `nixconf.yaml` from the first match in this order:
1. The path passed to `-c, --config `
2. The first `nixconf.yaml` found walking up from the current directory
3. `$XDG_CONFIG_HOME/nixconf.yaml` (or `~/.config/nixconf.yaml`)
Run `nixconf init` to create a starter file at
`$XDG_CONFIG_HOME/nixconf.yaml`, or `nixconf init ` to write it
elsewhere.
The file lists the repos to manage, grouped into `common`, `hosts`, and
`users`:
```yaml
git_base: "git@github.com:"
# Optional. Repos are cloned under this directory. Defaults to
# $XDG_DATA_HOME/nixconf (or ~/.local/share/nixconf). Relative values
# are resolved against the directory holding this file.
# data_dir: ""
# Optional. Controls how `nixconf update` commits the bumped flake.lock.
# Defaults shown.
update:
# `{{inputs}}` is replaced with " " when INPUTs are
# passed on the command line, and with "" otherwise.
commit_message: "chore(deps): flake update{{inputs}}"
# Extra args appended to `git commit`. An explicit empty list disables
# signing (`commit_flags: []`).
commit_flags: ["-v", "-s", "-S"]
repos:
common:
- name: nixos-common
path: nixos-common
hosts:
- name: nixos-desktop
path: hosts/nixos-desktop
- name: nixos-laptop
path: hosts/nixos-laptop
# Per-repo `url` overrides git_base entirely.
- name: nixos-other
path: hosts/nixos-other
url: "https://git.example.com/team/nixos-other.git"
# Disabled entries are skipped by clone/update/verify/git.
- name: nixos-archive
path: hosts/nixos-archive
disabled: true
users:
- name: nixos-
path: users/nixos-
```
`git_base` is optional if every repository provides its own `url`.
## Commands
| Command | What it does |
| -------------------------------------- | ------------------------------------------------------------------------- |
| `nixconf init [path]` | Create a starter `nixconf.yaml` (default: `$XDG_CONFIG_HOME`) |
| `nixconf clone` | Clone every repository in `nixconf.yaml` into its `path` under `data_dir` |
| `nixconf update [INPUT ...]` | `nix flake update` + commit `flake.lock` + push, in every repository |
| `nixconf verify` | Check host/user `flake.lock`s point at the latest `nixos-common` |
| `nixconf git ` | Run `git -C ` in every selected repository |
| `nixconf config add ` | Add a `host` or `user` entry (flags: `--path`, `--url`) |
| `nixconf config edit ` | Edit an entry (flags: `--name`, `--path`, `--url`) |
| `nixconf config delete ` | Remove an entry (aliases: `rm`, `remove`) |
| `nixconf config disable ` | Mark an entry as disabled — skipped by other commands |
| `nixconf config enable ` | Re-enable a previously disabled entry |
| `nixconf version` | Print version / commit / build date |
| `nixconf completion ` | Print shell completion (Bash/Zsh/Fish/PowerShell) |
Arbitrary Git commands are run only via the explicit `nixconf git`
subcommand; unknown subcommands are no longer auto-forwarded.
**Selectors** (combine with any command):
| Flag | Effect |
| --------------------- | ----------------------------------- |
| `--common` | only common repos |
| `--consumers` | only consumer repos (hosts + users) |
| `--hosts` | only host config repos |
| `--users` | only user config repos |
| `-r, --repo ` | only the named repository |
| `-n, --dry-run` | show what would be done; no changes |
| `-c, --config ` | override the `nixconf.yaml` lookup |
### Examples
```bash
# create a starter config in $XDG_CONFIG_HOME/nixconf.yaml
nixconf init
# add a host, then clone everything
nixconf config add host nixos-desktop
nixconf clone
# bump nixpkgs across all repos, commit + push the lockfile in each
nixconf update nixpkgs
# bump everything, only in host repos
nixconf --hosts update
# check that every host/user flake.lock pins the latest nixos-common
nixconf verify
# git in every repo (use the explicit `git` subcommand)
nixconf git status
nixconf --hosts git pull
nixconf -r nixos-common git log --oneline -5
```
## Shell completion
```bash
# zsh — one-time setup
nixconf completion zsh > "${fpath[1]}/_nixconf"
# bash
nixconf completion bash > /etc/bash_completion.d/nixconf
```
## License
Apache-2.0. See [LICENSE](./LICENSE) and [NOTICE](./NOTICE).