Here is the ordered list of applications and utility, organized as a todo-list until I get them all done.
- alacritty
- bash
- brew
- homebrew bundle
- btop
- fzf
- git
- iterm2
- k9s
- lazygit
- mas
- nvim
- obsidian
- ranger
- ruff
- sh
- starship
- tmux
- uv
- vscode
- wezterm
- yazi
- zsh
- zoxide
- winget
Some more todos:
- simplify this README by creating a docs folder with a README.md per dotfile
- some of the applications listed here do not have dotfile and should be moved somewhere else
This repo contains my dotfiles setup, allowing for a consistent coding experience across multiple machines and OS'es. Mind you, in my normal workflow, I use macos, ubuntu, and Windows 11.
I use GNU Stow to manage the various configuration files in this repo. In a nutshell, Stow allows to store all the respective dotfiles in a dedicated directory (which can be version controlled, and that's part of the point), and then creates symbolic links to the locations that are expected to be in by their respective programs. I name that folder dotfiles.
An important point to remember is that Stow does not care about the folder structure. It will create a symlink to the user's home directory by default.
GNU Stow can be installed using brew:
brew install stowAs much as possible, I use the XDG base directory specification by setting the environment variable XDG_CONFIG_HOME in my .profile file. More on that in the section dedicated to Shells.
export XDG_CONFIG_HOME="$HOME/.config"Following that convention means that most dotfiles would be under the .config folder. There are many exceptions to that, for example the bash and zsh files.
Each application which uses a dotfile should have its own eponymous subfolder under dotfiles. It should contain a .config folder which in turn should contain the configuration file expected by the application.
As an example, let's consider the dotfile for nvim. The folder structure would look like this:
dotfiles/
├─ nvim/
│ ├─ .config/
│ │ ├─ nvim/
│ │ │ ├─ init.lua
Here is a more detailed example listing my home folder with several cases:
├── .bash_profile -> dotfiles/bash/.bash_profile
├── .bashrc -> dotfiles/bash/.bashrc
├── .config
│ ├── alacritty -> ../dotfiles/alacritty/.config/alacritty
│ └── yazi -> ../dotfiles/yazi/.config/yazi
├── .profile -> dotfiles/sh/.profile
├── .wezterm.lua -> dotfiles/wezterm/.wezterm.lua
├── dotfiles
│ ├── README.md
│ ├── alacritty
│ │ └── .config
│ │ └── alacritty
│ │ └── alacritty.toml
│ ├── bash
│ │ ├── .bash_profile
│ │ └── .bashrc
│ ├── wezterm
│ │ └── .wezterm.lua
│ └── yazi
│ └── .config
│ └── yazi
│ └── yazi.toml
└── starship.toml -> dotfiles/starship/starship.toml
Observe that .bashrc is a symlink to dotfiles/bash/.bashrc, the same goes for starship.toml. On the other hand, alacritty uses the XDG_CONFIG_HOME convention and as a result, its configuration file alacritty.toml is symlinked to config/alacritty/ while residing in the dotfiles folder.
NOTE: wezterm should recognize the XDG_CONFIG_HOME but doesn't.
stow creates symlinks for all the dotfiles at once using a single command. Assuming that the repo has been cloned into dotfiles:
cd dotfiles
stow .Alternatively, one can only deploy certain dotfiles by using the command. Here is an example with the bash doftile:
stow bashSee more options in the Stow documentation.
I currently use 2 different terminals and I have yet to decide on which one to settle.
As of 2025-01-23 here is how the github projects compare:
Alacritty: 57.4K ⭐, 451 👀, 3.1k forks, toml config, Apache License v2.0WezTerm: 19K ⭐, 94 👀, 833 forks, lua config, MIT license
Alacritty is a cross-platform GPU-powered terminal emulator configured using toml files. It plays well with tmux.
The configuration file alacritty.toml is pretty straightforward to understand, the reference can be found in the official documentation.
The main elements of interest are:
- the window appearance
- the font
- the cursor behavior
- the theme (
catppuccin)
A theme is self contained in a toml file. There are several sources available, one of which is alacritty-theme. The repo can be cloned and placed under alacritty/.config/themes. Then provide the path to the theme of your choice within the alacritty.toml configuration file. The downside is that some themes (notably the catpuccin ones) have not seen any updates in over 2 years.
Alternatively, one can download directly the theme from the catpuccin github repository. I use the mocha flavor of the catpuccin theme. To install, copy the theme files from catpuccin alacritty and place them under the alacritty folder under .config, then add the correct import statement to refer to the right toml file:
[general]
import = [
# Provide the path to the theme flavour you want below:
"~/.config/alacritty/catppucin-theme/catppuccin-mocha.toml",
# "~/.config/alacritty/alacritty-theme/dawnfox.toml"
]I use it occasionally. Configuration is done through the GUI and results in a *.plist file which can be placed anywhere in the file system.
The file location has to be set from the GUI in the following location:
- click
iTerm2on the menu bar, then ``Settings...``` - navigate to
General>Settings - select the checkbox named
Loads settings from a custom folder or URL - click the
Browsebutton and select a path, I have chosen/Users/<username>/dotfiles/iterm2 - click the
Save Nowbutton which will savecom.googlecode.iterm2.plistin the above mentionned folder
WezTerm is a cross-platform GPU-powered terminal emulator and multiplexer configured using lua files. It provides an alternative to tmux.
The configuration file is actually a lua script, the reference can be found in the official documentation. The main idea is to create a config object, modify it with the desired options, and finally return it.
For example, changing the theme is as easy as:
-- Pull in the wezterm API
local wezterm = require("wezterm")
-- This will hold the configuration.
local config = wezterm.config_builder()
-- For example, changing the color scheme:
config.color_scheme = "Catppuccin Mocha"
return configSince I use both bash and zsh there are several files that impact the behavior of the login and interactive shells.
In order to avoid duplication, I opted for the following strategy:
- the
.profilefile contains all the aliases and cross shell methods bash:.bash_profilesources.profilethen.bashrc.bashrcsources.profile(relevant for non-login shells only)
zsh:.zprofilesources.profilethen.zshrc.zshrcsources.profile(relevant for non-login shells only)
The main reasoning is that I do not want to duplicate the variables definition and aliases for the bash and zsh configrations.
The .profile file is the original profile configuration for the Bourne shell sh, it has all aliases and export variables such as XDG_CONFIG_HOME. Also, it performs platform checks before creating aliases. As an example, the path to the iCloud drive is quite cumbersome to type.
export ICLOUD_DOCS="$HOME/Library/Mobile\ Documents/com~apple~CloudDocs/Documents"
if pathexists "$ICLOUD_DOCS"; then
alias icloud="cd $ICLOUD_DOCS"
fiThe bash configuration is done with both .bashrc and .bash_profile. The .profile configuration is also read.
The .bashrc contains the setup of external utilities starship, zoxide, etc
eval "$(starship init bash)"
eval "$(zoxide init bash)"The zsh configuration is done with both .zshrc and .zprofile. The .profile configuration is also read.
The .zshrc contains the setup of external utilities starship, zoxide, etc
eval "$(starship init bash)"
eval "$(zoxide init bash)"The starship configuration is contained in starship.toml.
I use brew as a package manager for my macos and ubuntu machines. This allows to very conviently install, update, remove packages. There is also Homebrew Cask which can install macos applications.
In order to install a package:
brew install weztermIn order to update all packages:
brew update
brew upgradebrew can be complemented with homebrew-bundle which also handles casks Mac applications, mas-cli Mac App Store applications and vscode extensions. It installs automatically when using the brew bundle command.
Dump packages to a Brewfile using:
brew bundle dump --force --describeReinstall packages:
brew bundleNOTE: brew bundle can also restore the mas dependencies, and vscode extensions.
Alternatively, a simpler solution as in here can work too.
mas is a command line interface for the Mac App Store which can be installed using brew:
brew install masIt uses numerical IDs for applications.
mas list
497799835 Xcode (16.1)
441258766 Magnet (3.0.6)
409183694 Keynote (14.2)
408981434 iMovie (10.4.3)To install an app you need its ID, which you can find by using the search commmand:
mas search XcodeThen use the returned ID to purchase (only for free apps though) the application:
mas purchase 497799835winget is the official Windows Package Manager. It has been shipped with Windows 11 for some time now.
It is the equivalent of brew for windos systems.
To be done from my windows machine.
To be done from my windows machine.
To be done from my windows machine.
uv is an extremely fast Python package and project manager.
There are no specific configuration for uv.
The configuration file for git is called .gitconfig and is expected in the $HOME folder.
The most useful setting is the user details.
Uses a config.yml file. One can use the catppuccin theme but it requires to include the content (no referencing seems possible).
ranger is a console file browser/manager.
The configuration is done using rc.conf see ranger conf as well as commands.py, see ranger command.
yazi is a modern alternative to ranger written in Rust. It is noticeably faster than ranger especially for network volumes (SMB).
The configuration is done through a yazi.toml file.
A smarter cd command. To install:
eval "$(zoxide init bash)"Not sure that this one has any dotfile at all.
btop is a resource monitor, it provides graphs for memory, cpu, and network usage.
The configuration is done using a btop.conf file, which can be edited from the tool itself. The main parameter I use is the theme and the braille graph symbol.
fzf is a general-purpose command-line fuzzy finder.
Install with:
brew install fzfon windows:
winget install fzfNo configuration file.
The configuration is contained in config.yaml. The TUI look is customized thanks to the catppuccin theme.
The most important aspect is to keep the same plugins and appearance. Obsidian keeps its settings per vault in a .obsidian folder.
Famous terminal session manager with 3 abstractions layers: session, window (within a session), and pane (splits a window in several terminals).
It does not have session persistency across reboots though but this can be fixed using a plugin.
The configuration is done using a .tmux.conf file located in .config/tmux. Remapping the prefix is the most typical setting, mine is set to C-A since the letter A is closest to Ctrl.
Other useful settings:
- Start numbering the windows and panes starting at 1. This makes switching between them easier using the shorcut
Prefix-3to move to the window number 3.
ruff is an extremely fast Python linter and code formatter, written in Rust.
uv tool install ruff@latest # Install Ruff globally.A .ruff.toml file is used (other names are accepted too). ruff supports up to 800 lint rules (autoflake, flake8, pylint, pep8..).
To run ruff as a linter.
ruff checkTo run ruff as a formatter.
ruff formatUsing the Settings sync function in vscode. Also, settings.json is saved.
The inspiration for this configuration comes from the following creators: