Skip to main content
This installation process will overwrite existing configuration files. Make sure to back up your current dotfiles before proceeding.

​
Prerequisites

Before installing, ensure you have the following:
  • Arch Linux (or Arch-based distribution)
  • Git configured with SSH access
  • Basic familiarity with terminal commands
  • Backup of existing configuration files

​
Installation Process

1

Clone the Repository

Clone the dotfiles repository to your home directory:
git clone git@github.com:joaopedroaats/dotfiles.git ~/dotfiles
The repository should be cloned to ~/dotfiles as the sync scripts expect this location.
2

First-Time Setup

For a fresh installation, run the first-sync script to set up the stot utility:
sh ~/dotfiles/first-sync.sh
This script will:
  • Create ~/.local/bin/ directory
  • Symlink the stot utility to ~/.local/bin/stot
  • Clone the packages repository for system dependencies
first-sync.sh
# Config Stot
mkdir ~/.local/bin/
[ ! -f ~/.local/bin/stot ] && ln -sv ~/dotfiles/bin/stot ~/.local/bin

# Download Packages
git clone git@github.com:joaopedroaats/packages.git ~/packages
3

Sync Configuration Files

Run the main sync script to create symlinks for all configuration files:
sh ~/dotfiles/sync.sh
This performs a hard sync of your local config files with ~/dotfiles. Existing files will be overwritten.
The sync script will link:
  • Home directory configs (.zshrc, .zshenv, .Xresources, etc.)
  • All .config/ application configurations
  • Custom binaries from bin/ to ~/.local/bin/
  • System files to /boot, /etc, /usr, and /srv (requires sudo)
4

Install System Packages

Install the required packages using the cloned packages repository:
cd ~/packages
# Follow the instructions in the packages repository
Key packages include:
  • i3-gaps — Tiling window manager
  • picom — Compositor
  • polybar — Status bar
  • rofi — Application launcher
  • dunst — Notification daemon
  • kitty — Terminal emulator
  • zsh — Shell
  • And many more…
5

Install Optional Components

​
Wallpapers

Clone the wallpapers repository:
git clone git@gitlab.com:joaopedroaa/wallpapers.git ~/Pictures/Wallpapers/

​
rEFInd Boot Theme

Install the custom rEFInd theme:
git clone git@gitlab.com:joaopedroaa/pers-rEFInd.git refind-theme
sudo cp -r refind-theme /boot/efi/EFI/refind/

​
Understanding the Stot Utility

The stot command is a custom wrapper around GNU Stow that simplifies dotfile management: 
stot [OPTION]... SOURCE
stot [OPTION]... SOURCE DEST

​
How Stot Works

1

For Home Directory Files (-l flag)

stot -l home/.zshrc /
Creates: ~/home/.zshrc → ~/dotfiles/home/.zshrc
2

For Config Directories (-l flag)

stot -l .config/i3
Creates: ~/.config/i3/* → ~/dotfiles/.config/i3/*
3

For System Files (-c flag)

stot -c etc/pacman.conf
Copies: ~/dotfiles/etc/pacman.conf → /etc/pacman.conf

​
Synced Configurations

​
Home Directory Files

stot -l home/.nvidia-settings-rc                /
stot -l home/.screenlayout-main.sh              /
stot -l home/.Xresources                        /
stot -l home/.zshenv                            /
stot -l home/.zshrc                             /

​
Application Configs

stot -l .config/alacritty
stot -l .config/doom
stot -l .config/dunst
stot -l .config/i3
stot -l .config/kitty
stot -l .config/nvim
stot -l .config/polybar
stot -l .config/ranger
stot -l .config/rofi
# ... and more

​
System Files

stot -c etc/pacman.conf
stot -c etc/hosts
stot -c etc/locale.conf
stot -c boot/efi/EFI/refind/refind.conf

​
Post-Installation

1

Restart Your Shell

exec zsh
2

Log Out and Log Back In

For i3 and other configurations to take effect, log out and select i3 as your window manager at the login screen.
3

Configure Powerlevel10k

On first run, Powerlevel10k will launch its configuration wizard:
p10k configure
4

Verify Installation

Test the custom commands:
status      # System summary
color       # Test terminal colors
PATH        # View your PATH

​
Troubleshooting

Ensure ~/.local/bin is in your PATH:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshenv
source ~/.zshenv
System file operations require sudo. The stot -c commands in sync.sh will automatically use sudo.
Ensure i3-gaps is installed and you’ve selected i3 at your display manager login screen.

​
Next Steps

Quick Start Guide

Learn how to use the configured system and custom commands