Skip to main content

​
Installation

This guide walks you through installing the dotfiles using both the automated installer and manual methods with GNU Stow.

​
Quick installation

1

Clone the repository

Clone the dotfiles repository to your home directory:
git clone https://github.com/J4yTr1n1ty/dotfiles.git ~/dotfiles
cd ~/dotfiles
2

Run the installer

Execute the installation script with sudo privileges:
sudo ./install.sh
The script needs sudo to install system packages, but it will correctly handle user-specific installations by detecting the actual user.
3

Select components

The installer presents an interactive menu where you can choose which components to install:
  • Core Shell Environment - Zsh, Tmux, Neovim (recommended)
  • Terminal Emulators - Ghostty, Kitty, Alacritty
  • Hyprland Desktop - Complete Wayland desktop environment
  • Fonts - JetBrains Mono NF, Maple Mono NF
  • Development Tools - .NET, Go, Rust, Node.js, Bun
  • Additional Utilities - htop, btop, git-delta, etc.
4

Confirm and install

Review your selections and confirm to begin the installation. The script will:
  • Install all selected packages
  • Set up configuration files using Stow
  • Configure shell defaults
  • Enable necessary services

​
Component selection

The modular installer lets you pick exactly what you need. Here’s what each component includes:

​
Core shell environment

Packages installed:
  • zsh, tmux, fzf, neovim, ranger
  • eza, zoxide, lazygit, pfetch
  • bat, fd, ripgrep
  • Oh My Posh prompt engine
Configurations applied:
  • .zshrc with Zinit plugin manager
  • Tmux config with vi-mode bindings
  • Oh My Posh theme (Zen)
  • LazyVim for Neovim
The core shell environment is recommended for all installations as it provides the foundation for terminal productivity.

​
Terminal emulators

Choose one or more terminal emulators:

Ghostty

Primary terminal with modern features (Arch only for auto-install)

Kitty

GPU-accelerated with image support

Alacritty

Minimal and fast OpenGL terminal
All terminals are configured with:
  • Consistent color schemes
  • JetBrains Mono Nerd Font
  • Optimized performance settings

​
Hyprland desktop environment

Includes: 
# Core compositor
hyprland hyprpaper

# Desktop components  
waybar wofi mako swaylock

# System utilities
brightnessctl pamixer playerctl

# Network and Bluetooth
blueman networkmanager nm-connection-editor
Configurations:
  • Hyprland with smooth animations and keybindings
  • Waybar with custom modules (battery, network, audio, etc.)
  • Wofi application launcher styling
  • Mako notification daemon theme
  • Swaylock screen locker
Hyprland auto-installation is only available on Arch Linux. On Ubuntu/Debian, you’ll need to compile it manually. The installer can still deploy the configuration files.

​
Fonts

Choose which Nerd Fonts to install:
  • JetBrains Mono NF - Primary font used throughout configs
  • Maple Mono NF - Alternative monospace font
Fonts are installed to ~/.local/share/fonts on manual installations.

​
Development tools

Available options: 
# Arch
yay -S dotnet-runtime dotnet-sdk aspnet-runtime

# Ubuntu/Debian (via Microsoft repo)
# Automatically configured by installer

​
Manual installation with Stow

If you prefer manual control or want to install on a different distribution:
1

Install prerequisites

Ensure you have Stow and Git installed:
# Arch
sudo pacman -S stow git

# Ubuntu/Debian  
sudo apt install stow git
2

Clone the repository

git clone https://github.com/J4yTr1n1ty/dotfiles.git ~/dotfiles
cd ~/dotfiles
3

Initialize submodules

The repository uses submodules for Neovim configuration:
git submodule update --init --recursive
4

Install packages manually

Install the packages you need based on the Prerequisites page.
5

Deploy configs with Stow

Stow will create symlinks from the dotfiles to your home directory:
stow .
This links all configuration files to your home directory while keeping them in the Git repository.

​
Selective deployment

If you only want specific configurations, you can stow individual directories: 
# Only Zsh configuration
stow -d ~/dotfiles -t ~ .zshrc

# Only Tmux configuration  
stow -d ~/dotfiles -t ~ .config/tmux

