Mario's dotfiles repository

 

Configurations previews

 

Table of contents

• 📖 About this repository
  • Repository structure
• 🚀 Setup
  • Mario's MacBook Pro
• 👨‍💻 Development
  • Environment
  • Workflow and conventions

About this repository

This repository serves as my personal dotfiles for setting up a new machine. This includes many system settings and the installation and configuration of most of the tools and applications I use on a daily basis on each of the machines handled by this repository.

Important

As mentioned, these dotfiles are tailored to my personal needs and preferences. Therefore, in most cases, they will not be suitable for anyone else. However, feel free to use them as a starting point for your own dotfiles. This guide is intended to be a reference for myself, but also for anyone else who might find it useful to build their own dotfiles.

This dotfiles repository contains configurations for my NixOS and Darwin (macOS) machines. The configurations are managed with Nix, with this repository serving as a Nix flake whose outputs are the machine configurations.

Repository structure

This repository's flake uses Blueprint, a library that maps a standard folder structure to flake outputs with an opinionated approach that keeps things simple and predictable.

For comprehensive details on how Blueprint works, please refer to the official documentation.

Check the specific directories in this repository to see which modules, hosts, and configurations are currently available.

Setup

In this section, we will describe how to setup each of the machines handled by this repository.

Warning

The following instructions will install and configure many tools and applications on your machine. Make sure to read and understand what the setup process does before running it.

Mario's MacBook Pro (Marios-MBP)

Configuration preview

We're going to describe the setup process for my (Mario's) MacBook Pro. We will assume a fresh installation of macOS.

1. Restore SSH keys: I use SSH keys to authenticate with GitHub and other services. For that reason, we will need to safely restore the SSH keys from a backup or generate new ones and store them in the ~/.ssh directory.

2. Install Xcode Command Line Tools: For the setup process, we will need to install the Xcode Command Line Tools, since they may be required in some of the following steps. To do so, run the following command in the terminal:

   xcode-select --install

3. Install Homebrew: Some packages are installed via Homebrew by nix-darwin. However, nix-darwin will not install Homebrew itself. To install Homebrew follow the instructions in the official download page or TL;DR, run the following command in the terminal:

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

4. Install Nix: We will use Nix to setup and manage the machine configuration. Install Nix following the instructions in the official download page.

5. Clone the repository: Once Nix is installed and the SSH keys are in place, we can clone the repository with Git (or by manually downloading it) and cd into it:

   git clone https://github.com/mariovagomarzal/dotfiles.git
   cd dotfiles

6. Setup the machine: If it is the first time we're setting up the machine with these dotfiles, we have to run the following command:

   sudo nix --extra-experimental-features 'nix-command flakes' run nix-darwin -- switch --flake '.#Marios-MBP'

If the last command succeeds, the machine should be fully configured with the dotfiles. From now on, we can update the machine by running the following Just recipe:

just darwin-rebuild # or simply 'just dr'

Extra optional manual steps

Here we will describe some extra optional manual steps which are not automated by the dotfiles.

Firefox

• Stylus user styles: The Stylus extension is used to apply custom styles to web pages. We use a curated list of user styles from the Catppuccin community. In this website we can select the styles (and its flavors) we want to apply to get an import.json file. Then we have to use this file with Stylus to apply the styles.

Development

In this section, we will describe how to setup the development environment, the workflows and the conventions used in this repository.

Environment

The repository flake defines a development shell with all the necessary tools and configurations to work with the repository. Assuming that Nix is installed, you can enter the development shell by running the following command:

nix --extra-experimental-features 'nix-command flakes' develop

Tip

The --extra-experimental-features 'nix-command flakes' flag is only needed if this features are no enabled by default in your Nix installation.

If the command succeeds, you will see a welcome message with a list of the available tools and commands. You can type menu to see the list of available commands again in any moment.

When entering the development shell, some git hooks are automatically installed to help with the workflow and conventions described in the next sections.

However, most of the tasks related to the development are defined in the Justfile file. You can see the list of available tasks by simply running just. Development-related recipes are defined under the development category.

Note

See the Just documentation for more information about how to use the Just command runner. You can also check the Justfile file for seeing how the tasks are defined.

Workflow and conventions

Next, we will describe the workflow and conventions used in this repository.

Note

Before version 2025.08.14, there were no strict rules for commit messages, branching, or other aspects of the workflow. This may be reflected in the commit history and other parts of the repository.

Commit messages

Commit messages follow the Conventional Commits specification, adapted to the context of a dotfiles repository. This ensures a consistent and readable commit history.

The standard format remains the same:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

We use the conventional commit types, where feat and fix take on meanings appropriate for dotfiles, like feat for adding new configurations, modules, or capabilities, and fix for correcting broken configurations or resolving issues. Other standard types (docs, style, refactor, perf, test, build, ci, chore) are used with their usual meanings.

Scopes identify which part of the repository is affected and follow specific patterns depending on the part of the configuration (if any) being changed:

• Module changes in the modules/ directory use simple platform identifiers: nixos, darwin, or home. For example: feat(nixos): add new firewall module or fix(home): correct git module structure.

• Host configurations in the hosts/ directory use the host name directly, such as fix(Marios-MBP): update display settings.

• User configurations in the hosts/<host_name>/users/ directories follow the pattern <host_name>/<user_name>, like feat(Marios-MBP/mariovagomarzal): add starship config.

• General changes use broader scopes:

  • config for general configuration changes not specific to a module, system, or home (flake-level changes, overlays, inputs, structure, etc.).
  • lib for changes related to the custom Nix library, stored in lib/.
  • overlays for changes to package overlays, stored in overlays/.
  • packages for changes to custom packages, stored in packages/.
  • shells for changes to development shells, stored in shells/.
  • checks for changes to flake checks, stored in checks/.

Other scopes can be used as needed.

Tip

A git hook automatically validates commit messages against this specification.

Branching

There are no strict rules for branching in this repository. The main branch holds the stable version of the dotfiles. Small changes can be committed directly to the main branch, while larger changes are recommended to be developed in separate feature branches.

Every stable version of the dotfiles must be tagged with a version tag, whose format is described in the next section.

Changelog

All notable changes to this project will be documented in the CHANGELOG.md file. The format of the changelog is described in the file itself.

The changelog is generated automatically with git-cliff. Use the following Just recipe to update the changelog:

just changelog

Important

Use the following commit message when updating the changelog so that it is ignored by git-cliff:

chore: update the changelog

Versioning

Although Conventional Commits are used for commit messages, this repository does not follow Semantic Versioning for versioning. Instead, each stable version of the dotfiles repository is tagged with a date in the format YYYY.MM.DD(.P), where P is an optional patch version separated by a dot if more than one version is released in the same day.

Use the following Just recipe to create a new version tag:

just tag

Important

The tag is obtained by reading the changelog. Thus, make sure that the changelog is up to date before creating a new tag.

 

---

Licensed under the MIT License by Mario Vago Marzal.