Mario's dotfiles repository
Configurations previews
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.
Note
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.
I use Nix to manage the dependencies and configurations for the tools and applications included in these dotfiles. This approach provides a reproducible and declarative way to set up a new machine. Specifically, I leverage the Flakes feature in Nix, which ensures that dependencies are version-pinned, further enhancing the reproducibility of the setup.
In addition to the benefits described above, the Flake approach enables centralized and organized definitions for system configurations, development environments, and other workflows.
The flake.nix file serves as the flake's entry point. It defines the flake's
dependencies (inputs) and outputs, such as system configurations and development
tools. However, these outputs are actually implemented in separate files.
The development.nix file specifies tools like pre-commit and development shells, utilizing flake-parts. For more details, refer to the Development section.
System configurations are defined in the system-configs.nix file and managed
using the custom 'configurations-manager' library (see
below). Each type of configuration has
its own directory:
- NixOS configurations are stored in
nixos-configurations/. - Darwin configurations are stored in
darwin-configurations/. - Home-Manager configurations are stored in
home-configurations/.
At the top level of each directory, shared modules for all hosts/users of that configuration type are defined. Within these directories, subdirectories are used to store host- or user-specific configurations.
This structure provides a clear overview of the components comprising each configuration managed by these dotfiles.
Repository file tree
dotfiles
├── configurations-manager
│ ├── default.nix
│ ├── home-makers.nix
│ ├── system-makers.nix
│ └── utils.nix
├── darwin-configurations
│ ├── Marios-MacBook-Pro
│ │ ├── packages.nix
│ │ └── system.nix
│ ├── host-users.nix
│ └── nix-core.nix
├── home-configurations
│ ├── firefox
│ │ ├── profiles
│ │ │ └── default.nix
│ │ └── default.nix
│ ├── mariovagomarzal@Marios-MacBook-Pro
│ │ ├── core.nix
│ │ ├── firefox.nix
│ │ ├── git.nix
│ │ ├── skhd.nix
│ │ ├── ssh.nix
│ │ └── yabai.nix
│ ├── vscode
│ │ ├── default.nix
│ │ ├── global-snippets.nix
│ │ ├── keybindings.nix
│ │ ├── language-snippets.nix
│ │ ├── user-settings.nix
│ │ └── user-tasks.nix
│ ├── alacritty.nix
│ ├── bat.nix
│ ├── core.nix
│ ├── fish.nix
│ ├── git.nix
│ ├── lsd.nix
│ └── starship.nix
├── nixos-configurations
├── .gitignore
├── CHANGELOG.md
├── development.nix
├── flake.lock
├── flake.nix
├── Justfile
├── LICENSE
├── README.md
└── system-configs.nix
The 'configurations-manager' library is a custom tool designed to leverage the repository structure described above, making it easy to locate and manage the required files for each configuration.
This library is implemented in the configurations-manager/ directory. For a
detailed explanation of its usage, refer to the
configurations-manager/default.nix file, which defines the three
primary functions for creating configurations:
mkNixosConfigurations: Used to define NixOS configurations.mkDarwinConfigurations: Used to define Darwin configurations.mkHomeConfigurations: Used to define standalone Home-Manager configurations.
An example of how to use this library can be found in the system-configs.nix
file. This file also provides additional details on how the configurations in
this repository are structured and defined.
In this section, we will describe how to setup each of the machines and/or users handled by this repository.
Caution
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.
Configuration preview
We're going to describe the setup process for my (Mario's) MacBook Pro. We will assume a fresh installation of macOS.
-
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
~/.sshdirectory. -
Install Xcode Command Line Tools: In first place, 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 -
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:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" -
Install Nix: We will use Nix to setup and manage the machine configuration. Install Nix following the instructions in the official download page.
-
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
cdinto it:git clone https://github.com/mariovagomarzal/dotfiles.git cd dotfiles
-
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:
nix --extra-experimental-features 'nix-command flakes' run nix-darwin -- switch --flake '.#Marios-MacBook-Pro'
If this 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'Here we will describe some extra optional manual steps which are not automated by the dotfiles.
Firefox
- Firefox Color theme: The Firefox Color extension is used to customize the browser's theme. We use the Catppuccin Firefox port theme. To apply the theme, follow the steps described in the repository's README.
- 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.jsonfile. Then we have to use this file with Stylus to apply the styles.
In this section, we will describe how to setup the development environment, the workflows and the conventions used in this repository.
To work with this repository, as we are using Nix with flakes, a development
shell with the necessary tools and configurations has been defined in the
development.nix file as a submodule of the main flake.
Assuming that you have Nix installed, you can enter the development shell by running the following command:
nix --extra-experimental-features 'nix-command flakes' developThe --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. Finally, you can exit the shell by typing exit.
In addition to that, some other basic tasks related to the development are
defined in a Justfile. You can see the list of available tasks (under the
development category) by simply running just.
This repository follows a simple (and flexible) workflow:
- The main branch (
main) holds the stable version of the dotfiles. These versions must be tagged with a format likeYYYY.MM.DD, with optional patch versions separated by a dot if more than one version is released in the same day.- Small changes can be committed directly to the main branch.
- Larger changes are recommended to be developed in separate feature branches.
- All changes should be documented in the
CHANGELOG.mdfile. The format of the changelog is described in the file itself.
Copyright © 2024-present Mario Vago Marzal