# Multiple specific configs
stow -d ~/dotfiles -t ~ .zshrc .config/tmux .config/nvim

​
Restowing configurations

If you need to refresh symlinks: 
cd ~/dotfiles
stow --restow .

​
Post-installation steps

After installation, complete these steps to activate everything:
1

Change default shell to Zsh

chsh -s $(which zsh)
Then log out and log back in, or start a new terminal session.
2

Install Tmux plugins

Start tmux and install plugins:
tmux
Then press Ctrl+a followed by Shift+I to install all plugins via TPM.
The installer automatically clones TPM (Tmux Plugin Manager) to ~/.tmux/plugins/tpm.
3

Activate development tools

If you installed development tools, activate them:
# Rust
source ~/.cargo/env

# Node.js via NVM
source ~/.nvm/nvm.sh
nvm use --lts

# Bun
source ~/.bun/_bun
These will be automatically sourced in new shell sessions.
4

Start Hyprland (if installed)

Log out and select Hyprland from your display manager.If you don’t have a display manager:
Hyprland
5

Enable Kanata (optional)

If you want keyboard remapping with Kanata:
systemctl --user daemon-reload
systemctl --user enable kanata.service --now
systemctl --user status kanata.service
Kanata remaps Caps Lock to Escape (tap) / Ctrl (hold). Check the service status to ensure it’s running properly.

​
Understanding GNU Stow

Stow creates symlinks from the dotfiles repository to your home directory. Here’s how it works: 
~/dotfiles/               # Source (this repository)
├── .zshrc               → ~/.zshrc
├── .bashrc              → ~/.bashrc  
├── .config/
│   ├── tmux/
│   │   └── tmux.conf    → ~/.config/tmux/tmux.conf
│   ├── nvim/            → ~/.config/nvim/
│   └── hypr/            → ~/.config/hypr/
└── ...
Benefits:
  • All configs stay in one Git repository
  • Edit files directly in the repo
  • Changes are immediately reflected in your system
  • Easy to back up, version control, and sync across machines

​
Stow ignore patterns

The .stow-local-ignore file tells Stow which files NOT to symlink: 
# Not symlinked to home directory:
.git/
.gitignore
README.md
install.sh
*.ttf
scripts/
The automated installer creates a custom ignore file to exclude components you didn’t select.

​
Verifying installation

Check that everything is working: 
# Verify Zsh is default
echo $SHELL  # Should show /usr/bin/zsh or similar

# Check Oh My Posh
oh-my-posh --version

# Test modern tools
eza --version
zoxide --version  
lazygit --version

​
Troubleshooting

​
Stow conflicts

If Stow reports conflicts with existing files: 
# Back up existing configs
mv ~/.zshrc ~/.zshrc.backup
mv ~/.config/tmux ~/.config/tmux.backup

# Then restow
cd ~/dotfiles
stow --restow .

​
Shell not changing

If chsh doesn’t work: 
# Verify Zsh is installed
which zsh

# Check current shell
echo $SHELL

# Try with full path
chsh -s /usr/bin/zsh

# Then completely log out and back in

​
Missing dependencies

If tools are missing: 
# Verify installation
which eza zoxide lazygit

# Check PATH includes ~/.local/bin
echo $PATH | grep \.local/bin

# Restart shell to reload PATH
exec zsh

​
Hyprland won’t start

Check logs for issues: 
# System journal
journalctl --user -u hyprland

# Hyprland log
cat ~/.local/share/hyprland/hyprland.log

​
Fonts not showing icons

# Verify font is installed
fc-list | grep -i jetbrains

# Refresh font cache
fc-cache -fv

# Restart terminal emulator
If you continue to have issues, check that you’ve completed all steps in the Prerequisites section.

​
Updating dotfiles

To update your dotfiles: 
cd ~/dotfiles
git pull origin main
git submodule update --recursive --remote
stow --restow .

​
Uninstalling

To remove the symlinks: 
cd ~/dotfiles
stow -D .
This removes all symlinks but keeps the repository and your configuration files intact.

​
Next steps

Now that you have the dotfiles installed:

Build docs developers (and LLMs) love

Get started for freeTalk to us